276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
145 lines
4.0 KiB
Markdown
145 lines
4.0 KiB
Markdown
# 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
|