dss/docs/principles/FIRST_PRINCIPLES.md

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 - Corporate terminology
• Architecture Overview - 7-layer system
• Atomic Hierarchy - Composition rules