{"_id":"@aestheticfunction/dspack-spec","_rev":"6-29c4c87cacda27c1d685e59d260579f3","name":"@aestheticfunction/dspack-spec","dist-tags":{"latest":"0.4.4"},"versions":{"0.4.0":{"name":"@aestheticfunction/dspack-spec","version":"0.4.0","license":"Apache-2.0","_id":"@aestheticfunction/dspack-spec@0.4.0","maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"bin":{"dspack-validate":"scripts/validate.mjs"},"dist":{"shasum":"e3eaf8c365a40fc43c7962db9ea7707d3e0ba75b","tarball":"https://registry.npmjs.org/@aestheticfunction/dspack-spec/-/dspack-spec-0.4.0.tgz","fileCount":21,"integrity":"sha512-Bfs+xQJcvgE93ayGrHU01o6etr9u5SZDnmDKS6F0YiETGB3uX2gBYGNfb3QlK0ZTpVp9mpcmiCVkGDxP58NOqg==","signatures":[{"sig":"MEUCIQDu7Z/6a/4TVUHpZL7YjRFyBStbP2zT7oB1e2ejMSOdiwIgCNCp1PDUUR2Umomg3+HGM20tV2D/er9Y7y1DF73oy7U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":424249},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"cf593c7f3cdde3a924a394b48e8aeecee0af2234","scripts":{"validate":"node scripts/validate.mjs"},"_npmUser":{"name":"ryandmonk","email":"rdombrowski@gmail.com"},"deprecated":"dspack-validate fails after a clean install; upgrade to 0.4.1 or later.","_npmVersion":"11.6.2","description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","directories":{},"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"_npmOperationalInternal":{"tmp":"tmp/dspack-spec_0.4.0_1784766578643_0.016108616944142895","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@aestheticfunction/dspack-spec","version":"0.4.1","license":"Apache-2.0","_id":"@aestheticfunction/dspack-spec@0.4.1","maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"homepage":"https://github.com/aestheticfunction/dspack#readme","bugs":{"url":"https://github.com/aestheticfunction/dspack/issues"},"bin":{"dspack-validate":"scripts/validate.mjs"},"dist":{"shasum":"c010f326bf92ae572b360a18afa843a51abb7d06","tarball":"https://registry.npmjs.org/@aestheticfunction/dspack-spec/-/dspack-spec-0.4.1.tgz","fileCount":21,"integrity":"sha512-VxqDTMJFNK1SjzNFII5ZI0sAWI0U1CgNU/GBQNSZ7zr44slFx7eW7kbgtcRuYhnqqEqc3Y/c+eGUA6UcdX9KXQ==","signatures":[{"sig":"MEUCIFHYITOJY/Z3bYyc49+trnPaVlFAZzAMPMPlSa9oN4jnAiEAghDNSKGwabZfLdsLbLfUTwwUx9X6c8w1Y2yR+DkuolY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aestheticfunction%2fdspack-spec@0.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":424527},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"c58a97a0b48b498b6299200ba266eb2899e1c778","scripts":{"validate":"node scripts/validate.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:045b9efa-7488-41c3-9a87-26897a8e7c1a"}},"repository":{"url":"git+https://github.com/aestheticfunction/dspack.git","type":"git"},"_npmVersion":"11.16.0","description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","directories":{},"_nodeVersion":"24.18.0","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"_hasShrinkwrap":false,"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/dspack-spec_0.4.1_1784770255920_0.26485645456706997","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@aestheticfunction/dspack-spec","version":"0.4.2","license":"Apache-2.0","_id":"@aestheticfunction/dspack-spec@0.4.2","maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"homepage":"https://github.com/aestheticfunction/dspack#readme","bugs":{"url":"https://github.com/aestheticfunction/dspack/issues"},"bin":{"dspack-validate":"scripts/validate.mjs"},"dist":{"shasum":"4d5924f729988c25f2e76c2b2594934831b8dffc","tarball":"https://registry.npmjs.org/@aestheticfunction/dspack-spec/-/dspack-spec-0.4.2.tgz","fileCount":23,"integrity":"sha512-c7sOcYfhqU7N4MOEJOH3GPIrjLqfMbRwO+XiIn3mumw6Is/5OCIVSvQupy703G8c2e0dotcnxxKNJs5A91eQ/g==","signatures":[{"sig":"MEUCIHx40FC3163xOdjbBa6m3ZR0tUcHazxjaFZdTMsTltuuAiEA6wAvqAg0dM3SNRsmi9BtOA3D/yBZngbuM9jnpJvPG54=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aestheticfunction%2fdspack-spec@0.4.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":429698},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"98d235c8a8b0e42403c8bdac42c62f7fb37768ac","scripts":{"validate":"node scripts/validate.mjs","check:lib":"node scripts/check-lib-boundary.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:218cd32a-87c9-4048-b9a8-fc0d25a9fd85"}},"repository":{"url":"git+https://github.com/aestheticfunction/dspack.git","type":"git"},"_npmVersion":"11.16.0","description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","directories":{},"_nodeVersion":"24.18.0","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"_hasShrinkwrap":false,"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/dspack-spec_0.4.2_1785797330222_0.5691070930636735","host":"s3://npm-registry-packages-npm-production"}},"0.4.3":{"name":"@aestheticfunction/dspack-spec","version":"0.4.3","license":"Apache-2.0","_id":"@aestheticfunction/dspack-spec@0.4.3","maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"homepage":"https://github.com/aestheticfunction/dspack#readme","bugs":{"url":"https://github.com/aestheticfunction/dspack/issues"},"bin":{"dspack-validate":"scripts/validate.mjs"},"dist":{"shasum":"d648a38467a225d3c7075f4d972fd7dbf8e716bf","tarball":"https://registry.npmjs.org/@aestheticfunction/dspack-spec/-/dspack-spec-0.4.3.tgz","fileCount":23,"integrity":"sha512-+8ma9pbko9hSUA6XQk4bPx0uMy3vewKxKtqQSVkohaXwgZFfHuPwc5mcGRIXGpuB2XkbNDL72QfYM+G5strG4Q==","signatures":[{"sig":"MEQCIGGXe1pQDhqrJaoSHNXDWZB+VVCYx4zEbvcDU06W/9KcAiBrYd2RV6lgtaiLsvNmVmT5fT2chfKCE/USzyrsAmdDIA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aestheticfunction%2fdspack-spec@0.4.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":815867},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"b1763e49893e5958199331d2c73d30b86ef85847","scripts":{"validate":"node scripts/validate.mjs","check:lib":"node scripts/check-lib-boundary.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:218cd32a-87c9-4048-b9a8-fc0d25a9fd85"}},"repository":{"url":"git+https://github.com/aestheticfunction/dspack.git","type":"git"},"_npmVersion":"11.16.0","description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","directories":{},"_nodeVersion":"24.18.0","dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"_hasShrinkwrap":false,"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/dspack-spec_0.4.3_1786120080987_0.6168259887900003","host":"s3://npm-registry-packages-npm-production"}},"0.4.4":{"name":"@aestheticfunction/dspack-spec","version":"0.4.4","description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","type":"module","license":"Apache-2.0","scripts":{"validate":"node scripts/validate.mjs","check:lib":"node scripts/check-lib-boundary.mjs"},"devDependencies":{},"engines":{"node":">=20.0.0"},"bin":{"dspack-validate":"scripts/validate.mjs"},"dependencies":{"ajv":"^8.17.1","ajv-formats":"^3.0.1"},"repository":{"type":"git","url":"git+https://github.com/aestheticfunction/dspack.git"},"homepage":"https://github.com/aestheticfunction/dspack#readme","bugs":{"url":"https://github.com/aestheticfunction/dspack/issues"},"gitHead":"d50f04931df2249f11c9f8f1831265fcbc335952","_id":"@aestheticfunction/dspack-spec@0.4.4","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-0Fb3x5KVyxclENVo3xUp36+uQkBYUmZoZ6h2pw0aRp2gq2Stp8048s/hqjms8Wu/VfBDrSQs5AJ9giM7Wx1VGg==","shasum":"4d56e8e6bcca5114ae085c52e86e4456113b30f6","tarball":"https://registry.npmjs.org/@aestheticfunction/dspack-spec/-/dspack-spec-0.4.4.tgz","fileCount":23,"unpackedSize":821187,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aestheticfunction%2fdspack-spec@0.4.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGpNjUE/PiVmC+TjVCBKAVCxuW2r5GSfMIuDaDk+ARhzAiAEyIYNEYvI1dZufuUNZtANz3hvsIN7vLUxNRjE5uuFjw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:218cd32a-87c9-4048-b9a8-fc0d25a9fd85"}},"directories":{},"maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dspack-spec_0.4.4_1786137422555_0.45677899598863236"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-23T00:29:38.460Z","modified":"2026-08-07T21:17:03.192Z","0.4.0":"2026-07-23T00:29:38.835Z","0.4.1":"2026-07-23T01:30:56.085Z","0.4.2":"2026-08-03T22:48:50.379Z","0.4.3":"2026-08-07T16:28:01.122Z","0.4.4":"2026-08-07T21:17:02.750Z"},"bugs":{"url":"https://github.com/aestheticfunction/dspack/issues"},"license":"Apache-2.0","homepage":"https://github.com/aestheticfunction/dspack#readme","repository":{"type":"git","url":"git+https://github.com/aestheticfunction/dspack.git"},"description":"The dspack specification: spec documents, JSON Schemas, reference example contracts, and the validation harness (bin: dspack-validate).","maintainers":[{"name":"ryandmonk","email":"rdombrowski@gmail.com"}],"readme":"# dspack\n\n**dspack** is an open JSON specification for what a design system knows and enforces: tokens, components, categories, intents, and typed governance rules in one portable contract that AI agents can query and must satisfy.\n\nThink of it as OpenAPI for design systems.\n\n> Part of the [dspack ecosystem](https://github.com/aestheticfunction) — the organization profile has the full map of how the repositories fit together.\n>\n> **Kind:** specification (spec, schemas, examples, validation harness; npm `@aestheticfunction/dspack-spec` ships the `dspack-validate` bin) · **Audience:** design-system practitioners and tool implementers · **Neighbors:** consumed by [ds-mcp](https://github.com/aestheticfunction/ds-mcp), [dspack-gen](https://github.com/aestheticfunction/dspack-gen), [dspack-emit](https://github.com/aestheticfunction/dspack-emit), and [dspack-studio](https://github.com/aestheticfunction/dspack-studio); bootstrapped from code by [dspack-export](https://github.com/aestheticfunction/dspack-export)\n>\n> **Adopting dspack for an existing design system?** The complete journey — snapshot, governance authoring, validation, serving — is walked step by step in [ADOPTING.md](./ADOPTING.md).\n\n---\n\n> **Status: v0.4 draft available.**\n>\n> The current draft is [`spec/dspack-v0.4.md`](./spec/dspack-v0.4.md) (written as a delta over [v0.3](./spec/dspack-v0.3.md)), with a matching [JSON Schema](./schema/dspack.v0.4.schema.json), a companion [surface schema](./schema/dspack.surface.v0_1.schema.json), and a [shadcn/ui reference example](./examples/shadcn-ui.dspack.json). v0.4 adds **component categories** (a contract-defined registry that rules can select by) and the **`required-props` rule type** (\"this component must carry named content directly\" — the refinement driven by measured projection-gap failures), and is strictly additive: a valid v0.3 document with `\"dspack\": \"0.4\"` validates against the v0.4 schema (see the [migration guide](./spec/migration-v0.3-to-v0.4.md)). Earlier specs and schemas ([v0.3](./spec/dspack-v0.3.md), [v0.2](./spec/dspack-v0.2.md), [v0.1](./spec/dspack-v0.1.md)) are preserved for reference. This is a draft — breaking changes may occur before v1.0. Contributions to the design are welcome at any stage.\n\n---\n\n## dspack in action\n\nOne dspack contract, consumed end-to-end by tools that never coordinated — queried over MCP, compiled to an A2UI catalog, and rendered. The spec travels.\n\nhttps://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961\n\n---\n\n## Try it in five minutes\n\nStart with the specification's own harness. It compiles every schema and\nvalidates the bundled examples, so one command shows you the spec is\nself-consistent and what a clean result reads like:\n\n```bash\nnpx -y -p @aestheticfunction/dspack-spec dspack-validate\n```\n\nThen put a real contract in front of an agent:\n\n```bash\ncurl -L https://raw.githubusercontent.com/aestheticfunction/dspack/main/examples/shadcn-ui.dspack.json -o shadcn-ui.dspack.json\nnpm install -g @aestheticfunction/ds-mcp\nds-mcp --dspack ./shadcn-ui.dspack.json\n```\n\nConnect Claude Code, Cursor, Claude Desktop, or Copilot ([client setup](https://github.com/aestheticfunction/ds-mcp#readme)) and ask it to build a settings form. It will query your components, tokens, and anti-patterns instead of guessing, and you can lint the result against the contract's rules with `validate-ui`.\n\n---\n\n## Table of Contents\n\n- [dspack in action](#dspack-in-action)\n- [Try it in five minutes](#try-it-in-five-minutes)\n- [What is dspack?](#what-is-dspack)\n- [Concepts](#concepts)\n- [Measured, not claimed](#measured-not-claimed)\n- [Implementations](#implementations)\n- [Non-goals](#non-goals)\n- [Roadmap](#roadmap)\n- [How to participate](#how-to-participate)\n- [Acknowledgments](#acknowledgments)\n- [License](#license)\n\n---\n\n## What is dspack?\n\nDesign systems encode decisions: what a button looks like, how spacing scales, when to use a modal versus a sheet, which patterns have been tried and retired. Most of that knowledge is effectively invisible to the AI agents now writing production code alongside the people who built those systems.\n\ndspack makes that knowledge portable. It defines a format for capturing a design system's vocabulary, including tokens, component contracts, usage patterns, known anti-patterns, and framework-specific bindings, in a single artifact that AI tools can load and query. The format is intentionally simple: it is a document, not a runtime. It describes what a design system knows, not how it renders.\n\nThe artifact is meant to be durable. Models, editors, and agent runtimes will keep changing; the need to carry design system knowledge between toolchains is more stable. A file can be versioned, reviewed, diffed, validated, and transported without requiring a particular service to stay online.\n\nThe full rationale, including why a file format and the principles the spec is built around, lives in [DESIGN.md](./DESIGN.md).\n\n---\n\n## Concepts\n\nA dspack file is a snapshot of a design system's knowledge at a point in time. It is not a live connection to Figma, Storybook, or any other tool. It organizes the following kinds of information:\n\n- **Tokens.** The named values that anchor a system's visual language, organized by category and classified by abstraction tier (primitive, semantic, or component-scoped), with alias relationships between tiers.\n- **Components.** What each component is for, the variants and states it supports, and the API surface it presents, plus lifecycle status, accessibility constraints, composition rules, and machine-readable usage constraints. No implementation code.\n- **Patterns.** Preferred ways of combining components to solve recurring problems: the problem addressed, the context, the components involved, and when to prefer the pattern over alternatives.\n- **Anti-patterns.** Things the system has deliberately ruled out, with the reason why and a severity level. An agent that knows what *not* to do is less likely to reproduce mistakes a team has already worked through.\n- **Framework bindings.** Which frameworks are supported, where packages are published, and per-sub-component import and export information, so consumers can generate correct import statements.\n- **Themes.** Named sets of token overrides for alternative visual modes: dark mode, high contrast, compact density.\n- **Layout primitives.** Responsive breakpoints, grid configuration, container sizes, and spacing scale parameters.\n\nThese concepts relate to one another: components depend on tokens, patterns compose components, anti-patterns explain why a pattern exists, tokens alias other tokens across tiers, and themes override tokens for alternative contexts.\n\n---\n\n## Measured, not claimed\n\nThe spec evolves against evidence, not speculation. Every milestone runs 216-run eval matrices across three local model families (gemma, qwen, gpt-oss), with all numbers recomputable from retained audit reports. The v0.4 `required-props` rule exists because 78/78 emitter-gate failures across all three families shared one measured signature; the amended rule took end-to-end passes from 28/216 to 67/216 with that signature extinct. Full findings: [dspack-gen findings](https://github.com/aestheticfunction/dspack-gen/blob/main/docs/findings.md) · [M3 report](https://github.com/aestheticfunction/dspack-gen/blob/main/docs/m3-report.md).\n\n---\n\n## Implementations\n\n### Producing dspack files\n\n[dspack-export](https://github.com/aestheticfunction/dspack-export) (experimental) generates a spec-current dspack file from a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase: components and props (including cva variant enums and their defaults, and Vue `defineProps`/emits/slots), semantic color and radius tokens from CSS custom properties or an imported DTCG design-token file, dark-theme overrides, layout breakpoints, and framework import bindings. It is a snapshot generator. Hand-authored sections such as `patterns`, `antiPatterns`, `whenToUse`, `accessibility`, and `constraints` remain yours to write; an exporter can extract facts, but the institutional knowledge that makes a dspack file valuable to agents comes from your team.\n\ndspack files can also simply be written by hand — the [shadcn/ui example](examples/shadcn-ui.dspack.json) in this repository was authored that way. A valid document needs only `dspack` and `name`.\n\n### Consuming dspack files\n\n[ds-mcp](https://github.com/aestheticfunction/ds-mcp) is the reference implementation of dspack. It is a read-only [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that loads a dspack file and exposes your design system as tools AI coding agents can query at coding time. It supports dspack v0.1 through v0.4; the generation tools (`get-generation-context`, `validate-ui`) require v0.3 or v0.4.\n\n[dspack-gen](https://github.com/aestheticfunction/dspack-gen) is the generation-and-governance pipeline: it compiles a contract into generation context for a model, lints what the model produces against the contract's typed rules (the S1–S3 gates), applies bounded repair, and audits every run. [dspack-emit](https://github.com/aestheticfunction/dspack-emit) is the deterministic emitter: it projects governed surfaces and contract catalogs onto rendering protocols (A2UI and json-render), behind its own validation gates.\n\n[dspack-studio](https://github.com/aestheticfunction/dspack-studio) is the flagship experience that runs this whole chain end to end — agent generation under a contract, gates, repair, and rendering, with every step recorded and inspectable. To see the ecosystem working before reading any further, the hosted replay lives at [studio.aesthetic-function.com](https://studio.aesthetic-function.com).\n\nds-mcp is one way to consume a dspack file, not the only way. The format is independent of MCP, independent of any specific AI agent or orchestration framework, and independent of any particular runtime environment. (On why the reference implementation is deliberately not the center of gravity, see [DESIGN.md](./DESIGN.md).)\n\n### Validating dspack files programmatically\n\nThe validation harness behind the `dspack-validate` CLI is importable —\npure functions, schemas injected, so the identical checks run under Node or\nin a browser bundle. The CLI is a front-end over this one implementation,\nnever a second validator:\n\n```js\nimport {\n  compileSchemaSet,\n  documentReport,\n} from \"@aestheticfunction/dspack-spec/lib/validate.mjs\";\nimport v04 from \"@aestheticfunction/dspack-spec/schema/dspack.v0.4.schema.json\" with { type: \"json\" };\nimport surface from \"@aestheticfunction/dspack-spec/schema/dspack.surface.v0_1.schema.json\" with { type: \"json\" };\n\nconst { validators } = compileSchemaSet({\n  \"dspack.v0.4.schema.json\": v04,\n  \"dspack.surface.v0_1.schema.json\": surface,\n});\nconst report = documentReport(doc, validators);\n// { valid, version, errors } — schema gate, governance consistency,\n// categories, and S1/S2 over the contract's own examples.\n```\n\nTypes ship alongside (`lib/validate.d.mts`). CI's `check:lib` gate keeps the\nlib pure (ajv-only imports) and replays the full example + negative-fixture\ncorpus through the import surface.\n\nIf you want to build a dspack reader for a different use case, the format is available under the Apache-2.0 license. Potential directions include:\n\n- Readers for non-MCP agentic frameworks (LangChain, AutoGen, or similar)\n- CLI tools for querying or linting dspack files\n- IDE plugins that surface design system context directly in the editor\n- RAG pipeline integrations that index dspack content alongside codebases\n- Implementations in Go, Python, Rust, or other languages\n\nIf you are building something that consumes dspack, feel free to open a discussion or mention it in an issue. This repository maintains a record of known implementations as they emerge.\n\n---\n\n## Non-goals\n\ndspack has a defined scope. Understanding what it is not helps clarify what it is.\n\n**dspack is not a code generator.** It describes a design system's vocabulary and contracts; it does not produce component scaffolding, generate CSS, or write implementation files.\n\n**dspack is not a design tool.** It does not replace Figma, Sketch, Penpot, or any other design environment. It is downstream of those tools.\n\n**dspack is not a drift reconciliation system.** It does not watch a codebase for divergence from a design spec, flag components that have fallen out of sync, or push changes from design back into code. That is a distinct problem with distinct requirements. (See the acknowledgments for a project that addresses it.)\n\n**dspack is not a rendering engine.** It describes contracts, intent, and vocabulary, not pixels, computed styles, or DOM structure.\n\n**dspack is not framework-specific.** A single dspack file can describe a design system that ships implementations across multiple frameworks.\n\n**dspack is not tied to any design tool's export format.** It may ingest or reference those formats, but it has its own schema and versioning.\n\n**dspack is not a substitute for design system governance.** It can record decisions; it does not make them.\n\n**dspack is not a guarantee of implementation quality.** The format can improve the conditions under which agents operate, but it does not remove the need for review, testing, and judgment.\n\n---\n\n## Roadmap\n\nThe following milestones represent the current intended direction. They are not scheduled. The priority is getting the spec right, not getting it done quickly.\n\n| Milestone | Description |\n|-----------|-------------|\n| **Schema design conversation** | Structured discussion to establish core vocabulary, structural constraints, and extensibility model for v0.1 |\n| **v0.1 spec draft** | First complete draft of the dspack specification — _[available](./spec/dspack-v0.1.md)_ |\n| **shadcn/ui example dspack** | A reference dspack file for the [shadcn/ui](https://ui.shadcn.com) component library — _[available](./examples/shadcn-ui.dspack.json)_ |\n| **v0.2 spec draft** | Adds structured generation constraints: lifecycle status, accessibility, composition rules, contextual constraints, variant semantics, token hierarchy, themes, layout primitives, and anti-pattern severity — _[available](./spec/dspack-v0.2.md)_ |\n| **v0.3 spec draft** | Adds the machine-checkable governance blocks: named intents, typed deterministic rules with rationales, compilable examples, and the companion dspack surface format — _[available](./spec/dspack-v0.3.md)_ |\n| **v0.4 spec draft** | Adds component categories (contract-defined registry, category-based rule selection) and the `required-props` rule type, both driven by measured pipeline evidence — _[available](./spec/dspack-v0.4.md)_ |\n| **ds-mcp v0 release** | First release of the reference implementation, validated against the v0.2 spec; current releases support v0.1 through v0.4 — _[available](https://github.com/aestheticfunction/ds-mcp)_ |\n| **Community RFCs** | Open RFC process for proposing additions and changes to the spec |\n| **v1.0 spec stabilization** | First stable, versioned release of the specification; breaking changes require a formal process after this point |\n\nCommunity feedback will influence the order and scope of these milestones. The roadmap is best understood as a set of feedback loops rather than a strict waterfall: drafting the spec informs what a reference example should contain, and attempting a real example exposes whether the draft is missing concepts or forcing awkward abstractions.\n\n---\n\n## How to participate\n\n### Issues\n\nGitHub Issues are the preferred place for concrete, specific input:\n\n- **Spec questions** — if something about the intended behavior or scope of the format is unclear, open a spec question issue. Questions about intent help sharpen the draft.\n- **Ambiguity reports** — reports of spec language that is unclear or could be interpreted multiple ways are high-value contributions. A spec with documented ambiguities is better than one with undocumented ones.\n- **Breaking change proposals** — proposals for changes that would be incompatible with prior versions of the spec. These require more context and deliberation than other issues.\n\nIssue templates are provided for each of these. Labels for routing issues are configured in the repository settings; if a label is missing when you open an issue, it will be added during triage.\n\n### Discussions\n\nGitHub Discussions are open for broader conversation: use cases you are trying to cover, design system patterns the spec should be able to represent, experience reports from working with AI agents and existing design systems, or anything that does not fit neatly into an issue.\n\nIf you are unsure whether something should be an issue or a discussion, start with a discussion when the topic is exploratory and an issue when the topic describes a concrete problem to resolve. There is no penalty for getting that wrong in an early-stage repository; the goal is to keep useful information visible and actionable.\n\n### The RFC process\n\nFor substantive proposals — new top-level concepts, structural changes, or anything requiring updates to existing dspack files — the process is lightweight:\n\n1. **Open a GitHub Discussion** describing the problem and your proposed approach. The goal at this stage is to validate that the problem is real and that the direction makes sense before investing in a full proposal.\n2. **Iterate in the discussion** until the proposal is reasonably stable. Gather input, refine the approach, identify edge cases.\n3. **Open a pull request** adding a document to the `rfc/` directory. The template and conventions for RFC documents are described in [`rfc/README.md`](./rfc/README.md).\n4. **Review happens in the PR.** An RFC is accepted when it merges; it is rejected when the PR is closed without merging.\n\nThere is no formal RFC numbering scheme at this stage. The repository is still early enough that over-formalizing the process would create more ceremony than clarity.\n\n### Who should contribute\n\nYou do not need to be a software engineer to contribute to this spec. Design system practitioners of all kinds — designers, content strategists, product managers, accessibility specialists — are invited to participate. The spec should reflect how design systems actually work in organizations, not just how they are implemented in code.\n\nThat invitation also extends to people who do not expect to use ds-mcp themselves. dspack is intended to stand as a general-purpose specification. If your interest is in documentation workflows, schema validation, internal tooling, package metadata, or some future implementation that has not been written yet, your perspective still helps shape the format.\n\n### Good early contributions\n\nThe most helpful inputs at this stage are usually:\n\n- examples of design system knowledge that is hard to express with current tooling\n- cases where agents consistently make the wrong design-system decision\n- distinctions a spec would need to preserve for your organization to trust the artifact\n- notes about interoperability constraints if you maintain design systems across multiple frameworks or platforms\n- questions that expose unclear assumptions in the current draft\n\nConcrete examples of real design-system problems are often more valuable than abstract debates about ideal structure.\n\n### What this repository contains\n\n- versioned specification documents in `spec/`\n- schema and validation artifacts in `schema/`\n- example dspack files in `examples/`\n- design proposals and change records in `rfc/`\n\n---\n\n## Acknowledgments\n\ndspack was created by [Ryan Dombrowski](https://github.com/ryandmonk) ([LinkedIn](https://www.linkedin.com/in/ryan-dombrowski)), who also builds [Aesthetic Function](https://github.com/aestheticfunction), a reconciliation engine that keeps design systems aligned across Figma, code, and documentation.\n\n---\n\n## License\n\nCopyright 2026 Aesthetic Function, LLC.\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full text.\n","readmeFilename":"README.md"}