[Do Not Merge]feat(docs): add docs.llm.md MVP generator for 1st-gen components - #6396
Open
blunteshwar wants to merge 10 commits into
Open
blunteshwar wants to merge 10 commits into
blunteshwar wants to merge 10 commits into
Conversation
Ship the end-to-end MVP slice from the docs.llm.md RFC (SWC-2277): a deterministic generator that derives an LLM-consumable markdown file from each 1st-gen component README, plus generated output for the 5 MVP components (button, picker, menu, action-button, dialog). The transform is script-only (no LLM in the loop). It strips Storybook and docs-site chrome from the README — shield badges, sp-tabs/sp-tab/sp-tab-panel wrappers, `demo` code-fence modifiers — collapses blank-line runs, and prepends a small metadata frontmatter block (component, tag, package, source, generated timestamp, generator). Same input always yields the same output, so files can be regenerated and diffed in CI to detect drift from the README. New scripts: - yarn generate:llm-docs write docs.llm.md (all MVP, or named components) - yarn generate:llm-docs:check drift gate for CI (timestamp-insensitive) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: ca50869 The changes in this PR will be included in the next version bump. This PR includes changesets to release 84 packages
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 |
blunteshwar
marked this pull request as draft
June 11, 2026 15:25
blunteshwar
changed the title
blunteshwar
marked this pull request as ready for review
June 17, 2026 10:37
…docs package
Extend the docs.llm.md generator from the 5-component MVP to every Spectrum 1
component, and add the optional aggregate package that bundles them.
Generator changes (scripts/generate-llm-docs.mjs):
- Auto-discover components: any 1st-gen package whose README registers a
custom element via a `@spectrum-web-components/{name}/sp-*.js` side-effect
import. Icon-set and tooling packages are skipped. 62 components found.
- Default run now generates the full set; `--mvp` restricts to the original 5
and named arguments still scope to specific components.
- Each component is written from one generated string to two locations so they
stay byte-identical: the per-component `docs.llm.md` beside the README and the
aggregate `{component}.llm.md` in the new package.
- `--check` verifies both copies and the aggregate README, ignoring the
generated timestamp.
New package (@spectrum-web-components/llm-docs):
- Lives at 1st-gen/projects/llm-docs so yarn constraints does not treat it as a
component workspace (which would force a src entry point). It is still a
published workspace via the @spectrum-web-components/* fixed changeset group.
- Ships one {component}.llm.md per component plus a generated index README.
- Optional install for AI assistants and build-time tools that want the docs as
plain markdown, kept out of the per-component tarballs to keep them lean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…utput Two issues surfaced when scaling the generator to all 62 gen1 components: - The chrome-stripping rules ran on every line, including inside fenced code blocks. For most components `<sp-tabs>` / `<sp-tab>` / `<sp-tab-panel>` are Storybook layout chrome, but for the Tabs component itself they are the literal example markup, so its demos were gutted to empty code fences. Chrome rules now run only outside fenced code blocks; fenced content is preserved verbatim. Any block left empty after stripping is dropped. - Generated markdown is a build artifact, but Prettier reformatted it on commit, which broke `yarn generate:llm-docs:check`. The per-component `docs.llm.md`, the aggregate `*.llm.md`, and the aggregate README are now in .prettierignore, so the generator output stays canonical and the drift check is authoritative. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a `lint:llm-docs` step that runs the generator's `--check` drift gate, and include it in the root `lint` chain. CI now fails when a component README has changed without its `docs.llm.md` and aggregate copy being regenerated, keeping the source of truth and the generated files in sync. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Keep package.json and README.md visible at the llm-docs package root instead of
burying them among 62 markdown files. The aggregate `{component}.llm.md` files
now live in 1st-gen/projects/llm-docs/src/; the generated index README links
into src/ and the package `files` field publishes src/*.llm.md. The
per-component docs.llm.md beside each README is unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a skill that grounds UI work in the @spectrum-web-components/llm-docs package. On invocation it ensures the docs are available (already installed, the local monorepo copy, or a fresh devDependency install via the detected package manager), reads the authoritative per-component docs, and builds with Spectrum Web Components only, using real tags, imports, attributes, and variant values instead of guessed ones. - SKILL.md: mindset, when/when-not, the ensure -> read -> build -> verify workflow, fallbacks (docs-site mirror, component README) for when the package cannot be installed, and a common-name to component lookup table. - scripts/ensure-llm-docs.mjs: resolves the docs directory (node_modules, then monorepo, then install), lists documented components, and prints the path to requested component docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…utput The `generated:` ISO timestamp in each file's frontmatter changed on every run, so regenerating produced a 124-file diff of pure noise and the `--check` gate had to special-case it. Remove the timestamp: generation is now fully deterministic, the same README always yields byte-identical output, regenerations stay out of the git diff, and the drift check is a plain equality test. Provenance is still captured by `source:` and `generator:` in the frontmatter and by git history. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a skill that grounds UI work in the @spectrum-web-components/llm-docs package. On invocation it ensures the docs are available (already installed, the local monorepo copy, or a fresh devDependency install via the detected package manager), reads the authoritative per-component docs, and builds with Spectrum Web Components only, using real tags, imports, attributes, and variant values instead of guessed ones. - SKILL.md: mindset, when/when-not, the ensure -> read -> build -> verify workflow, fallbacks (docs-site mirror, component README) for when the package cannot be installed, and a common-name to component lookup table. - scripts/ensure-llm-docs.mjs: resolves the docs directory (node_modules, then monorepo, then install), lists documented components, and prints the path to requested component docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Annotate generate-llm-docs.mjs and the skill's ensure-llm-docs.mjs line by line so the chrome-stripping rules, fence handling, drift check, package-manager detection, and docs resolution are self-explanatory. No behavior change. Co-Authored-By: Claude Opus 4.8 <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
2 participants
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.
Description
Ships the end-to-end MVP slice from the docs.llm.md RFC (SWC-2277): a deterministic generator that derives an LLM-consumable markdown file from each 1st-gen component README, plus generated output for the 5 MVP components.
The generator is script-only — no LLM in the loop. Same input always yields the same output, so files can be regenerated and diffed in CI to detect drift from the README.
What it does
Reads
1st-gen/packages/<name>/README.md, applies deterministic chrome-stripping, and writes1st-gen/packages/<name>/docs.llm.md:<sp-tabs>/<sp-tab>/<sp-tab-panel>Storybook wrappers (inner demos kept)```html demo,demo ignore,demo open) to plain```htmlIt prepends a small metadata frontmatter block:
component,tag(derived from the README side-effect import),package,source,generated(ISO timestamp),generator.New scripts
yarn generate:llm-docs— writedocs.llm.md(all MVP components, or pass specific names)yarn generate:llm-docs:check— drift gate for CI; timestamp-insensitive, exits non-zero when on-disk files are staleMotivation and context
The RFC (wiki 3854270520) proposes shipping one LLM-friendly markdown file per component, derived mechanically from the existing documentation source of truth (README for 1st-gen). This PR proves the pipeline end-to-end on a 5-component slice before committing to the full generator + 69-component backfill, de-risking the RFC's architectural choices against real output.
Related issue(s)
MVP components
button,picker,menu,action-button,dialog— chosen to stress different generator edge cases: simple, near-duplicate, slotted, composition-heavy, and overlay + a11y-heavy.Scope note for reviewers
This deterministic transform produces chrome-stripped README + frontmatter. It does not synthesize the richer curated format (When-NOT-to-use, Common-LLM-mistakes, S1→S2 tables) seen in earlier hand-authored examples — that content cannot be derived from a README alone. Extracting structured frontmatter (sizes/variants/slots) is a deliberate follow-up if the RFC wants it. The full generator (SWC-2204) must later produce byte-equivalent output to these files (modulo timestamp).
Author's checklist
Manual review test cases
Generator produces expected output
yarn generate:llm-docsdocs.llm.mdfiles written under1st-gen/packages/{button,picker,menu,action-button,dialog}/<sp-tab,html demo, orimg.shields.ioresidue remainsDrift gate works
yarn generate:llm-docs:checkyarn generate:llm-docs, re-run check, expect "up to date"Accessibility testing checklist
Keyboard (required)
Screen reader (required)
🤖 Generated with Claude Code