feat: Astryx contract slice — 9 components, 6 rules from Meta's own doc source (PR-19)#14
Merged
Conversation
…oc source (PR-19) M3 plan Phase 3, ADR-M3-5 as confirmed: a governed slice of Astryx (MIT, guidance-over-enforcement), pinned v0.1.2 (commit 6c533c70), authored from the repository's structured *.doc.mjs files — component descriptions, prop tables, and do/don't bestPractices are machine-readable at the source, so every component and rule carries an x-source provenance link to the exact file at the pinned tag. Structural findings the contract documents (write-up material): - Astryx is PROPS-BASED where shadcn is compositional: AlertDialog carries title/description/actionLabel as required string props (no trigger sub-component); Button.label is the required accessible name. The shadcn projection-gap class is structurally impossible here — governance shifts to prop-presence rules (required-props' prop form, used in anger). - Tables and menus are DATA-DRIVEN (array props), documented as such; generation-schema array support surfaces in the pipeline leg. - IconButton is EXCLUDED: its required icon prop is ReactNode, not surface-expressible (documented honest scope). Rules (all provenance-quoted): destructive-requires-alertdialog (component-choice; the AlertDialog/Dialog analog), alertdialog-carries- content + button-carries-label + input-carries-label (required-props, prop form), alertdialog-action-label-specific (forbiddenProps — 'OK'/'Confirm' forbidden verbatim from the guidance), dialog-no-nested-overlays (forbiddenCategories; categories mirror Astryx's own taxonomy). validate green (both example contracts). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new governed example contract for Meta’s Astryx design system (pinned to upstream v0.1.2) to illustrate a props-based, doc-derived component slice and corresponding governance rules, and links it from the examples README.
Changes:
- Added
examples/astryx.dspack.json: Astryx slice (9 components) with categories, intents, 6 governance rules, and a worked example surface. - Updated
examples/README.mdto list and describe the new Astryx example contract.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| examples/README.md | Adds the Astryx example to the examples index with a brief description. |
| examples/astryx.dspack.json | Introduces a new dspack v0.4 contract example for Astryx with components, categories, rules, and an example surface. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…rsion alignment
- description says 'nine-component slice' (was '~10', the map has 9)
- top-level version now 0.1.2, matching the pinned upstream tag per the
schema's documented meaning ('version of the design system content') —
the pin (metadata.x-upstream) and the displayed version now agree
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
What
M3 plan Phase 3, PR-19 (ADR-M3-5 as confirmed):
examples/astryx.dspack.json— a governed slice of Astryx (MIT, explicitly guidance-over-enforcement), pinned v0.1.2 (commit6c533c70).The authoring story (write-up material)
Astryx's "agent-ready" claim turned out to be literally true for contract authoring: the repo ships structured
*.doc.mjsfiles per component — descriptions, full prop tables, andbestPracticesentries with machine-readable do/don't flags. The contract's component entries are derived from Meta's own doc source, and every component and rule carries anx-sourceprovenance link to the exact file at the pinned tag. Categories mirror Astryx's own docs taxonomy.Structural findings the contract documents
AlertDialogcarriestitle/description/actionLabelas required string props — no trigger sub-component.Button.labelis the required accessible name. The shadcn projection-gap class is structurally impossible in this API — governance shifts to prop-presence rules (required-props' prop form, now used in anger). The ADR-M3-5 caveat (Astryx does not exercise the A2UI projection gap) is confirmed from the API side.Table(data/columns) andDropdownMenu(items) take array props, not children — documented as array-typed props; generation-schema array support will surface in the pipeline leg (PR-20).iconprop is ReactNode — not surface-expressible.The rules (each provenance-quoted in its rationale)
destructive-requires-alertdialogalertdialog-carries-contentalertdialog-action-label-specificbutton-carries-labelinput-carries-labeldialog-no-nested-overlaysThe conversion-rate finding (previewed; quantified in the Phase 3 findings)
Not everything converts — the misses are ceiling evidence, verbatim: "don't place more than one primary button in the same view" (max-cardinality, a documented v0.4 ceiling item), "don't use the destructive variant without a confirmation step" (ancestor requirement), plus quality judgments ("labels that describe the action") and runtime behaviors (loading states). The full do/don't census lands with the eval leg.
Acceptance
npm run validate— green (both example contracts; the worked example passes S1/S2 + referential consistency and satisfies all six rules).Hand-review surface
The contract itself — the second-biggest review artifact of M3 (per the plan). Every claim in it is checkable against the pinned
x-sourcefiles.🤖 Generated with Claude Code