A declarative, machine-readable specification for defining design systems as code, built for AI-native development.

DSS exists to solve two problems in AI-assisted development:

When an AI agent (Claude, Copilot, etc.) generates UI code, it should automatically follow the design system—using correct colors, spacing, component variants, and patterns.

How DSS helps: The dss generate --llm command produces a structured context document containing:

• Design principles and constraints
• Token values with semantic meanings
• Component specs with allowedContexts and antiPatterns
• Accessibility requirements

Include this in your AI context, and generated code follows the design system.

After code is written (by humans or AI), an agent should be able to review it and report design system violations.

How DSS helps: The dss validate command checks implementations against the spec:

• Hardcoded colors → should use CSS variables
• Invalid variant values → must match component spec
• Missing accessibility attributes → required by spec
• Anti-pattern violations → flagged in component spec

JSON output (--json) enables programmatic integration with CI or agent workflows.

• Hardcoded colors, spacing values
• Invalid component variants
• Missing alt, aria-label attributes
• Anti-patterns (multiple primary buttons, nested cards)
• Non-standard token values

• Visual correctness (does it look right?)
• Interaction behavior (does hover/focus work?)
• Semantic appropriateness (is this the right component for the use case?)
• Layout and responsive issues

For visual validation, combine DSS with visual regression testing (Chromatic, Percy).

# CLI
go install github.com/plexusone/design-system-spec/cmd/dss@latest

# Go SDK
go get github.com/plexusone/design-system-spec

my-design-system/
├── meta.json
├── foundations/
│   └── colors.json
└── components/
    └── button.json

meta.json:

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

components/button.json:

{
  "id": "Button",
  "name": "Button",
  "variants": [
    { "id": "default", "isDefault": true },
    { "id": "secondary" },
    { "id": "destructive" }
  ],
  "llm": {
    "intent": "Trigger user actions",
    "allowedContexts": ["forms", "dialogs", "toolbars"],
    "antiPatterns": ["Multiple primary buttons per view"]
  }
}

dss generate --llm ./DESIGN_CONTEXT.md

Add DESIGN_CONTEXT.md to your AI assistant's context (Claude Projects, Copilot instructions, etc.).

# Human-readable
dss validate ./src/components

# JSON for CI/agents
dss validate --json ./src/components

dss generate --llm ./DESIGN_CONTEXT.md  # LLM context (primary use case)
dss generate --css ./src/index.css      # Tailwind v4 @theme block
dss generate --types ./src/lib/types.ts # TypeScript interfaces

# Generate CSS bindings from themeBindings configuration
dss bind --output ./theme.css

# Generate TypeScript constants
dss bind --format typescript --output ./theme.ts

# Use semantic auto-mapping strategy
dss bind --strategy semantic --output ./theme.css

# Show a component's theming contract
dss contract show button

# Validate all theming contracts
dss contract validate

✓ Passed:
  Button: validated against spec

⚠ Warnings (2):
  [no-hardcoded-colors] ./src/components/Card.tsx:45
    Hardcoded color '#333' - use CSS variable from design system
  [button-accessible-name] ./src/components/IconButton.tsx:12
    Icon-only button should have aria-label

Summary: 3 checks (1 passed, 2 warnings, 0 errors)

The generated DESIGN_CONTEXT.md includes:

# My Design System

## Design Principles
- Clarity Over Complexity: ...

## Design Tokens
| Token | Value | Usage |
|-------|-------|-------|
| `primary` | `hsl(222 47% 11%)` | Primary actions and CTAs |

## Components

### Button
**Intent:** Trigger user actions
**Use in:** forms, dialogs, toolbars
**Don't use in:** inline-text, navigation

**Anti-patterns:**
- Multiple primary buttons per view
- Using button for navigation (use Link)

**Examples:**
<Button>Save</Button>
<Button variant="destructive">Delete</Button>

This structure is optimized for LLM comprehension and consistent code generation.

DSS supports formal theming contracts between component libraries and consuming applications:

Component Side (themingContract):

{
  "themingContract": {
    "prefix": "--btn",
    "tokens": [
      {
        "id": "background",
        "cssProperty": "--btn-background",
        "semantic": "primary",
        "defaultLight": "#0066CC",
        "defaultDark": "#3399FF"
      }
    ]
  }
}

Application Side (themeBindings):

{
  "themeBindings": [
    {
      "component": "button",
      "mappings": [
        { "from": "brand-primary", "to": "background" }
      ]
    }
  ]
}

Generate CSS:

dss bind --output ./theme.css

See Theming Specification for details.

Note: Figma integration is for teams transitioning from traditional design workflows. For AI-native development, DSS specs are authored directly—Figma is not required.

For teams that still use Figma:

• Tokens Studio can sync Figma variables ↔ JSON tokens
• Future: dss import figma / dss export figma commands

If your workflow is AI-first (specs authored in JSON, UI generated by AI), skip Figma entirely.

DSS defines 9 layers (most projects only need 3):

import dss "github.com/plexusone/design-system-spec/sdk/go"

ds, _ := dss.LoadDesignSystem("./my-design-system/")
ds.Validate()

// Generate for AI context
prompt, _ := ds.GenerateLLMPrompt(dss.DefaultLLMPromptOptions())

// Generate for build
css, _ := ds.GenerateCSS(dss.DefaultCSSOptions())
types, _ := ds.GenerateReactTypes(dss.DefaultReactOptions())

design-system-spec/
├── cmd/dss/              # CLI tool
│   └── cmd/
│       ├── generate.go   # Generate CSS, TypeScript, LLM
│       ├── validate.go   # Validate implementations
│       ├── bind.go       # Theme bindings generation
│       ├── contract.go   # Theming contract commands
│       └── info.go
├── sdk/go/               # Go SDK
│   ├── loader.go         # Load design systems
│   ├── theming.go        # Theming contract types
│   ├── contract_validate.go  # Contract validation
│   ├── gen_bindings.go   # Theme bindings generator
│   ├── gen_css.go        # CSS generator
│   ├── gen_react.go      # TypeScript generator
│   ├── gen_llm.go        # LLM context generator
│   ├── gen_mermaid.go    # Mermaid diagram generator
│   ├── gen_d2.go         # D2 diagram generator
│   ├── gen_w3c_tokens.go # W3C Design Tokens export
│   └── gen_docs.go       # Documentation generator
├── schema/               # JSON Schemas (generated)
├── ui/                   # Web component viewer (Lit)
└── docs/                 # MkDocs documentation

• Core SDK (9 canonical layers)
• CLI (generate, validate, info)
• Code generators (CSS, TypeScript, LLM)
• Documentation (MkDocs)
• Theming contracts and bindings
• Diagram generators (Mermaid, D2)
• W3C Design Tokens export
• Web component viewer (ui/)
• dss init scaffolding
• dss lint for spec completeness
• Advanced validation (color contrast, cross-references)
• Figma tokens import/export (for transitioning teams)

MIT