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
208 lines
7.1 KiB
Markdown
208 lines
7.1 KiB
Markdown
# DSS Core Principles
|
|
|
|
**Version 2.1.0** | Last Updated: 2025-12-09 | Status: Production
|
|
|
|
The Design System Swarm (DSS) treats design as a core architectural concern, equal to code and infrastructure. By codifying design decisions into version-controlled, immutable contracts and exposing all operations via standardized tooling, we deliver consistent, high-quality user experiences with greater velocity and traceability.
|
|
|
|
---
|
|
|
|
## The 5 Core Principles
|
|
|
|
### 1. Design is an Architectural Concern
|
|
|
|
Design decisions shape system structure, not just aesthetics. Every color, spacing, and component is a **contract** that other parts of the system depend on.
|
|
|
|
**What this means:**
|
|
- Design tokens are code-level dependencies, not styling suggestions
|
|
- Component specifications are immutable contracts (API_CONTRACTS.md)
|
|
- Design changes go through the same versioning and review as API changes
|
|
|
|
**Decision criteria:**
|
|
- Does this design change affect component contracts? → Version it
|
|
- Is this a visual tweak or structural change? → Structural = architectural
|
|
|
|
---
|
|
|
|
### 2. Contracts are Immutable and Versioned
|
|
|
|
Tier 1 files (API_CONTRACTS.md, ARCHITECTURE.md, PRINCIPLES.md) are the constitution. They change only through semantic versioning.
|
|
|
|
**What this means:**
|
|
- Breaking changes require MAJOR version bump (v1.0.0 → v2.0.0)
|
|
- Non-breaking additions require MINOR bump (v1.0.0 → v1.1.0)
|
|
- Documentation fixes require PATCH bump (v1.0.0 → v1.0.1)
|
|
- Every change includes a changelog entry
|
|
|
|
**Decision criteria:**
|
|
- Will external systems break if I change this? → Don't change it (bump version first)
|
|
- Can I add new fields without breaking old code? → Minor bump, backwards compatible
|
|
|
|
---
|
|
|
|
### 3. The System is the Single Source of Truth
|
|
|
|
Every piece of information exists in exactly ONE canonical location. No duplicates, no "also documented in...".
|
|
|
|
**What this means:**
|
|
- API endpoints documented ONCE in API_CONTRACTS.md (not repeated in README)
|
|
- Architecture decisions documented ONCE in ARCHITECTURE.md (not in project guides)
|
|
- Project status documented ONCE in PROJECT_STATUS.md (not in weekly reports)
|
|
- Use links instead of copy-paste for cross-references
|
|
|
|
**Decision criteria:**
|
|
- Does this information already exist somewhere? → Link to it, don't duplicate
|
|
- Is there conflicting information in two places? → Find the canonical source and delete the copy
|
|
|
|
---
|
|
|
|
### 4. Decisions are Explicit and Traceable
|
|
|
|
Why did we choose this? → Check the Architecture Decision Record (ADR).
|
|
|
|
**What this means:**
|
|
- Significant architectural decisions documented in `.knowledge/adrs/`
|
|
- Every ADR includes: context, decision, alternatives considered, consequences
|
|
- Code changes link to ADRs (`Implements ADR-002`)
|
|
- Decision rationale is preserved, not lost in commit messages
|
|
|
|
**Decision criteria:**
|
|
- Will someone ask "why did we do this?" in 6 months? → Document it as an ADR
|
|
- Is this a one-off technical choice or a pattern? → If pattern, it's an ADR
|
|
|
|
---
|
|
|
|
### 5. Operations are Exposed as Standardized Tools
|
|
|
|
Model Context Protocol (MCP) tools are first-class. REST endpoints wrap tools, not the reverse. Agents interact via tools; humans use tools through UIs.
|
|
|
|
**What this means:**
|
|
- Every operation (create project, sync tokens, etc.) is an MCP tool
|
|
- REST endpoints wrap tools, not standalone logic
|
|
- Agents have full autonomy via tools
|
|
- All operations logged in audit trail
|
|
|
|
**Decision criteria:**
|
|
- Is this a new capability? → Create as MCP tool first, then REST endpoint wraps it
|
|
- Should humans or agents do this? → Humans use tool through UI, agents use directly
|
|
|
|
---
|
|
|
|
## How These Principles Work Together
|
|
|
|
```
|
|
Design Decisions (Principle 1)
|
|
↓
|
|
Version in Contracts (Principle 2)
|
|
↓
|
|
Document in Single Location (Principle 3)
|
|
↓
|
|
Record Why in ADR (Principle 4)
|
|
↓
|
|
Expose as MCP Tool (Principle 5)
|
|
↓
|
|
Governed by Admin Standards (Admin Principles)
|
|
```
|
|
|
|
---
|
|
|
|
## Admin & Operational Standards
|
|
|
|
The administration of the DSS is governed by a specific set of operational standards that extend these core principles.
|
|
|
|
**See [ADMIN_PRINCIPLES.md](./ADMIN_PRINCIPLES.md) for the detailed specification.**
|
|
|
|
**Key Admin Principles:**
|
|
1. **Visibility**: Transparent system state (Glass Box).
|
|
2. **Authority**: Decisions bounded by contracts (No God Mode).
|
|
3. **Accountability**: All actions audited and attributed.
|
|
4. **Partnership**: Distinct roles for Developers and Admins.
|
|
5. **Isolation**: Admin plane survives User plane failures.
|
|
|
|
---
|
|
|
|
## What to Do When Principles Conflict
|
|
|
|
Use this hierarchy:
|
|
|
|
1. **Contracts are Immutable** (highest priority)
|
|
2. **Single Source of Truth**
|
|
3. **Operations as Tools**
|
|
4. **Decisions Traceable**
|
|
5. **Design is Architecture** (lowest priority)
|
|
|
|
**Example**: If MCP tooling would break an API contract → Keep the contract, deprecate the old tool, introduce new one in next major version.
|
|
|
|
---
|
|
|
|
## For Different Audiences
|
|
|
|
**New Developer:**
|
|
1. Read this file (5 min)
|
|
2. Read DOCUMENTATION_GUIDE.md (10 min)
|
|
3. Start with QUICK_REFERENCE.md for your task
|
|
|
|
**Making a Decision:**
|
|
1. Will this break a contract? (Principle 2)
|
|
2. Will this duplicate existing info? (Principle 3)
|
|
3. Should this be an MCP tool? (Principle 5)
|
|
4. Document in an ADR if significant (Principle 4)
|
|
|
|
**Doing Code Review:**
|
|
- Does this create duplicate documentation? ✗
|
|
- Is the version updated? ✓
|
|
- Should this be an MCP tool? ✓
|
|
- Is there an ADR for this decision? (if major change) ✓
|
|
|
|
---
|
|
|
|
## Key Documents
|
|
|
|
- **API_CONTRACTS.md**: Endpoint specifications (immutable, versioned)
|
|
- **ARCHITECTURE.md**: System design and structure (immutable, versioned)
|
|
- **ADMIN_PRINCIPLES.md**: Operational standards and admin governance
|
|
- **PROJECT_STATUS.md**: Current state (updated weekly, not immutable)
|
|
- **IMPLEMENTATION_SUMMARY.md**: Feature inventory by phase
|
|
- **.knowledge/adrs/**: Decision records (why we chose this way)
|
|
- **DOCUMENTATION_GUIDE.md**: Map of all documentation (where to find what)
|
|
- **BEST_PRACTICES.md**: How to apply principles (implementation patterns)
|
|
- **ANTI_PATTERNS_AND_LEARNINGS.md**: What not to do (and why)
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
- ✅ No duplicate documentation (links used instead)
|
|
- ✅ All major decisions in `.knowledge/adrs/`
|
|
- ✅ Tier 1 files (contracts) never change without version bump
|
|
- ✅ PROJECT_STATUS.md updated weekly
|
|
- ✅ All operations have MCP tools (REST wraps tools)
|
|
- ✅ New developer can start coding in 30 min (read QUICK_REFERENCE → DOCUMENTATION_GUIDE → relevant guide)
|
|
- ✅ Team asks "which principle applies here?" before PRs
|
|
|
|
---
|
|
|
|
## Evolution Path
|
|
|
|
**Year 1 (Now)**: Manual enforcement
|
|
- Team follows principles consciously
|
|
- Pre-commit hooks catch violations
|
|
- CI/CD validates consistency
|
|
|
|
**Year 2**: Automation
|
|
- Generate semver from change detection
|
|
- Auto-generate changelogs
|
|
- Tools self-discover from API schema
|
|
|
|
**Year 3**: Code-from-Graph
|
|
- ARCHITECTURE.md generates TypeScript types
|
|
- API_CONTRACTS.md generates OpenAPI + SDK types
|
|
- ADRs generate test suites
|
|
- Rules become executable code
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-09
|
|
**Version**: 2.2.0 (Integrated 6-principle Admin framework)
|
|
**Previous Version**: 2.1.0
|
|
**Status**: PRODUCTION - All principles active and enforced
|