docs: v0.4 is four additions, not two; repair the ADOPTING table of contents - #43
Merged
Conversation
…ontents 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 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates repository documentation to reflect the full set of dspack v0.4 additions/amendments (including requiredCategories and S2 sub-component containment), corrects example descriptions, and repairs broken intra-doc navigation links in the adoption guide.
Changes:
- Refresh v0.4 summaries across
README.md,spec/README.md,schema/README.md, and the v0.3→v0.4 migration guide to reflect four additions/amendments. - Correct example documentation: Astryx component count wording and a more specific accounting of what the shadcn/ui contract demonstrates.
- Fix
ADOPTING.md“journey at a glance” ToC anchors to match the actual headings.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/README.md | Updates v0.4 spec summary to include the two later amendments. |
| spec/migration-v0.3-to-v0.4.md | Aligns the worked-example narrative with four v0.4 additions and the real category set. |
| schema/README.md | Updates the v0.4 schema blurb to mention the additional amendments. |
| README.md | Updates top-level project overview + milestone table to reflect v0.4 amendments. |
| examples/README.md | Makes the shadcn/ui example feature summary more specific/quantified. |
| examples/astryx.dspack.json | Fixes Astryx contract description to match the shipped component count. |
| ADOPTING.md | Regenerates broken “jump to step” anchors using GitHub slug rules. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
7
to
9
| - [`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 |
| - [`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). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
From an ecosystem-wide documentation audit.
The v0.4 summaries never caught up with the spec's own amendments. §4.3
requiredCategories(2026-08-07) and §5.1 S2 sub-component containment are normative, schema-backed, used in the worked contract, and evaluated by dspack-gen — but README (×2),spec/README.md, andschema/README.mdall still described v0.4 as "component categories and therequired-propsrule type". The migration guide said "all three additions" and illustrated "a registry of two categories" (the worked contract declares seven).The reference artifact contradicted its own README:
examples/astryx.dspack.jsondescribed itself as "a nine-component slice" while shipping twelve.examples/README.mdalso understated the v0.4 features the shadcn example demonstrates (7 categories, 26required-props, 2forbidden-composition, and arequiredCategoriesrule that went unmentioned).All 12 ADOPTING.md ToC anchors were broken — hand-written up to the em-dash while the headings carry a trailing mode label (
— 🤖 Automated), so every "jump to step N" link failed. Regenerated from the real headings using GitHub's slug rules.Verified:
npm run validatepasses both examples; negative fixtures still refuse. The CLI, exports, schema, and every relative link audited clean and are untouched.🤖 Generated with Claude Code