Initial commit: Clean DSS implementation
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
This commit is contained in:
Digital Production Factory
207
docs/01_core/PRINCIPLES.md
Normal file
207
docs/01_core/PRINCIPLES.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user