# DSS First Principles

> **The 7 foundational truths that govern all design system decisions**

---

## Principle 1: Single Source of Truth

**Design tokens are the canonical representation of design decisions.**

- All outputs derive from tokens, never the reverse
- Tokens are immutable facts; themes are interpretations
- The database is the authoritative source for all token data
- External systems query DSS; DSS does not duplicate external state

```
Source (Figma/CSS/JSON) → DSS Tokens (truth) → Outputs (CSS/SCSS/TS)
```

---

## Principle 2: Atomic Composition

**Build complexity through composition, not complexity.**

The 5-level hierarchy:

1. **Tokens** - Design variables (colors, spacing, typography)
2. **Primitives** - Base UI elements (button, input, icon)
3. **Components** - Composite UI (form field, card)
4. **Layouts** - Page structure patterns
5. **Views** - Complete screens

**Rules:**
- Each level only references the level below
- Never skip levels (components don't directly use tokens without primitives)
- Composition creates complexity; primitives stay simple

---

## Principle 3: Separation of Concerns

**Keep distinct responsibilities in distinct places.**

| Concern | Separation |
|---------|------------|
| Definition vs Application | What tokens exist ≠ How they're used |
| Source vs Output | Where tokens come from ≠ What format they export to |
| Core vs Custom | Immutable DSS standards ≠ Client-specific extensions |
| Design vs Development | Token definition ≠ Token implementation |

---

## Principle 4: Translation Over Transformation

**External systems translate TO the design system, not the reverse.**

- Legacy code maps to canonical tokens via translation dictionaries
- Never modify core to accommodate edge cases
- Custom props live in client namespace, not DSS core
- The translation layer is explicit and auditable

```
Legacy CSS → Translation Dictionary → DSS Canonical Tokens
Figma → Translation Dictionary → DSS Canonical Tokens
```

---

## Principle 5: Observable Health

**Every layer must have measurable health indicators.**

- Validation happens at system boundaries
- Errors surface immediately with actionable context
- Metrics are collected at each layer
- Health status is queryable at any time

**Health Indicators by Layer:**
| Layer | Indicators |
|-------|------------|
| Core | Database connectivity, schema validity |
| Ingestion | Parse success rate, source availability |
| Validation | Error counts, warning counts |
| State | Token coverage, consistency scores |
| Processing | Transformation success, output validity |
| Presentation | Component coverage, story completeness |
| Integration | API latency, MCP tool availability |

---

## Principle 6: Progressive Enhancement

**Start minimal, scale through composition.**

1. Start with tokens (foundation)
2. Add components when tokens are stable
3. Add layouts when components are proven
4. Scale through composition, not complexity

**Anti-patterns to avoid:**
- Building components before defining tokens
- Creating layouts before components exist
- Adding features before foundations are solid

---

## Principle 7: Documentation as Code

**Documentation lives alongside implementation.**

- Every token has a reference
- Every component has a story
- Storybook is the living documentation
- Changes to code trigger changes to docs
- Documentation is versioned with code

```
Component Code + Story + Docs = Complete Delivery
```

---

## Application

When making design system decisions, ask:

1. Does this maintain a single source of truth?
2. Does this follow atomic composition?
3. Are concerns properly separated?
4. Are we translating TO DSS, not FROM it?
5. Can we observe the health of this change?
6. Are we enhancing progressively?
7. Is this documented alongside the code?

If any answer is "no", reconsider the approach.

---

## See Also

- [Glossary](../GLOSSARY.md) - Corporate terminology
- [Architecture Overview](../architecture/OVERVIEW.md) - 7-layer system
- [Atomic Hierarchy](./ATOMIC_HIERARCHY.md) - Composition rules