From 4e961ed9d8074256f7855ccbaea01ae5f6c88389 Mon Sep 17 00:00:00 2001 From: Ryan Dombrowski Date: Mon, 10 Aug 2026 15:12:22 -0400 Subject: [PATCH] docs: v0.4 is four additions, not two; repair the ADOPTING table of contents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An ecosystem-wide documentation audit found the v0.4 summary lines never caught up with the spec's own amendments, and every ADOPTING anchor broken. - v0.4 has been amended twice since the summaries were written: `requiredCategories` (ยง4.3, 2026-08-07) and S2 sub-component containment (ยง5.1). Both are normative, schema-backed, in use in the worked contract, and evaluated by dspack-gen โ€” but README (twice), spec/README, and schema/README all still said "categories and required-props". Corrected in all four, and the migration guide's "all three additions" is now four. - The migration guide illustrated "a registry of two categories"; the worked contract declares seven. - examples/README understated what the reference example demonstrates (7 categories, 26 required-props rules, 2 forbidden-composition rules, and a requiredCategories rule that went unmentioned). - examples/astryx.dspack.json described itself as "a nine-component slice" while shipping twelve components โ€” the artifact contradicted its own README. - All 12 ADOPTING.md table-of-contents anchors were broken: they were hand-written up to the em-dash while the headings carry a trailing mode label, so every "jump to step N" link failed. Regenerated from the real headings using GitHub's slug rules. Verified: `npm run validate` passes both examples, negative fixtures still refuse. Co-Authored-By: Claude Opus 4.8 --- ADOPTING.md | 24 ++++++++++++------------ README.md | 4 ++-- examples/README.md | 2 +- examples/astryx.dspack.json | 2 +- schema/README.md | 2 +- spec/README.md | 5 +++-- spec/migration-v0.3-to-v0.4.md | 4 ++-- 7 files changed, 22 insertions(+), 21 deletions(-) diff --git a/ADOPTING.md b/ADOPTING.md index 5b14d30..c0db7ab 100644 --- a/ADOPTING.md +++ b/ADOPTING.md @@ -27,18 +27,18 @@ there.) | # | Step | Mode | |---|------|------| -| 1 | [Extract a snapshot from your codebase](#step-1--extract-a-snapshot) | ๐Ÿค– Automated | -| 2 | [~~Set the version to the current spec~~](#step-2--set-the-version) โ€” retired; snapshots declare it | ๐Ÿค– Automated | -| 3 | [Review the snapshot against reality](#step-3--review-the-snapshot) | ๐Ÿ‘€ Human review | -| 4 | [Author component guidance](#step-4--author-component-guidance) | โš–๏ธ Design decision | -| 5 | [Define categories and tag components](#step-5--define-categories) | โš–๏ธ Design decision | -| 6 | [Record patterns and anti-patterns](#step-6--patterns-and-anti-patterns) | โš–๏ธ Design decision | -| 7 | [Name your intents](#step-7--name-your-intents) | โš–๏ธ Design decision | -| 8 | [Write rules](#step-8--write-rules) | โš–๏ธ Design decision | -| 9 | [Write worked examples and cross-link them](#step-9--worked-examples) | โš–๏ธ Design decision (machine-validated) | -| 10 | [Validate the contract](#step-10--validate) | ๐Ÿค– Automated | -| 11 | [Serve it to agents](#step-11--serve-it-to-agents) | ๐Ÿค– Automated | -| 12 | [Generate, lint, and render](#step-12--generate-lint-render) | ๐Ÿค– Automated (rendering profile: โš–๏ธ) | +| 1 | [Extract a snapshot from your codebase](#step-1--extract-a-snapshot---automated) | ๐Ÿค– Automated | +| 2 | [~~Set the version to the current spec~~](#step-2--set-the-version--retired) โ€” retired; snapshots declare it | ๐Ÿค– Automated | +| 3 | [Review the snapshot against reality](#step-3--review-the-snapshot---human-review) | ๐Ÿ‘€ Human review | +| 4 | [Author component guidance](#step-4--author-component-guidance--) | โš–๏ธ Design decision | +| 5 | [Define categories and tag components](#step-5--define-categories--) | โš–๏ธ Design decision | +| 6 | [Record patterns and anti-patterns](#step-6--patterns-and-anti-patterns--) | โš–๏ธ Design decision | +| 7 | [Name your intents](#step-7--name-your-intents--) | โš–๏ธ Design decision | +| 8 | [Write rules](#step-8--write-rules--) | โš–๏ธ Design decision | +| 9 | [Write worked examples and cross-link them](#step-9--worked-examples---machine-validated) | โš–๏ธ Design decision (machine-validated) | +| 10 | [Validate the contract](#step-10--validate---automated) | ๐Ÿค– Automated | +| 11 | [Serve it to agents](#step-11--serve-it-to-agents---automated) | ๐Ÿค– Automated | +| 12 | [Generate, lint, and render](#step-12--generate-lint-render---rendering-profile-) | ๐Ÿค– Automated (rendering profile: โš–๏ธ) | Step 1 assumes a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase (what [dspack-export](https://github.com/aestheticfunction/dspack-export) diff --git a/README.md b/README.md index 7e693b3..1543224 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Think of it as OpenAPI for design systems. > **Status: v0.4 draft available.** > -> 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. +> 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), the **`required-props` rule type** ("this component must carry named content directly" โ€” the refinement driven by measured projection-gap failures), and two later amendments: **`requiredCategories`** (ยง4.3 โ€” a component must contain a member of a named category) and **S2 sub-component containment** (ยง5.1 โ€” a sub-declared id may appear only inside its declaring compound). It 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. --- @@ -189,7 +189,7 @@ The following milestones represent the current intended direction. They are not | **shadcn/ui example dspack** | A reference dspack file for the [shadcn/ui](https://ui.shadcn.com) component library โ€” _[available](./examples/shadcn-ui.dspack.json)_ | | **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)_ | | **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)_ | -| **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)_ | +| **v0.4 spec draft** | Adds component categories (contract-defined registry, category-based rule selection) and the `required-props` rule type, plus the `requiredCategories` (ยง4.3) and sub-component containment (ยง5.1) amendments โ€” all driven by measured pipeline evidence โ€” _[available](./spec/dspack-v0.4.md)_ | | **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)_ | | **Community RFCs** | Open RFC process for proposing additions and changes to the spec | | **v1.0 spec stabilization** | First stable, versioned release of the specification; breaking changes require a formal process after this point | diff --git a/examples/README.md b/examples/README.md index 99f6196..780c84d 100644 --- a/examples/README.md +++ b/examples/README.md @@ -7,4 +7,4 @@ Example dspack files live in this directory. Examples are intended to help imple - [`shadcn-ui.dspack.json`](./shadcn-ui.dspack.json) โ€” a reference dspack file for the [shadcn/ui](https://ui.shadcn.com) component library - [`astryx.dspack.json`](./astryx.dspack.json) โ€” a governed slice of Meta's [Astryx](https://github.com/facebook/astryx) design system (pinned v0.1.4; published on npm under the `@astryxdesign` scope): 12 components, categories mirroring Astryx's own docs taxonomy, and 14 rules converted from the repository's structured `*.doc.mjs` guidance and the studio's example-expansion governance, each rule with a provenance link (`x-source`). Notable: Astryx components are props-based (labels are required string props; tables and menus are data-driven array props) โ€” a deliberately different idiom from shadcn's compound composition -The shadcn/ui example demonstrates the corpus concepts (tokens, components, patterns, anti-patterns, framework bindings), the v0.3 governance blocks (intents, rules, examples), and the v0.4 additions (component categories, a `required-props` rule, a category-based `forbidden-composition` rule). It validates against the [v0.4 JSON Schema](../schema/dspack.v0.4.schema.json). +The shadcn/ui example demonstrates the corpus concepts (tokens, components, patterns, anti-patterns, framework bindings), the v0.3 governance blocks (intents, rules, examples), and the v0.4 additions: 7 component categories, 26 `required-props` rules, 2 category-based `forbidden-composition` rules, and a `requiredCategories` rule (`rule.form-control-carries-control`). It validates against the [v0.4 JSON Schema](../schema/dspack.v0.4.schema.json). diff --git a/examples/astryx.dspack.json b/examples/astryx.dspack.json index 7fe0f7f..173f842 100644 --- a/examples/astryx.dspack.json +++ b/examples/astryx.dspack.json @@ -2,7 +2,7 @@ "$schema": "../schema/dspack.v0.4.schema.json", "dspack": "0.4", "name": "Astryx", - "description": "A nine-component slice of Meta's Astryx design system (open source, MIT; 160+ components; explicitly guidance-over-enforcement: design opinions live in docs, components render whatever they are passed). This contract converts a subset of that prose guidance into machine-checkable governance. Components and guidance are sourced from the repository's structured *.doc.mjs files at the pinned tag.", + "description": "A twelve-component slice of Meta's Astryx design system (open source, MIT; 160+ components; explicitly guidance-over-enforcement: design opinions live in docs, components render whatever they are passed). This contract converts a subset of that prose guidance into machine-checkable governance. Components and guidance are sourced from the repository's structured *.doc.mjs files at the pinned tag.", "version": "0.1.4", "metadata": { "source": "https://github.com/facebook/astryx/tree/v0.1.4", diff --git a/schema/README.md b/schema/README.md index 796e447..2e451f0 100644 --- a/schema/README.md +++ b/schema/README.md @@ -5,7 +5,7 @@ JSON Schema and related validation artifacts for dspack live in this directory. ## Current schemas - [`dspack.v0.4.schema.json`](./dspack.v0.4.schema.json) โ€” JSON Schema for dspack v0.4 - (current draft; adds component categories and the `required-props` rule type) + (current draft; adds component categories, the `required-props` rule type, and the `requiredCategories` / sub-component-containment amendments) - [`dspack.v0.3.schema.json`](./dspack.v0.3.schema.json) โ€” JSON Schema for dspack v0.3 (adds the governance blocks: `intents`, `rules`, `examples`) - [`dspack.surface.v0_1.schema.json`](./dspack.surface.v0_1.schema.json) โ€” JSON Schema for diff --git a/spec/README.md b/spec/README.md index b0299d2..edd9d42 100644 --- a/spec/README.md +++ b/spec/README.md @@ -6,8 +6,9 @@ Versioned specification documents for dspack live in this directory. - [`dspack-v0.4.md`](./dspack-v0.4.md) โ€” v0.4 specification (current draft, written as a delta over v0.3): component categories (contract-defined registry, membership metadata, - the `forbiddenCategories` rule form) and the `required-props` rule type ("this component - must carry named content directly") + the `forbiddenCategories` rule form), the `required-props` rule type ("this component + must carry named content directly"), and two amendments: `requiredCategories` (ยง4.3) and + S2 sub-component containment (ยง5.1) - [`migration-v0.3-to-v0.4.md`](./migration-v0.3-to-v0.4.md) โ€” migration guide (v0.4 is strictly additive; includes the worked v0.4 deltas from the shadcn contract) - [`dspack-v0.3.md`](./dspack-v0.3.md) โ€” v0.3 specification (written as a diff --git a/spec/migration-v0.3-to-v0.4.md b/spec/migration-v0.3-to-v0.4.md index a09e53e..d408f4a 100644 --- a/spec/migration-v0.3-to-v0.4.md +++ b/spec/migration-v0.3-to-v0.4.md @@ -33,9 +33,9 @@ three v0.3 rule types' semantics are frozen (v0.3 ยง5.5); enumerated ## Worked example: the v0.4 shadcn contract deltas The repository's [`examples/shadcn-ui.dspack.json`](../examples/shadcn-ui.dspack.json) -shows all three additions in use. +shows all four additions in use. -**A registry of two categories, populated where the metadata already lived** (the +**A registry of categories (the worked contract declares seven: interactive, overlay, form, layout, content, feedback, navigation), populated where the metadata already lived** (the `tags` fields sketched the taxonomy; categories make it referenceable by rules): ```json