Repository navigation
feat: split the Button page into an overview and a page per layer - #54
Merged
Merged
Conversation
The Button's page had grown to about 35,000 tokens. As a trial on one component, it's now a folder: an Overview with the intro, At a glance, the checklist, the FAQ and the sources, and a page each for UI, UX, DX, AX and the reference implementation, under one Button group in the sidebar. Agents still read one page. readPages() in server/lib/raw.ts joins the parts back where they came from, so /raw/docs/components/button.md, its contract and the MCP server serve the same Button as before, and a part's path finds the whole page in findPage(). Links from before the split go on to the part with the section, through a route middleware whose map is built from the parts' headings. Links to the Button's moved sections now point at their new pages, and AGENTS.md and CONTRIBUTING.md describe how a page splits into parts. Co-authored-by: multica-agent <github@multica.ai>
The slot-line test compared a substring, so a join that turned #react into ##react still passed: it now compares the part's lines whole. The parts of a split page are pages too, so a test checks each one sets its title, description, sidebar title and where it goes. CONTRIBUTING.md now names joinPage() as the join, and the docs point at the Button's Prompts where they now are. The redirect no longer decodes a hash the router has already decoded, and a part's frontmatter is read the way Nuxt Content reads it. Co-authored-by: multica-agent <github@multica.ai>
alexgrozav
marked this pull request as ready for review
October 20, 2026 21:10
alexgrozav
marked this pull request as draft
October 21, 2026 06:03
The Radio Group's page was the only component page with a number, 5.radio-group.md, against the convention, which failed the test that checks it. The number also sorted it first, so its keep-focus rule came before the Button's in suggestions, which failed the suggestion test. Its URL doesn't change, and the sidebar now lists it by name. Co-authored-by: multica-agent <github@multica.ai>
alexgrozav
marked this pull request as ready for review
October 21, 2026 06:10
alexgrozav
marked this pull request as draft
October 21, 2026 06:59
The Button's Overview now keeps the playground, At a glance, the reference implementation and the sources, and links each layer's page from a card with a large icon that moves on hover and focus. Each layer page ends with its rules table and the questions it answers, and the Code page is gone. joinPage() gathers the rules back under the Checklist and the questions into one FAQ, so /raw, the contract and the MCP server still read one Button page, and agentMarkdown keeps each card as a link. In the sidebar and the header's menu, Button links to its Overview, with a chevron beside it that opens and closes the group, which opens on its pages and closes once you leave them. DocsNavigation.vue renders both, with Nuxt UI's theme, in place of UContentNavigation. Co-authored-by: multica-agent <github@multica.ai>
The sidebar group lists the Overview again, first, and the Button label still opens it, also on the Overview itself after the chevron closed the group. A hovered card's tint took its muted description below 4.5:1 in light mode, so the description darkens on hover. The join's missing-Checklist error has a test, the redirect only reads the map's own anchors, and the docs say where a layer page's rules sit. Co-authored-by: multica-agent <github@multica.ai>
alexgrozav
marked this pull request as ready for review
October 21, 2026 07:49
alexgrozav
marked this pull request as draft
October 21, 2026 07:54
…with the cards Each layer page heads its rules "UI Checklist" and so on, and the Overview's Checklist lists the four as links. The join turns them back into "UI rules" and so on, so the whole page, its contract and the MCP server's rule links stay as they are, and #ui-rules redirects to #ui-checklist. The cards now open At a glance, above its table, without the icon animation, and User Experience has a user icon. Co-authored-by: multica-agent <github@multica.ai>
The cards replace the intro's list of layers, and the At a glance table joins the intro, without its heading. The Checklist names the four layers' checklists in full, and the sidebar names the layer pages without their abbreviation, so each fits on one line. Co-authored-by: multica-agent <github@multica.ai>
…ance At a glance now holds the paragraph on how the examples work, the playground and the table, so the Overview's intro ends with the layer cards, and the whole page agents read has its At a glance section again. Co-authored-by: multica-agent <github@multica.ai>
alexgrozav
marked this pull request as ready for review
October 21, 2026 15:00
This was referenced Oct 22, 2026
alexgrozav
added a commit
that referenced
this pull request
Oct 23, 2026
… layer (#69) ## What changed The other ten component pages now have the shape the Button's got in #54: the Card, Checkbox, Checkbox Group, Dialog, Input, Radio Group, Spinner, Switch, Textarea and Tooltip each become a folder in `content/docs/3.components/`. Each folder holds an Overview and a page per layer: User Interface (UI), User Experience (UX), Developer Experience (DX) and Agentic Experience (AX). The text moves as it is. The only changes are the ones the Button's split made: the cards in place of the intro's list of layers, At a glance starting before the paragraph on examples, the four Checklist links, each part's rules under "UI Checklist" and so on, its questions under its own FAQ, and link targets. Once the Checkbox was a folder, Nuxt Content would have listed Checkbox Group before it, since it sorts by file path and `-` comes before `/`. `app/lib/navigation.ts` keeps the component pages in name order in the sidebar, the header's menu and the links to the previous and next pages. `app/components/UContentSurround.vue` replaces Nuxt UI's to read that order. The tests that covered the Button's split, and the Button-only checks in `scripts/check-mcp.mjs`, now run once for every split component. Links between components go straight to the section's new page. Links from before the split, like `/docs/components/input#sizes`, still land on the right page through the redirect map. In the sidebar and the header's menu, a component's name opens and closes the list of its pages, the Overview and its layers, without navigating, so you pick the page you want. The group still opens on any of its pages and closes once you leave them. Agents see no difference. `/raw/docs/components/<component>.md` and `.yaml`, and the MCP server, serve each component as one page with the outline and contract it has on `main`. The FAQ comes back grouped by layer. A changelog entry announces the change, and `AGENTS.md` and `.github/CONTRIBUTING.md` now say every component page is split like the Button's. It collects these PRs, each reviewed on its own: #56 (component order), #57 (split tests), #58 to #67 (one per component), #68 (links between components, changelog, guides) and #70 (the name opens the group, without navigating). To try it, run `pnpm dev` and open `/docs/components/checkbox`. ## Checklist - [x] The title follows [Conventional Commits](https://www.conventionalcommits.org), as in `feat(docs): add the focus guideline`. - [x] `pnpm check-types` passes. - [x] Docs changes: the pages read well on `pnpm dev`. (Checked on a `pnpm build` served with `wrangler dev`.) - [x] Homepage changes: `pnpm build`, then `pnpm lighthouse`, still scores 100 in every category. (No homepage changes, but the redirect map now covers eleven components and loads on every page, so it ran: 100 in every category on all three runs.) --------- Co-authored-by: multica-agent <github@multica.ai>
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 changed
This is a trial on one component: the Button's page, about 35,000 tokens long, becomes an Overview with a page for each layer, so you can try how a split reads before it goes to the other components.
The Overview keeps the intro, At a glance (the paragraph on how the examples work, the playground and the table, together), the Checklist's intro, the reference implementation and the sources. In the intro, four cards link the layer pages, in place of the list of layers: User Interface (UI), User Experience (UX), Developer Experience (DX) and Agentic Experience (AX). They're the site's own
::cards, restyled inapp/app.config.tswith a large icon. Their descriptions darken on hover, so they keep 4.5:1 against the hover tint. Each layer page ends with its rules table, under "UI Checklist" and so on, and the questions from the FAQ it answers. The Overview's Checklist lists the four, as "User Interface (UI) Checklist" and so on. No text changed apart from link targets, the cards in place of the intro's list of layers, At a glance now starting before the paragraph on examples, and the list of the four checklists.In the sidebar and the header's menu, Button is a link to its Overview, with a chevron beside it that opens and closes its pages: the Overview, then its layers, by name, like "User Experience". The group opens on any of its pages and closes once you leave them. Docus renders both with Nuxt UI's
UContentNavigation, which keeps every group open, soDocsAsideLeftBody.vueandAppHeaderBody.vuerender a sharedDocsNavigation.vueinstead, with Nuxt UI's theme.Agents still read one page.
server/lib/raw.tsjoins the layer pages back in, gathering their rules under the Checklist, as "UI rules" and so on, and their questions into one FAQ, so/raw/docs/components/button.md,/raw/docs/components/button.yamland the MCP server serve the Button as one page, with the outline it has onmainand the same contract. The MCP server reads each card as a link to its layer page, and the FAQ comes back grouped by layer. Links from before the split, like/docs/components/button#loading, go on to the page with the section through a route middleware, whose map is built from the layer pages' headings when the site builds.It also drops the number from the Radio Group's page file,
5.radio-group.md, which was the only numbered component page. That fixes the two tests that fail onmain: the one that checks the convention, and the suggestion test, since the number sorted the Radio Group first and itskeep-focusrule came before the Button's. Its URL doesn't change, and the sidebar now lists it by name.To try it, run
pnpm devand open/docs/components/button.Checklist
feat(docs): add the focus guideline.pnpm check-typespasses.pnpm dev.pnpm build, thenpnpm lighthouse, still scores 100 in every category. (No homepage changes, but the route middleware, its anchor map and the cards' classes load on every page, so it ran: 100 in every category on two of three runs, and 97 for performance on the other, above the 95 budget.)