# 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