Reference / Spec and API

Spec and API

Every system is a folder with a manifest, tokens in the W3C design tokens format, rules, component specs and agent instructions.

Layout

<system>/
├── manifest.json            id, name, tags, fonts, licenses
├── tokens/
│   ├── primitives.json      raw values (DTCG)
│   ├── semantic.light.json  roles → primitives
│   └── semantic.dark.json
├── principles/visual-language.md
├── components/              index.json + one spec per component
├── agent/instructions.md    new · existing · ongoing · verification · rollback
├── CHANGELOG.md
└── dist/
    ├── agent.md             the single document agents read
    ├── tokens.css           CSS variables, light and dark
    └── tokens.json          resolved values per mode

HTTP API

GET /api/v1/design-systems
GET /api/v1/design-systems/:id
GET /api/v1/design-systems/:id/tokens
GET /api/v1/design-systems/:id/components/:name
GET /api/v1/design-systems/:id/guides/:mode     new | existing | ongoing
GET /s/:id/agent.md

Every endpoint serves the current system. Errors return { "error": { "code", "message" } } with codes unknown_template, invalid_component, unavailable_artifact and invalid_mode.