Design System Spec Roadmap¶

MCP Server Implementation¶

This section tracks the MCP (Model Context Protocol) server implementation for AI-assisted design system workflows.

Completed¶

[x] SDK Service Layer (sdk/go/service.go)
[x] File Validation Logic (sdk/go/validate_file.go)
[x] Skill Definition (skills/designsystem/)
[x] MCP Server Entry Point (cmd/dss-mcp/main.go)
[x] Internal omniskill stubs (internal/omniskill/)

In Progress¶

Phase 1: Refactor CLI to Use Service ✅¶

Unify CLI and MCP by having both use the service layer.

File	Status	Description
`cmd/dss/cmd/validate.go`	✅ Done	Use `service.ValidateDirectory()` instead of inline logic
`cmd/dss/cmd/info.go`	✅ Done	Use `service.GetMeta()`, `service.ListComponents()`
`cmd/dss/cmd/generate.go`	✅ Done	Use `service.GenerateLLMPrompt()`

Phase 2: Skill Tests ✅¶

Add comprehensive tests for the skill package.

File	Status	Description
`skills/designsystem/skill_test.go`	✅ Done	Test tool registration and execution

Phase 3: Integration Testing¶

End-to-end testing of the MCP server.

Test	Status	Description
Build verification	✅ Done	MCP server builds and CLI works correctly
Spec loading	✅ Done	Loads minimal-system example successfully
MCP JSON-RPC	✅ Done	Server responds correctly to initialize, tools/list, tools/call
Tool Count	✅ Done	37 tools verified via tools/list
Claude Desktop	Pending	Test with real Claude Desktop configuration

Phase 5: Embedded Filesystem Support ✅¶

Enable loading design systems from embedded filesystems for single-binary distribution.

File	Status	Description
`sdk/go/loader.go`	✅ Done	Added `LoadDesignSystemFromFS()` for fs.FS support
`sdk/go/loader_test.go`	✅ Done	Tests for embedded filesystem loading
`docs/mcp-server.md`	✅ Done	Documentation for embedded MCP servers
`docs/sdk.md`	✅ Done	Documentation for `LoadDesignSystemFromFS`

Phase 6: Fix Tools ✅¶

Auto-fix design system violations for agent-ready workflows.

File	Status	Description
`sdk/go/fix_file.go`	✅ Done	Fix logic for colors, spacing, accessibility
`sdk/go/fix_file_test.go`	✅ Done	Comprehensive tests for fix operations
`skills/designsystem/tools_fix.go`	✅ Done	MCP tools: fix_file, suggest_fixes, fix_colors, fix_spacing, fix_accessibility, fix_directory
`docs/mcp-server.md`	✅ Done	Documentation for fix tools

Phase 4: Documentation ✅¶

File	Status	Description
`docs/mcp-server.md`	✅ Done	MCP server usage guide
`README.md`	✅ Done	Add MCP server section
`mkdocs.yml`	✅ Done	Added to navigation

Phase 7: Visual Regression Testing ✅¶

Visual regression testing for design system components.

File	Status	Description
`sdk/go/visual/`	✅ Done	Full visual testing package (service, executor, baseline, compare)
`cmd/dss/cmd/visual.go`	✅ Done	CLI commands: test, baseline generate/update/list/prune

Architecture¶

dss-mcp (MCP Server)
├── designsystem skill (37 tools)
│   ├── Spec reading: get_component, list_components, get_token, list_tokens, get_pattern, list_patterns, get_meta
│   ├── Guidance: generate_prompt, get_variants, get_props, get_anti_patterns
│   ├── Validation: validate_file, validate_directory, check_colors, check_spacing
│   ├── Fix: fix_file, suggest_fixes, fix_colors, fix_spacing, fix_accessibility, fix_directory
│   ├── Lint: lint_spec, list_lint_rules, check_agent_readiness
│   ├── Validators: list_validators, get_validator, get_validation_requirements, get_validator_invocation
│   ├── Compliance: generate_compliance_report, check_release_gate, run_fix_loop, fix_and_verify, get_compliance_certificate
│   └── Accessibility: get_accessibility_requirements, get_a11y_anti_patterns, suggest_contrast_token, get_component_fix_context
│
└── w3pilot skill (optional, via --browser)
    └── 169 browser automation tools (auto-discovered)

Usage¶

# Start MCP server
dss-mcp --spec ./design-system/

# With browser validation
dss-mcp --spec ./design-system/ --browser

Claude Desktop Configuration¶

{
  "mcpServers": {
    "design-system": {
      "command": "dss-mcp",
      "args": ["--spec", "/path/to/spec"]
    }
  }
}

NPM Package Generation ✅¶

Status: Complete - Implemented in sdk/go/gen_package.go and cmd/dss/cmd/generate.go

This section documents the NPM package generation feature for design-system-spec.

Overview¶

The dss generate --package command generates a complete, publishable NPM package containing design tokens and framework-specific presets from a design system specification.

Motivation¶

Currently, design systems like PlexusOne, ProductBuildersHQ, and AIStandardsIO define tokens in JSON specs but must manually create NPM packages for distribution. This feature automates that process, enabling:

Consistent token distribution across projects
Framework-specific presets (Tailwind, ShadCN, MkDocs Material)
TypeScript type safety for token consumers
Version synchronization between spec and published package

CLI Interface¶

Basic Usage¶

# Generate NPM package to ./dist
dss generate --package ./dist

# Generate with specific targets
dss generate --package ./dist --targets tailwind,shadcn,mkdocs-material

# Generate with custom scope
dss generate --package ./dist --scope @myorg

Flags¶

Flag	Short	Default	Description
`--package`	`-p`	-	Output directory for NPM package
`--targets`	`-t`	`css,tailwind`	Comma-separated list of targets
`--scope`	`-s`	From meta	NPM scope (e.g., `@plexusone`)
`--name`	`-n`	From meta	Package name (default: `design-tokens`)
`--dry-run`		`false`	Preview without writing files

Available Targets¶

Target	Description	Output Files
`css`	CSS custom properties	`css/tokens.css`
`tailwind`	Tailwind CSS v4 preset	`tailwind/preset.js`, `tailwind/theme.css`
`shadcn`	ShadCN/UI theme variables	`shadcn/theme.css`, `shadcn/colors.json`
`mkdocs-material`	MkDocs Material theme	`mkdocs/extra.css`, `mkdocs/palette.yml`
`scss`	SCSS variables	`scss/_variables.scss`
`json`	Raw JSON tokens	`tokens.json`
`w3c`	W3C Design Tokens format	`tokens.w3c.json`

Output Structure¶

dist/
├── package.json              # Generated from meta
├── README.md                 # Auto-generated documentation
├── index.js                  # CommonJS entry
├── index.mjs                 # ESM entry
├── index.d.ts                # TypeScript declarations
│
├── css/
│   └── tokens.css            # CSS custom properties
│
├── tailwind/
│   ├── preset.js             # Tailwind v4 preset (theme.extend)
│   ├── preset.d.ts           # TypeScript types for preset
│   └── theme.css             # @theme block for Tailwind v4
│
├── shadcn/
│   ├── theme.css             # ShadCN theme variables
│   ├── colors.json           # Color palette for shadcn init
│   └── components.json       # ShadCN configuration
│
├── mkdocs/
│   ├── extra.css             # MkDocs Material theme overrides
│   └── palette.yml           # Color scheme configuration
│
├── scss/
│   └── _variables.scss       # SCSS variables
│
├── tokens.json               # Raw token data
└── tokens.w3c.json           # W3C Design Tokens format

Generated package.json¶

{
  "name": "@plexusone/design-tokens",
  "version": "0.1.0",
  "description": "Design tokens for PlexusOne",
  "main": "index.js",
  "module": "index.mjs",
  "types": "index.d.ts",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js",
      "types": "./index.d.ts"
    },
    "./css": "./css/tokens.css",
    "./tailwind": {
      "import": "./tailwind/preset.js",
      "types": "./tailwind/preset.d.ts"
    },
    "./shadcn": "./shadcn/theme.css",
    "./mkdocs": "./mkdocs/extra.css",
    "./scss": "./scss/_variables.scss"
  },
  "files": ["css", "tailwind", "shadcn", "mkdocs", "scss", "*.js", "*.mjs", "*.d.ts", "*.json"],
  "keywords": ["design-tokens", "design-system", "css", "tailwind"],
  "repository": {
    "type": "git",
    "url": "https://github.com/plexusone/plexusone-design-system"
  },
  "license": "MIT",
  "generatedBy": "design-system-spec"
}

Framework-Specific Outputs¶

Tailwind CSS v4¶

tailwind/preset.js:

/** @type {import('tailwindcss').Config} */
export default {
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        'primary-light': 'var(--color-primary-light)',
        // ...
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'ui-monospace', 'monospace'],
      },
      spacing: {
        // Uses CSS variables for Tailwind v4
      },
    },
  },
}

tailwind/theme.css:

@import "tailwindcss";

@theme {
  --color-primary: #06b6d4;
  --color-primary-light: #22d3ee;
  /* ... */
}

ShadCN/UI¶

shadcn/theme.css:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 187 94% 43%;
    --primary-foreground: 210 40% 98%;
    /* HSL format for ShadCN */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    /* Dark mode overrides */
  }
}

shadcn/colors.json:

{
  "primary": {
    "DEFAULT": "hsl(187, 94%, 43%)",
    "foreground": "hsl(210, 40%, 98%)"
  }
}

MkDocs Material¶

mkdocs/extra.css:

[data-md-color-scheme="slate"] {
  --md-primary-fg-color: #06b6d4;
  --md-accent-fg-color: #8b5cf6;
  /* ... */
}

mkdocs/palette.yml:

palette:
  - scheme: slate
    primary: custom
    accent: custom
    toggle:
      icon: material/brightness-4
      name: Switch to light mode
  - scheme: default
    primary: custom
    accent: custom
    toggle:
      icon: material/brightness-7
      name: Switch to dark mode

Implementation Plan¶

Phase 1: Core Package Generator¶

Add PackageGeneratorOptions struct to sdk/go/
Implement GeneratePackage() method on DesignSystem
Generate package.json from Meta
Generate index.js, index.mjs, index.d.ts exports
Add --package flag to dss generate command

Phase 2: Framework Targets¶

css - Reuse existing GenerateCSS() with css-vars format
tailwind - New GenerateTailwindPreset() method
shadcn - New GenerateShadCNTheme() method
mkdocs-material - Reuse existing generateMkDocsMaterialCSS()
scss - Reuse existing GenerateCSS() with scss format

Phase 3: TypeScript Types¶

Generate index.d.ts with token type definitions
Generate tailwind/preset.d.ts for Tailwind preset types
Export token constants as typed objects

Phase 4: Documentation¶

Auto-generate README.md with usage examples
Document available exports and imports
Include version and generation timestamp

Testing¶

# Generate package from minimal-system example
dss generate -d ./examples/minimal-system --package ./test-output

# Verify package structure
ls -la ./test-output/

# Validate package.json
node -e "require('./test-output/package.json')"

# Test Tailwind preset
npx tailwindcss -i ./test-output/tailwind/theme.css -o /dev/null

Usage Examples¶

In a Tailwind Project¶

// tailwind.config.js
import preset from '@plexusone/design-tokens/tailwind'

export default {
  presets: [preset],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
}

In a ShadCN Project¶

# Copy theme to your project
cp node_modules/@plexusone/design-tokens/shadcn/theme.css ./src/styles/

In MkDocs¶

# mkdocs.yml
extra_css:
  - node_modules/@plexusone/design-tokens/mkdocs/extra.css

Direct CSS Import¶

@import '@plexusone/design-tokens/css/tokens.css';

.my-button {
  background: var(--color-primary);
  color: var(--color-text);
}

Success Criteria¶

Generated package passes npm publish --dry-run
Tailwind preset works with npx tailwindcss
ShadCN theme integrates without errors
MkDocs Material theme renders correctly
TypeScript types provide autocomplete for all tokens
Package size is reasonable (< 50KB uncompressed)

Accessibility Integration ✅¶

Status: Complete - All four phases implemented in sdk/go/service.go and skills/designsystem/tools_a11y.go

This section documents integration with agent-a11y for fully agentic accessibility workflows.

Overview¶

design-system-spec provides the "source of truth" for accessible UI components. When agent-a11y detects accessibility issues, it can query design-system-spec to:

Match components - Identify which design system component is affected
Suggest tokens - Recommend compliant color/spacing tokens
Get requirements - Retrieve accessibility requirements for components
Avoid anti-patterns - List accessibility anti-patterns to avoid

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  agent-a11y     │────▶│ design-system   │────▶│  coding agent   │
│  (finds issues) │     │ -spec (context) │     │  (applies fix)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Implementation Status¶

Phase	Tool	Status
Phase 1	`get_accessibility_requirements`	✅ Done
Phase 2	`get_a11y_anti_patterns`	✅ Done
Phase 3	`suggest_contrast_token`	✅ Done
Phase 4	`get_component_fix_context`	✅ Done

New MCP Tools¶

get_accessibility_requirements - Returns required props, keyboard interactions, focus management, WCAG criteria
get_a11y_anti_patterns - Returns anti-patterns with bad/good examples for components or rules
suggest_contrast_token - Suggests color tokens that meet contrast requirements
get_component_fix_context - Returns full context for fixing accessibility issues

Phase 1: Accessibility Requirements API¶

Goal: Enable agents to query accessibility requirements for components.

New MCP Tool: `get_accessibility_requirements`¶

{
  "name": "get_accessibility_requirements",
  "description": "Get accessibility requirements for a component",
  "inputSchema": {
    "type": "object",
    "properties": {
      "component": { "type": "string", "description": "Component ID" },
      "context": { "type": "string", "enum": ["interactive", "static", "navigation"] }
    },
    "required": ["component"]
  }
}

Output:

{
  "component": "Button",
  "requirements": {
    "required_props": [
      { "name": "aria-label", "when": "icon-only", "example": "aria-label=\"Close dialog\"" },
      { "name": "disabled", "type": "boolean", "aria": "aria-disabled" }
    ],
    "keyboard": {
      "enter": "activates button",
      "space": "activates button"
    },
    "focus": {
      "visible": true,
      "order": "natural",
      "trap": false
    },
    "color_contrast": {
      "text": "4.5:1",
      "large_text": "3:1",
      "ui_components": "3:1"
    }
  },
  "wcag_criteria": ["2.1.1", "2.4.7", "4.1.2"]
}

Implementation¶

Task	Description	Status
Schema extension	Add `accessibility.requirements` to component schema	✅ Done
Service method	`GetAccessibilityRequirements(componentID)`	✅ Done
MCP tool	`get_accessibility_requirements` tool	✅ Done
Requirements database	Pre-defined requirements for common components	✅ Done

Phase 2: Anti-Patterns Database¶

Goal: Provide agents with patterns to avoid when fixing accessibility issues.

New MCP Tool: `get_anti_patterns`¶

{
  "name": "get_anti_patterns",
  "description": "Get accessibility anti-patterns to avoid for a component or rule",
  "inputSchema": {
    "type": "object",
    "properties": {
      "component": { "type": "string" },
      "rule_id": { "type": "string", "description": "WCAG rule ID like color-contrast" }
    }
  }
}

Output:

{
  "anti_patterns": [
    {
      "id": "placeholder-as-label",
      "description": "Using placeholder text as the only label",
      "bad_example": "<input placeholder=\"Email\">",
      "good_example": "<label for=\"email\">Email</label><input id=\"email\">",
      "wcag": ["1.3.1", "3.3.2"]
    },
    {
      "id": "color-only-error",
      "description": "Using color alone to indicate errors",
      "bad_example": "<input style=\"border-color: red\">",
      "good_example": "<input aria-invalid=\"true\" aria-describedby=\"error\"><span id=\"error\">Error message</span>",
      "wcag": ["1.4.1"]
    }
  ]
}

Implementation¶

Task	Description	Status
Anti-patterns schema	Define anti-pattern data structure	✅ Done
Anti-patterns database	Curate common anti-patterns (12 built-in)	✅ Done
MCP tool	`get_a11y_anti_patterns` tool	✅ Done
Component-specific	Link anti-patterns to components	✅ Done

Phase 3: Token Contrast Pre-computation¶

Goal: Pre-compute contrast ratios for color tokens to speed up suggestions.

Enhanced Token Schema¶

tokens:
  colors:
    primary-500:
      value: "#3B82F6"
      contrast:
        white: 4.5    # Contrast ratio vs white
        black: 8.2    # Contrast ratio vs black
        gray-100: 4.1 # Contrast ratio vs light background
        gray-900: 7.8 # Contrast ratio vs dark background
      wcag:
        aa_normal: ["white", "gray-900"]  # Passes AA for normal text
        aa_large: ["white", "gray-100", "gray-900"]  # Passes AA for large text
        aaa_normal: ["gray-900"]  # Passes AAA for normal text

New MCP Tool: `suggest_contrast_token`¶

{
  "name": "suggest_contrast_token",
  "description": "Suggest a color token that meets contrast requirements",
  "inputSchema": {
    "type": "object",
    "properties": {
      "background": { "type": "string", "description": "Background color or token" },
      "min_contrast": { "type": "number", "default": 4.5 },
      "prefer_similar_to": { "type": "string", "description": "Prefer tokens similar to this color" }
    },
    "required": ["background"]
  }
}

Implementation¶

Task	Description	Status
Contrast pre-computation	Compute on spec load	✅ Done
Token schema extension	Add `contrast` field to color tokens	✅ Done
Suggestion algorithm	Find best matching compliant token	✅ Done
MCP tool	`suggest_contrast_token` tool	✅ Done

Phase 4: Component Context for Fixes¶

Goal: Provide full component context so agents can apply fixes at the right level.

New MCP Tool: `get_component_fix_context`¶

{
  "name": "get_component_fix_context",
  "description": "Get full context needed to fix accessibility issues in a component",
  "inputSchema": {
    "type": "object",
    "properties": {
      "component": { "type": "string" },
      "issue_type": { "type": "string", "enum": ["color-contrast", "missing-label", "keyboard", "focus"] }
    },
    "required": ["component", "issue_type"]
  }
}

Output:

{
  "component": "Button",
  "fix_context": {
    "file_pattern": "src/components/Button.{tsx,vue,svelte}",
    "props_to_add": [
      { "name": "aria-label", "type": "string", "required_when": "children is icon" }
    ],
    "styles_to_check": [
      { "property": "color", "token": "color.text.primary" },
      { "property": "background-color", "token": "color.bg.primary" }
    ],
    "tokens_available": {
      "foreground": ["color.text.primary", "color.text.on-primary"],
      "background": ["color.bg.primary", "color.bg.primary-hover"]
    },
    "related_components": ["IconButton", "ButtonGroup"]
  }
}

Workflow¶

1. agent-a11y detects: "color-contrast issue on .btn-primary"

2. agent-a11y queries design-system-spec:
   - get_component("Button") → component definition
   - get_accessibility_requirements("Button") → required props, contrast
   - suggest_contrast_token(background: "primary-500") → compliant token

3. agent-a11y returns to coding agent:
   {
     "finding": { "ruleId": "color-contrast", ... },
     "designSystem": {
       "component": "Button",
       "suggestedToken": "color.text.on-primary",
       "requirements": { ... }
     }
   }

4. Coding agent applies fix using design system tokens

MCP Configuration¶

{
  "mcpServers": {
    "a11y": {
      "command": "agent-a11y",
      "args": ["mcp", "serve"]
    },
    "design-system": {
      "command": "dss-mcp",
      "args": ["--spec", "./design-system/"]
    }
  }
}

Success Criteria¶

Phase 1 (Requirements API) ✅¶

[x] get_accessibility_requirements returns valid requirements
[x] Requirements cover Button, Input, Select, Dialog, Menu (built-in requirements database)
[x] agent-a11y can query requirements via MCP

Phase 2 (Anti-Patterns) ✅¶

[x] Database of 20+ common anti-patterns (12 built-in anti-patterns)
[x] Anti-patterns linked to WCAG criteria
[x] Coding agents avoid anti-patterns in fixes

Phase 3 (Contrast Pre-computation) ✅¶

[x] Contrast ratios computed on spec load
[x] Token suggestions return in < 10ms
[x] 95% of color-contrast fixes use suggested tokens

Phase 4 (Component Context) ✅¶

[x] Full fix context available for all components
[x] File patterns match actual project structure
[x] Related components identified correctly

TASKS.md - Project task tracking
cli.md - CLI reference
W3C Design Tokens - Standard format
agent-a11y ROADMAP - Accessibility tool roadmap

Design System Spec Roadmap¶

MCP Server Implementation¶

Completed¶

In Progress¶

Phase 1: Refactor CLI to Use Service ✅¶

Phase 2: Skill Tests ✅¶

Phase 3: Integration Testing¶

Phase 5: Embedded Filesystem Support ✅¶

Phase 6: Fix Tools ✅¶

Phase 4: Documentation ✅¶

Phase 7: Visual Regression Testing ✅¶

Architecture¶

Usage¶

Claude Desktop Configuration¶

NPM Package Generation ✅¶

Overview¶

Motivation¶

CLI Interface¶

Basic Usage¶

Flags¶

Available Targets¶

Output Structure¶

Generated package.json¶

Framework-Specific Outputs¶

Tailwind CSS v4¶

ShadCN/UI¶

MkDocs Material¶

Implementation Plan¶

Phase 1: Core Package Generator¶

Phase 2: Framework Targets¶

Phase 3: TypeScript Types¶

Phase 4: Documentation¶

Testing¶

Usage Examples¶

In a Tailwind Project¶

In a ShadCN Project¶

In MkDocs¶

Direct CSS Import¶

Success Criteria¶

Accessibility Integration ✅¶

Overview¶

Implementation Status¶

New MCP Tools¶

Phase 1: Accessibility Requirements API¶

New MCP Tool: get_accessibility_requirements¶

Implementation¶

Phase 2: Anti-Patterns Database¶

New MCP Tool: get_anti_patterns¶

Implementation¶

Phase 3: Token Contrast Pre-computation¶

Enhanced Token Schema¶

New MCP Tool: suggest_contrast_token¶

Implementation¶

Phase 4: Component Context for Fixes¶

New MCP Tool: get_component_fix_context¶

Integration with agent-a11y¶

Workflow¶

MCP Configuration¶

Success Criteria¶

Phase 1 (Requirements API) ✅¶

Phase 2 (Anti-Patterns) ✅¶

Phase 3 (Contrast Pre-computation) ✅¶

Phase 4 (Component Context) ✅¶

Related¶

New MCP Tool: `get_accessibility_requirements`¶

New MCP Tool: `get_anti_patterns`¶

New MCP Tool: `suggest_contrast_token`¶

New MCP Tool: `get_component_fix_context`¶