feat: 🚧 machine-readable component contracts (twins) generated from source - #5167
Draft
sorensensig wants to merge 6 commits into
Draft
feat: 🚧 machine-readable component contracts (twins) generated from source#5167sorensensig wants to merge 6 commits into
sorensensig wants to merge 6 commits into
Conversation
Adds scripts/generate-twins.mjs: one JSON contract per documented component export (real import name, emitted class and data attributes, design tokens, JSDoc summary), plus an llms.txt index for agent discovery. Extracted fields regenerate from source and cannot drift; documentation-prose fields (a11y, composition, relations) are stubbed as authored, never invented. Output (./registry) is gitignored pending a decision on committed-vs-build-time generation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: edea3a7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
7 tasks
…gistry Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Aug 13, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
Summary
First PR of the stack proposed in #5166 (AI-readiness). It adds:
scripts/generate-twins.mjsand apnpm generate:twinsscriptllms.txtindex so agents can discover every contract from one fileSuggestionexport, the only documented component that was missing oneThe generator only writes down what it can read from the source code, so re-running it always matches the code. Rules that live only in the documentation (accessibility, composition, when to use what) are left empty on purpose: the generator never guesses them. They arrive in the next PR of the stack, where every such rule is backed by a verbatim quote from the docs.
Design note: this PR adds
registryto.gitignoreon purpose. The twins are derived output, like a build artifact: committing them would let them drift from the source they are generated from, and would add ~90 JSON files of churn to every component PR. The plan in the stack is to generate them at docs-site build time (the llms.txt PR). What does need review, the authored rules, arrives as committed source data in the next PR. Say so if repo convention prefers committed artifacts and we will flip it.🚧 Draft on purpose: opened early per CONTRIBUTING's suggestion so the work is visible; not ready for merge until the stack's shape is agreed on #5166.
Checks
pnpm changesetif relevant): not relevant, repo scripts and one JSDoc comment only🤖 Generated with Claude Code