Specification Overview

DSS defines 9 canonical layers for complete design system specification. Each layer serves a specific purpose and can be defined in separate JSON/YAML files or combined.

Layer Summary

Layer	File(s)	Purpose
Meta	meta.json	System name, version, maintainers
Principles	principles.json	Design philosophy and guidelines
Foundations	foundations/*.json	Design tokens (colors, typography, spacing)
Components	components/*.json	UI elements with variants, states, props
Patterns	patterns/*.json	Multi-component solutions
Templates	templates/*.json	Page-level layouts
Content	content.json	Voice & tone guidelines
Accessibility	accessibility.json	WCAG compliance requirements
Governance	governance.json	Versioning and deprecation policies

Directory Structure

A complete design system spec typically follows this structure:

my-design-system/
├── meta.json                 # Required: name, version
├── principles.json           # Design philosophy
├── accessibility.json        # WCAG requirements
├── governance.json           # Policies
├── content.json              # Voice & tone
├── foundations/
│   ├── colors.json           # Color tokens
│   ├── typography.json       # Font definitions
│   ├── spacing.json          # Spacing scale
│   └── border-radius.json    # Border radius values
├── components/
│   ├── button.json           # Button component spec
│   ├── card.json             # Card component spec
│   └── input.json            # Input component spec
├── patterns/
│   └── form.json             # Form pattern spec
└── templates/
    └── dashboard.json        # Dashboard template

Minimal Example

The minimum required spec is just meta.json:

{
  "name": "My Design System",
  "version": "1.0.0"
}

Loading Behavior

The DSS loader:

1. Looks for meta.json in the specified directory
2. Loads principles.json, accessibility.json, etc. if present
3. Scans foundations/, components/, patterns/, templates/ subdirectories
4. Merges all files into a single DesignSystem object
5. Validates the combined spec

File Formats

DSS supports both JSON and YAML:

// colors.json
{
  "colors": [
    { "id": "primary", "value": "#0066CC" }
  ]
}

# colors.yaml
colors:
  - id: primary
    value: "#0066CC"

LLM Context

Any component, pattern, or template can include an llm field for AI code generation optimization:

{
  "llm": {
    "intent": "What this element is for",
    "allowedContexts": ["where-to-use-it"],
    "forbiddenContexts": ["where-not-to-use-it"],
    "antiPatterns": ["common mistakes to avoid"],
    "exampleUsage": ["<Component>Example</Component>"]
  }
}

See Components for full LLM context documentation.