[mvilacad]

Closes #123

Every page in site/src/content/docs/** was checked against the 3.0.0 source, the generated manifest (dist/components.json) and the CLI. Two guard tests now keep it that way.

Guards (test first)

Test	Fails when	Evidence
packages/ui/tests/docs-accuracy.test.ts	a <Props> row names a prop the component lacks, a documented default differs from the source, a code fence imports a name the entry point does not export, a sample passes an undeclared prop, a /docs/ link or #anchor is dead, a <Props> literal is not valid JS (breaks the MDX build), an exported component is never mentioned	Before: 5 of the 9 checks failed (33 wrong props, 2 wrong defaults, 2 bad imports, 5 bad sample props, 14 undocumented components). After: 11 pass. The valid-JS check was proven on the real broken line (button.mdx, unescaped quote): fails with it, passes without.
packages/ui/tests/docs-samples.test.ts + scripts/check-docs-samples.ts	a svelte fence that imports the package does not compile under svelte-check against dist types (unknown export, wrong prop value, TS in a plain script, unclosed block)	104 samples, 2s. It reported 7 real errors before the fixes; a self-test feeds it a bad sample and requires the failure.

<Props> takes a for="Component[, Component]" attribute (or for="none" for tables that do not describe a component); without it the guard infers the component from the title or the page name.

Inaccuracies fixed (page | what was wrong)

Getting started

• installation | Release channels described alpha/beta by branch; releases are by tag (latest, X.Y.Z-beta.N as dist-tag beta, any other prerelease id as its own tag). Optional-peer table missed axe-core, @resvg/resvg-js + png-to-ico (caBrandPlugin), typescript (migrate), @sveltejs/kit, astro. No section described init: added flags (--write, --dir), the create/ok/diff/patch/manual/skip lines, exit codes, final messages. The files table was wrong (vite.config.ts and app.html are only patched; skip when missing; manual when no viewport meta). Astro section did not match what init writes.
• theming | defaultStyle listed 4 of 9 styles; density, controlRadius, border, elevation, typography, motion, noise undocumented; ThemeOptions imported from the root (not loadable in Node config) instead of /vite and /astro; DESIGN_STYLES and mergeTheme not described.
• seo | og.imageType and the twitter.card fallback missing; caBrandPlugin options (mark, theme, outDir, base, manifestFile, name) undocumented, and outDir is emptied first; missing imports in the vite sample; dev warnings incomplete.
• pwa | manifest colors and defaults, short_name default, per-icon type, extra, and the real tags appleMeta emits.
• mobile | several breakpoints said 768px; input zoom guard, Sheet, StickyActions, AuthLayout are 900px. Wrong input-selector list, Sheet dismiss threshold (0.5 px/ms), MobilePane onback, press-scale (Button only).
• performance | font sample used a non-existent defineTheme(...) as the theme.
• accessibility | "All overlays trap focus and lock scroll" (only modal layers do; popovers, menus, Select, Combobox, date pickers close on Escape/outside press); reduced motion zeroes --ca-motion-scale; dead anchor #skip-link.
• i18n | pagination.nextPage does not exist (pagination.next); unclosed <I18nProvider> sample.
• ai-agents | said AGENTS.md is Portuguese (English); recommended the deprecated Row; migrate coverage (.js, default src, GlassCard/GlassSurface/Row codemod) and --dir, guides.json, search_tokens 60-match cap.
• index | pitched glass as the default look; stale counts.
• docs-kit/docs | pager prop and CodeTabs.tabs missing; DocsNav item shape.
• charts/index | "tooltips use the glass material"; echarts v6 peer and hex/rgb note.

Surfaces, layout, foundation

• surface | radius default documented as 'lg' (source: undefined, falls back to --ca-radius-lg); liquid also uses the blur tiers; glow is transparent under solid/flat; interactive needs a link/button or role; forced-colors exception for ghost; no mention of the 3.0 solid default.
• card | interactive missing from passed-through props; auto is opaque under solid, glass under liquid; demo wording ("backlit halo", "gradient overlay").
• accordion | keyboard wording (Arrow Up/Down, Home, End); single-mode value is '' when closed; demo cited GlassSurface/GlassCard.
• glass-card, glass-surface | no migration snippets; the codemod writes material="liquid" or "glass".
• app-shell | onNavigate row wrong (panel items are plain links; it fires on module switch); defaultModule and stored module; panel skipped for a module with fewer than two destinations; code samples missing lang="ts" and the SiteHeader import; PanelNavItem, SectionGroup undocumented.
• page-shell | gap/maxWidth defaults were literals (source: undefined); title renders the page <h1>.
• sticky-actions | called glass; fill is --ca-glass-bg, blurred only under glass/frosted.
• typography, shadows, materials | --ca-font-scale, kit does not load Inter/JetBrains Mono, --ca-font-display default; "soft warm shadows" and "glass relies on inset highlights" were 2.x claims; materials presented everything as Liquid Glass.
• form-page | table named FormPage (removed; the component is AppForm).

Inputs

• button | children missing; loading description wrong; an unescaped quote in a Props string broke the MDX build.
• date-picker | arrows move by day (up/down by week); hourCycle, fixedWeeks, closeOnRangeSelect were attributed to every component.
• radio | variant, aria-label, item description undocumented; claimed roving focus (native radios).
• text-area | claimed a floating label; select | "glass panel", no native form submit note; combobox | accessible name falls back to ariaLabel; toggle-group | undefined items in sample, roving focus only in single mode; export-menu | label default, columns semantics.
• masked-field, money-input | leading / trailing, PhoneField.*, CepField.* rows combined several props in one name.

Display, feedback, navigation

• table | documented SimpleTable; cards below 600px of the table width (not 900px), captions from thead; image | srcset/sizes are forwarded native attributes, not props.
• data-table | User/users undeclared in samples; DataTableToolbar, DataTablePagination, DataTableColumnHeader, DataTableColumnToggle, DataTableFacetedFilter undocumented.
• alert | role="alert" with polite live region; badge | missing IconButton import, role="status" label; divider | recommended Row; notification-bell | onRead only for unread items; pagination | keyboard and aria-current; scroll-area | viewport is focusable; tooltip | focus, Escape, touch, 300ms skip window; duplicate order values.
• dialog | claimed aria-modal (native showModal), split breakpoint 900px, LayerChange/LayerInfo/LayerKind and onLayerChange undocumented; sheet | 768px (is 900px); alert-dialog | initial focus, "rethrown"; drawer | missing Button import; progress, skeleton, toast | aria-valuemin, "rather than", a fence with two <script> blocks.
• actions | scrollFocusable missing, clipboard/longpress events; menu | DropdownMenuLabel only in a demo; tabs | TabsList undocumented, automatic activation; stepper | bubbles are buttons; breadcrumb, command-palette, popover, navigation/drawer | behavior and layer notes.

New pages (exported components with no docs)

Kbd, FilterGroup, SettingItem, Lightbox, ErrorPage, AuthLayout + AuthCard, LiquidGlass. The nav is derived from the collection, so they appear with no list to edit. Mentions added for PanelNavItem, SectionGroup, DropdownMenuLabel, the DataTable* parts.

Core: packages/ui

• KpiCard rendered the deprecated GlassCard (every KPI card logged the [ca-ui] deprecation warning). Now Card elevation={3}. Test first: KpiCard.svelte.test.ts "is built on Card" failed (.ca-glass-card present), passes after. Patch changeset.
• FilterGroup label used --ca-text-hint; the new route axe spec failed color-contrast in dark mode on a custom preset (4.11:1). Now --ca-text-secondary. Test first: contrast.test.ts "label role is not the hint role" failed, plus a 4.5:1 check per preset and scheme on every surface (172 pass). Patch changeset.
• Sheet doc comment said 768px (CSS is 900px); it feeds the manifest.
• New: scripts/check-docs-samples.ts, tests/docs-accuracy.test.ts, tests/docs-samples.test.ts.

Site: site/ and config

• Docs content (~70 pages), demos for the new pages and radio/Cards.svelte.
• biome.json and .gitignore ignore site/.cache (sample extraction output).

Verification

• bun run validate: ok (21.7s).
• Browser: KpiCard, FilterGroup, Sheet component tests pass (27).
• Site e2e (docs, smoke, routes a11y in dark/light/forced-colors, layout; desktop, mobile, a11y): 1063 passed, 0 failed. The a11y run caught the FilterGroup contrast bug above before the fix.

Not done

• VRT baselines for KpiCard and FilterGroup are regenerated on CI (bun run test:vrt:update), the only place they are rendered.
• SwatchGroup (landing branch site: landing scroll jump in theme section, livelier hero app, sketchbook polish #122) is not in main; the coverage guard will require its page when it lands.
• Reported, not changed: Row keeps align="start" as a deliberate legacy default; --ca-elevation-* tokens are missing from dist/tokens.json; Rail, Panel, BottomNav, MobileHeader have no props tables.

[github-actions]

Site preview: https://pr-125.codeatlas-ui.pages.dev