Skip to content

Release Notes - v0.3.0

Release Date: 2026-05-30

Highlights

  • Theming Contracts - Formal theming API between component libraries and consuming applications
  • Diagram Generators - Mermaid and D2 diagram generation for visualizing design system architecture
  • Web Component Viewer - Lit-based @plexusone/dss-ui package for interactive spec viewing
  • W3C Design Tokens - Export to W3C Design Tokens Community Group format

What's New

Theming System

A complete theming contract system enabling components to declare their external theming API and applications to map their tokens:

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" }
      ]
    }
  ]
}

CLI Commands:

# Generate CSS/TypeScript/SCSS from theme bindings
dss bind --output ./theme.css --format css

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

# Validate all theming contracts
dss contract validate

Diagram Generators

Generate architecture diagrams from your design system specification:

Mermaid:

opts := dss.DefaultMermaidOptions()
diagram, _ := ds.GenerateMermaid(opts)
// Produces component relationship diagrams

D2:

opts := dss.DefaultD2Options()
opts.Sketch = true  // Hand-drawn look
d2, _ := ds.GenerateD2(opts)

W3C Design Tokens Export

Export design tokens in the W3C Design Tokens Community Group format:

opts := dss.DefaultW3CTokensOptions()
tokens, _ := ds.GenerateW3CTokens(opts)

Web Component Viewer

New @plexusone/dss-ui package for visualizing design system specs:

  • Lit-based web components
  • Interactive token and component viewers
  • PlexusOne dark theme styling
  • TypeScript types for DSS schema

Schema Enhancements

  • Brand section - Organization-specific branding (logos, navigation, social links)
  • Component Events - Define custom events with detail payloads
  • Component Uses - Declare component dependencies
  • PropConstraints - Validation constraints for properties
  • $schema property - IDE validation support

Added

  • ThemingContract, ThemeToken, ThemeBindings, TokenMapping types
  • ValidateContract(), ValidateAllContracts() contract validation
  • GenerateBindings() for CSS/TypeScript/SCSS theme binding output
  • dss bind CLI command with --format and --strategy flags
  • dss contract show and dss contract validate CLI commands
  • GenerateMermaid(), GenerateMermaidComponentDiagram(), GenerateMermaidTokenDiagram()
  • GenerateD2(), GenerateD2ComponentDiagram() for D2 diagram generation
  • GenerateW3CTokens() for W3C Design Tokens export
  • GenerateDocs() for MkDocs-compatible documentation generation
  • @plexusone/dss-ui web component viewer package
  • Brand schema section with identity, logos, navigation
  • ComponentEvent, EventDetailField types for event definitions
  • PropConstraints type for property validation
  • themed-app example demonstrating theme bindings

Changed

  • JSON schemas regenerated with new theming and event types
  • README updated with theming contracts, new CLI commands, and roadmap
  • MkDocs navigation includes Theming specification and case study

Fixed

  • Resolve golangci-lint findings (gofmt, gosec G107, unparam, dupl)

Documentation

  • Theming specification (docs/specification/theming.md)
  • Component theming case study (docs/case-studies/component-theming.md)
  • CLI reference updated with bind and contract commands
  • SDK reference updated with diagram generators and theming functions
  • CLAUDE.md project instructions for AI-assisted development

Tests

  • Comprehensive theming contract and bindings tests
  • Table-driven tests for output format generation

Build

  • Bump github.com/invopop/jsonschema from 0.13.0 to 0.14.0

Installation

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

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

Quick Start

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

# Validate theming contracts
dss contract validate

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

What's Next

  • dss init scaffolding for new design systems
  • dss lint for spec completeness checking
  • Advanced validation (color contrast, composition rules)
  • Figma tokens import/export