Clarify design-system documentation and unify component examples

[mahanti]

Clarify design-system documentation and unify component examples

The design-system viewer mixed navigation categories, text styles, spacing, and example formats. It now separates Foundations, Patterns, Guides, and Components and uses a consistent reading column, heading hierarchy, section rhythm, and responsive navigation.

Component examples share Preview/Code tabs and copyable public API excerpts, inspired by Fluid Functionalism’s documentation layout. Normal previews retain edits while reading code; toast portals hide with their preview without losing unresolved recovery state. Wide pages offer section navigation, and documentation preserves headings, lists, tables, code, and working local links.

Rewrite the six maintained design-system documents and viewer guidance in clearer language, simplify the Forms overview, remove the requested Foundation alignment page, and fix the standalone viewer’s Bestie artwork URL. Preserve the latest row-end button, flex-body dialog, and end-aligned Select examples from main.

Validation

Checked cleanup committed as ceb8b0f0, with unchanged source content from the reviewed snapshot on f3676ce7:

• App build/typecheck and design typecheck/build pass.
• Design checks pass with existing documented contrast exceptions.
• Design unit tests: 20 files, 120 tests pass.
• Mandatory pre-commit/pre-push hooks pass, including secret scanning, source checks, TypeScript, 186 unit files / 2,344 tests, and design guards. Worktree hooks preserve and run the global LHM checks as well as repository checks. Rust checks were not selected because this cleanup has no Rust changes.
• Hosted CI required and DCO Check pass at ceb8b0f0. The original native job timed out downloading Ubuntu packages before Rust checks ran; a targeted rerun at the unchanged head passed without code, workflow, timeout, or test changes.
• Changed-source Biome, documentation links/anchors, and diff checks pass.
• Full viewer browser file, Chromium and WebKit, one worker and no retries: 76 pass, 2 fail in 1.5 minutes. Both failures are the same inherited modal/F6 defect described below.
• Exercised the actual fixture viewer: Preview/Code, Copy, toast recovery restoration, dialog scrolling, mobile navigation, and light/dark reading layouts. Screenshots use fixture data.

Browser coverage

Three scenarios added cover native navigation/focus and hash scrolling, responsive tables/token labels, and code-panel keyboard scrolling with contents navigation. These require real browser geometry and focus. One Foundation alignment scenario was removed with that deleted page; no retained behavior loses coverage. Six new React unit cases cover Markdown rendering/links, preview state, clipboard success/failure, and toast portal lifecycle.

Regression evidence: the toast portal test fails before the visibility fix and passes afterward. Earlier renderer, WebKit table-scroll, and route-contents failures also failed before their fixes and passed afterward. The modal test now waits for initial focus before testing F6, retaining the containment assertion rather than accepting an autofocus race.

Known limitations

• Inherited failure: after opening the Toast example’s dialog and waiting for Close to receive focus, F6 moves focus into the notification stack. The same failure reproduces in both engines with main’s unchanged ToastSpecimens and unchanged shared Toast/Dialog code. Shared modal behavior is outside this documentation cleanup.
• Human tested and accepted the current design viewer snapshot on October 1, 2026. Native/assistive-technology checks remain unperformed confidence gaps.
• Independent CI remediation review: 9/10, no new blockers; the targeted rerun changed no code or coverage.

buzz-review-completed

Screenshots

Four screenshots and capture notes are saved locally for attachment. They have not been uploaded to GitHub.

[wesbillman]

Carl, an automated reviewer, commenting via Wes’s GitHub account.

No introduced blockers found. 9/10; one optional excerpt correction inline. This is a comment review, not an approval.

Reviewed head ceb8b0f0027ab27db6ba41a92cb8c3c8df87c2a4 against target base 55f96c256e9af418041f7a79d838ce3fdc65b1ac, using merge-base f3676ce7215519ce576de265f6b7c23f6cacbdc2 for the PR diff. All three independent review lanes returned before consolidation.

• Existing applicable hosted checks pass. Built the standalone viewer and exercised Chromium and WebKit: preview draft retention, toast hide/restore/resolve, cross-document anchor scrolling, mobile navigation/focus/overflow, and the emitted Bestie image. Those focused checks passed with no page errors.
• Reproduced the disclosed modal/F6 escape in both engines, including with the base ToastSpecimens substituted into the head viewer. Shared Toast/Dialog source is identical to the target base; this is not a new blocker for this cleanup.
• Native and assistive-technology validation remain unperformed. Broad suites were not rerun locally; this does not claim full accessibility certification or authorize merge.

[wesbillman]

Optional: retain React keys in the copyable mapped examples. Removing the viewer-only Specimen wrappers also removed their keys: the Avatar excerpts here and at lines 332–368, plus the InlineChip excerpt at lines 1236–1242, now return unkeyed components from .map(). The live previews are keyed, so their checks do not exercise the copied version, which produces React's missing-key warning. Put key={size} / key={status} on the returned Avatars and key={row.label} on InlineChip. The fixed sample arrays make this non-blocking.