Release Notes - v0.5.0

Release Date: 2026-07-13

Highlights

• MCP Server with 37 Tools - Complete Model Context Protocol server enabling AI assistants to query, validate, and fix design system violations
• Visual Regression Testing - Screenshot-based testing with w3pilot integration, ImageMagick/Go comparison, and baseline management
• Evaluation System - Rubric-based spec evaluation with structured-evaluation integration
• HTML Documentation Generator - Self-contained documentation with Material Web live demos
• Accessibility Integration - Four-phase a11y tools for agent-a11y integration
• Compliance & Release Workflow - Go/no-go release gates with fix-validate loops

What's New

MCP Server (37 Tools)

The dss-mcp command exposes your design system as a Model Context Protocol server, enabling AI assistants like Claude to directly query and validate against your spec.

Installation:

go install github.com/plexusone/design-system-spec/cmd/dss-mcp@v0.5.0

Claude Desktop Configuration:

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

Tool Categories:

Category	Tools	Purpose
Spec Reading	7	Query components, tokens, patterns, meta
Guidance	4	Generate prompts, get variants, props, anti-patterns
Validation	4	Validate files/directories, check colors/spacing
Fix	6	Auto-fix colors, spacing, accessibility violations
Lint	3	Spec completeness and agent-readiness checking
Validators	4	External validator discovery and delegation
Compliance	5	Release gates, compliance reports, certificates
Accessibility	4	A11y requirements, contrast suggestions, fix context

Visual Regression Testing

Screenshot-based visual regression testing using w3pilot for browser automation.

Features:

• YAML/JSON test definitions with viewport and stabilization options
• Parallel test execution with configurable worker pool
• ImageMagick comparison with anti-aliasing tolerance (Go fallback available)
• Versioned baseline management with SHA256 checksums
• Diff image generation highlighting pixel differences

CLI Commands:

dss visual test                           # Run visual tests
dss visual baseline generate v1.0.0       # Create baseline
dss visual baseline update v1.0.0         # Update specific tests
dss visual baseline list                  # List available versions

Test Definition Example:

version: "1.0"
name: "My Component Tests"
tests:
  - id: button-primary
    url: http://localhost:3000/components/button
    selector: ".button-primary"
    viewports:
      - { width: 1920, height: 1080 }
      - { width: 375, height: 812 }

Evaluation System

Rubric-based evaluation using structured-evaluation for consistent scoring.

Categories (weighted):

• Completeness (25%): Required fields, no gaps
• Agent-Readiness (30%): LLM context, anti-patterns, examples
• Accessibility (25%): WCAG, keyboard, screen reader support
• Documentation (20%): Descriptions, usage guidance

CLI:

dss eval --dir ./specs --json > evals/v3.json
dss eval --dir ./specs --min-score 80  # Require minimum score

HTML Documentation Generator

Generate self-contained HTML documentation with embedded Material Web component demos.

Features:

• PlexusOne unified navigation integration
• Dark/light theme toggle
• Live Material Web component demos via CDN
• Variant selector and disabled state controls
• Component gallery with token visualization
• Evaluation dashboard with coverage metrics

CLI:

dss render --dir ./specs/v3 --output ./docs/v3 --title "Material Design 3"
dss render --dir ./specs/v3 --output ./docs --mkdocs  # MkDocs-compatible

Accessibility Integration

Four-phase integration for agent-a11y compatibility.

New Tools:

Tool	Purpose
get_accessibility_requirements	Required props, keyboard interactions, focus management
get_a11y_anti_patterns	Common a11y mistakes with bad/good examples
suggest_contrast_token	Color tokens meeting WCAG contrast requirements
get_component_fix_context	Full fix context for specific a11y issues

Compliance & Release Workflow

End-to-end release workflow support.

New Tools:

Tool	Purpose
generate_compliance_report	Full validation report with categorized scoring
check_release_gate	Go/no-go decision with blocking issues
run_fix_loop	Automated fix-validate until convergence
fix_and_verify	Single file fix with before/after verification
get_compliance_certificate	Cryptographic proof of compliance

Example Workflow:

Claude: [calls lint_spec to check spec completeness]
        [calls run_fix_loop to auto-fix violations]
        [calls check_release_gate for go/no-go decision]
        "Release approved with score 92/100. Certificate: a3f2c8b1"

Spec Linting

Verify design system spec completeness for agent-readiness.

CLI:

dss lint-spec                    # Lint current directory
dss lint-spec --min-score 80     # Require minimum score
dss lint-spec --rules llm-*      # Specific rules only
dss lint-spec --json             # JSON output for CI
dss lint-spec rules              # List available rules

Rules:

• meta-required: Name and version required
• component-has-variants/props/llm-context: Component completeness
• llm-has-intent/anti-patterns/allowed-contexts: LLM context quality
• tokens-have-descriptions: Token documentation
• accessibility-defined: A11y requirements present
• validators-configured: External validators configured

External Validators

Delegate validation to specialized external tools (agent-a11y, spectral, etc.).

New Types:

{
  "validators": {
    "accessibility": {
      "tool": "agent-a11y",
      "type": "mcp",
      "config": { "standard": "wcag21aa" }
    },
    "apiStyle": {
      "tool": "spectral",
      "type": "cli",
      "config": { "ruleset": "openapi" }
    }
  }
}

Agentic Development Documentation

Comprehensive documentation for autonomous development workflows.

New Documentation:

• PIDL workflow specification (16 entities, 25 flows)
• Automation analysis (71.3% automation score)
• ASDM integration (L5-L7 mapping)
• Agentic maturity assessment (L2.8 current, L4 target)

Added

• dss-mcp MCP server with 37 tools
• dss eval command for spec evaluation
• dss render command for HTML documentation
• dss visual commands for visual regression testing
• dss lint-spec command for spec completeness
• Service type for unified CLI/MCP operations
• LoadDesignSystemFromFS() for embedded filesystems
• ValidateFile() and ValidateDirectory() methods
• FixFile(), SuggestFixes(), FixDirectory() methods
• ComplianceReport, ReleaseGate, ComplianceCertificate types
• Validators section for external validation delegation
• Visual regression testing package (sdk/go/visual/)
• Evaluation system with structured-evaluation integration
• HTML templates with Material Web CDN integration
• Design compliance and fixer agent specifications

Changed

• CLI commands refactored to use service layer
• MkDocs navigation updated with new documentation

Fixed

• Remove markdown attribute from HTML wrapper causing MkDocs parsing issues
• Resolve golangci-lint issues (gofmt, gosec, unparam)

Documentation

• MCP server documentation with all 37 tools
• Visual regression testing PRD, TRD, PLAN, ROADMAP
• Rendering components feature documentation
• Agentic delivery loop documentation (AGENT-LOOP.md)
• ASDM integration mapping
• PIDL workflow specification
• Automation analysis with infographic
• Agentic maturity assessment
• Design systems catalog
• Updated README with MCP server section
• Updated CLI reference with new commands

Build

• Add MCP SDK dependency (github.com/modelcontextprotocol/go-sdk)
• Add structured-evaluation v0.9.0 dependency

Installation

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

# MCP server
go install github.com/plexusone/design-system-spec/cmd/dss-mcp@v0.5.0

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

Quick Start

# Generate HTML documentation with live demos
dss render --dir ./my-design-system --output ./docs --title "My Design System"

# Run visual regression tests
dss visual test --dir ./my-design-system

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

What's Next

• dss init scaffolding for new design systems
• CI/CD GitHub Actions integration
• Color contrast validation
• Figma tokens import/export

Links

• Documentation
• MCP Server
• CLI Reference
• Go SDK
• Changelog
• v0.4.0 Release Notes