design-system-spec

Design System Spec

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

Primary Goals

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

1. AI Agents Build Compliant UI

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.

2. AI Agents Review Code for Compliance

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.

Assessment: How Well Does DSS Achieve These Goals?

What DSS Catches

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

What DSS Cannot Catch

• 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).

Installation

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

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

Quick Start

1. Create a 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"]
  }
}

2. Generate LLM Context

dss generate --llm ./DESIGN_CONTEXT.md

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

3. Validate Implementations

# Human-readable
dss validate ./src/components

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

CLI Commands

Generate Options

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

Validate Output

✓ 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)

LLM Context Structure

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.

Figma Integration

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.

Canonical Layers

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

Go SDK

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())

Project Structure

design-system-spec/
├── cmd/dss/           # CLI tool
│   └── cmd/
│       ├── generate.go
│       ├── validate.go
│       └── info.go
├── sdk/go/            # Go SDK
│   ├── loader.go
│   ├── gen_css.go
│   ├── gen_react.go
│   └── gen_llm.go
├── schema/            # JSON Schemas
└── docs/              # MkDocs documentation

Roadmap

• Core SDK (9 canonical layers)
• CLI (generate, validate, info)
• Code generators (CSS, TypeScript, LLM)
• Documentation (MkDocs)
• dss init scaffolding
• dss lint for spec completeness
• Advanced validation (color contrast, cross-references)
• Figma tokens import/export (for transitioning teams)

License

MIT