docs: teach component setup with verified examples

app/pages/accessibility.wrn

@@ -8,9 +8,13 @@ page AccessibilityGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Accessibility</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Getting Started</span><h1>Accessibility</h1><p>Keyboard interaction, visible focus states, labels, and reduced-motion support ship by default.</p></header>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>bunx wrnexus test accessibility .
+bunx wrnexus security headers .</code></pre><h3>What changes after this</h3><p>Keyboard, focus, naming, contrast, zoom, and reduced-motion behavior become explicit acceptance criteria.</p></section>
       <section class="guide-section"><h2>Keyboard first</h2><p>Every interactive control must be reachable in a logical order and operable without a pointer. Preserve native elements and the component's documented keyboard behavior.</p></section><section class="guide-section"><h2>Names and descriptions</h2><p>Provide visible labels or accessible names for icon-only actions. Associate help and validation messages with their fields rather than relying on color alone.</p></section><section class="guide-section"><h2>Focus and overlays</h2><p>Keep visible focus rings. Modal, drawer, dropdown, and popover components manage focus and dismissal; test Escape, Tab, Shift+Tab, and focus restoration.</p></section><section class="guide-section"><h2>Motion and contrast</h2><p>Theme tokens preserve semantic contrast, while components honor reduced motion. Verify custom colors in light and dark modes at 200% zoom.</p></section>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>bunx wrnexus test accessibility .
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
-bunx wrnexus security headers .</code></pre></section>
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/colors.wrn

@@ -8,9 +8,13 @@ page ColorsGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Colors</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Customization</span><h1>Colors</h1><p>Semantic primary, secondary, success, warning, danger, and info tokens remain available in every palette.</p></header>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>&lt;Button color="primary"&gt;Save&lt;/Button&gt;
+&lt;Alert color="danger"&gt;Unable to save&lt;/Alert&gt;</code></pre><h3>What changes after this</h3><p>Status and hierarchy use named semantic roles that remain understandable in both light and dark modes.</p></section>
       <section class="guide-section"><h2>Semantic roles</h2><p>Primary and secondary communicate hierarchy; success, warning, danger, and info communicate state. Use roles consistently instead of choosing colors by appearance.</p></section><section class="guide-section"><h2>Component colors</h2><p>Every maintained component accepts the shared color contract. Prefer the color prop for supported variants and tokens for application-owned surfaces.</p></section><section class="guide-section"><h2>Accessible combinations</h2><p>Check text, icons, borders, hover, focus, selected, and disabled states. Never make color the only carrier of meaning.</p></section><section class="guide-section"><h2>Brand overrides</h2><p>Define brand values once through theme tokens. Derived surfaces and on-colors keep contrast coherent across light and dark modes.</p></section>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>&lt;Button color="primary"&gt;Save&lt;/Button&gt;
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
-&lt;Alert color="danger"&gt;Unable to save&lt;/Alert&gt;</code></pre></section>
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/dark-mode.wrn

@@ -8,11 +8,15 @@ page DarkModeGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Dark mode</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Customization</span><h1>Dark mode</h1><p>Choose light, dark, or system mode. The selection persists and updates every preview.</p></header>
-      <section class="guide-section"><h2>Choose a default</h2><p>Set light, dark, or system in wrnexus.config.ts. System mode follows the operating-system preference until the user selects an explicit value.</p></section><section class="guide-section"><h2>Persist preference</h2><p>Use PreferenceSwitcher or your own control to update the document theme. The selected value persists and is applied before interactive components hydrate.</p></section><section class="guide-section"><h2>Author with tokens</h2><p>Use semantic --wire-* variables instead of hard-coded light colors. Tokens switch surfaces, text, borders, focus, and status colors together.</p></section><section class="guide-section"><h2>Test both modes</h2><p>Check content, overlays, charts, disabled controls, focus rings, and browser autofill in both modes. Do not treat dark mode as a simple color inversion.</p></section>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>theme: <span>&#123;</span>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>theme: <span>&#123;</span>
   default: "system",
   palette: "violet",
-<span>&#125;</span></code></pre></section>
+<span>&#125;</span></code></pre><h3>What changes after this</h3><p>The initial server document and hydrated client agree on light, dark, or system mode without a theme flash.</p></section>
+      <section class="guide-section"><h2>Choose a default</h2><p>Set light, dark, or system in wrnexus.config.ts. System mode follows the operating-system preference until the user selects an explicit value.</p></section><section class="guide-section"><h2>Persist preference</h2><p>Use PreferenceSwitcher or your own control to update the document theme. The selected value persists and is applied before interactive components hydrate.</p></section><section class="guide-section"><h2>Author with tokens</h2><p>Use semantic --wire-* variables instead of hard-coded light colors. Tokens switch surfaces, text, borders, focus, and status colors together.</p></section><section class="guide-section"><h2>Test both modes</h2><p>Check content, overlays, charts, disabled controls, focus rings, and browser autofill in both modes. Do not treat dark mode as a simple color inversion.</p></section>
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/fonts.wrn

@@ -8,11 +8,15 @@ page FontsGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Fonts</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Customization</span><h1>Fonts</h1><p>Select a font family globally while components continue to inherit typography correctly.</p></header>
-      <section class="guide-section"><h2>Configure families</h2><p>Declare the application sans family and optional hosted families in wrnexus.config.ts. Components inherit typography without per-component imports.</p></section><section class="guide-section"><h2>Control loading</h2><p>Request only used weights and styles. Keep a system fallback so content remains readable before hosted fonts finish loading.</p></section><section class="guide-section"><h2>Preserve hierarchy</h2><p>Use semantic heading, body, label, caption, and code roles. Avoid arbitrary sizes that break density and responsive rhythm.</p></section><section class="guide-section"><h2>Test real content</h2><p>Check long headings, translated labels, numeric tables, code, and form errors. Font choices must remain legible at zoom and on narrow screens.</p></section>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>fonts: <span>&#123;</span>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>fonts: <span>&#123;</span>
   sans: '"Plus Jakarta Sans", system-ui, sans-serif',
   google: [<span>&#123;</span> family: "Plus Jakarta Sans", weights: [400, 500, 600, 700] <span>&#125;</span>],
-<span>&#125;</span></code></pre></section>
+<span>&#125;</span></code></pre><h3>What changes after this</h3><p>Typography loads only required families and weights while preserving a readable system fallback.</p></section>
+      <section class="guide-section"><h2>Configure families</h2><p>Declare the application sans family and optional hosted families in wrnexus.config.ts. Components inherit typography without per-component imports.</p></section><section class="guide-section"><h2>Control loading</h2><p>Request only used weights and styles. Keep a system fallback so content remains readable before hosted fonts finish loading.</p></section><section class="guide-section"><h2>Preserve hierarchy</h2><p>Use semantic heading, body, label, caption, and code roles. Avoid arbitrary sizes that break density and responsive rhythm.</p></section><section class="guide-section"><h2>Test real content</h2><p>Check long headings, translated labels, numeric tables, code, and form errors. Font choices must remain legible at zoom and on narrow screens.</p></section>
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/framework-guides.wrn

@@ -8,9 +8,13 @@ page FrameworkGuidesGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Framework guides</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Getting Started</span><h1>Framework guides</h1><p>WRNexus components use native HTML semantics and framework component mounts.</p></header>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>bunx wrnexus inspect component Navbar .
+bunx wrnexus typecheck .</code></pre><h3>What changes after this</h3><p>The page depends on public component props, slots, and outputs, so framework upgrades do not depend on private markup.</p></section>
       <section class="guide-section"><h2>Mount components</h2><p>Use the component mount name directly in .wrn views. Props are typed, slots remain server-rendered, and declared outputs reach parent bindings.</p></section><section class="guide-section"><h2>Own page composition</h2><p>Keep application structure in pages and layouts. Use library components for reusable behavior, then add application-specific styles in the owning .wrn file.</p></section><section class="guide-section"><h2>Prefer semantic contracts</h2><p>Choose props, slots, and outputs over selectors that depend on a component's internal markup. This keeps applications compatible with framework upgrades.</p></section><section class="guide-section"><h2>Inspect before integrating</h2><p>Use the CLI component inspector for the exact prop, slot, and output contract, then type-check the finished page.</p></section>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>bunx wrnexus inspect component Navbar .
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
-bunx wrnexus typecheck .</code></pre></section>
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/installation.wrn

@@ -8,11 +8,15 @@ page InstallationGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Installation</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Getting Started</span><h1>Installation</h1><p>Install the package and import the shared stylesheet once in your application.</p></header>
-      <section class="guide-section"><h2>Prerequisites</h2><p>Use Bun 1.3 or newer and a WRNexus application whose framework packages share the same version. Private-preview installs require npm credentials with access to the @wrnexus scope.</p></section><section class="guide-section"><h2>Install the UI package</h2><p>Add @wrnexus/ui to the application. The dev server and production builder discover its component directory, styles, tokens, and metadata automatically.</p></section><section class="guide-section"><h2>Verify discovery</h2><p>Run the type checker and inspect packages. A healthy application reports valid application types and lists @wrnexus/ui among its resolved packages.</p></section><section class="guide-section"><h2>Production check</h2><p>Build once before deployment. Confirm the report lists UI components, the selected active theme, and the application stylesheet without loading the complete theme matrix.</p></section>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>bun add @wrnexus/ui@0.8.7
-      <section class="guide-section"><h2>Quick start</h2><pre><code>bun add @wrnexus/ui@0.8.7
 bunx wrnexus typecheck .
 bunx wrnexus inspect packages .
-bunx wrnexus build .</code></pre></section>
+bunx wrnexus build .</code></pre><h3>What changes after this</h3><p>The UI package becomes discoverable by development, type-check, and production builds without manually copying component CSS.</p></section>
+      <section class="guide-section"><h2>Prerequisites</h2><p>Use Bun 1.3 or newer and a WRNexus application whose framework packages share the same version. Private-preview installs require npm credentials with access to the @wrnexus scope.</p></section><section class="guide-section"><h2>Install the UI package</h2><p>Add @wrnexus/ui to the application. The dev server and production builder discover its component directory, styles, tokens, and metadata automatically.</p></section><section class="guide-section"><h2>Verify discovery</h2><p>Run the type checker and inspect packages. A healthy application reports valid application types and lists @wrnexus/ui among its resolved packages.</p></section><section class="guide-section"><h2>Production check</h2><p>Build once before deployment. Confirm the report lists UI components, the selected active theme, and the application stylesheet without loading the complete theme matrix.</p></section>
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/resources.wrn

@@ -8,10 +8,14 @@ page ResourcesGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Resources</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Getting Started</span><h1>Resources</h1><p>Use the component API pages, blocks, and templates as production starting points.</p></header>
-      <section class="guide-section"><h2>Component contracts</h2><p>Each component page contains live variants, typed props, slots, outputs, copyable WRN source, behavior notes, and responsive guidance.</p></section><section class="guide-section"><h2>Blocks and templates</h2><p>Blocks demonstrate production composition patterns. Templates combine those patterns into public pages, authentication surfaces, and application dashboards.</p></section><section class="guide-section"><h2>Framework diagnostics</h2><p>Use inspect, explain, doctor, and typecheck when a component does not render or hydrate as expected. These commands expose resolved ownership rather than requiring guesswork.</p></section><section class="guide-section"><h2>Upgrade safely</h2><p>Preview framework migrations, commit the current application, apply the update, and review generated migration reports before deployment.</p></section>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>bunx wrnexus doctor .
-      <section class="guide-section"><h2>Quick start</h2><pre><code>bunx wrnexus doctor .
 bunx wrnexus inspect styles .
-bunx wrnexus update . --latest --dry-run</code></pre></section>
+bunx wrnexus update . --latest --dry-run</code></pre><h3>What changes after this</h3><p>You can move from component contract to composed block, diagnose ownership, and preview upgrades with supported tools.</p></section>
+      <section class="guide-section"><h2>Component contracts</h2><p>Each component page contains live variants, typed props, slots, outputs, copyable WRN source, behavior notes, and responsive guidance.</p></section><section class="guide-section"><h2>Blocks and templates</h2><p>Blocks demonstrate production composition patterns. Templates combine those patterns into public pages, authentication surfaces, and application dashboards.</p></section><section class="guide-section"><h2>Framework diagnostics</h2><p>Use inspect, explain, doctor, and typecheck when a component does not render or hydrate as expected. These commands expose resolved ownership rather than requiring guesswork.</p></section><section class="guide-section"><h2>Upgrade safely</h2><p>Preview framework migrations, commit the current application, apply the update, and review generated migration reports before deployment.</p></section>
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/sizing.wrn

@@ -8,9 +8,13 @@ page SizingGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Sizing</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Customization</span><h1>Sizing</h1><p>Compact through large scales adjust the complete component system consistently.</p></header>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>&lt;Button size="sm"&gt;Compact action&lt;/Button&gt;
+&lt;Input size="lg" label="Search" /&gt;</code></pre><h3>What changes after this</h3><p>Control size and application density remain consistent without shrinking accessible touch targets.</p></section>
       <section class="guide-section"><h2>Component size</h2><p>Use xs, sm, default, md, lg, or xl when a component needs an explicit scale. Related controls should use the same size within one task.</p></section><section class="guide-section"><h2>Interface density</h2><p>Compact, default, comfortable, and large adjust the system globally. Choose density from audience and task complexity rather than viewport alone.</p></section><section class="guide-section"><h2>Responsive composition</h2><p>Let containers, grids, columns, navigation, and sections adapt layout. Avoid shrinking touch targets to force desktop arrangements onto mobile.</p></section><section class="guide-section"><h2>Override deliberately</h2><p>Use tokens for application-wide spacing changes and component props for local intent. Measure dense tables and large marketing layouts separately.</p></section>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>&lt;Button size="sm"&gt;Compact action&lt;/Button&gt;
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
-&lt;Input size="lg" label="Search" /&gt;</code></pre></section>
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

app/pages/themes.wrn

@@ -8,12 +8,16 @@ page ThemesGuide {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>Themes</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">Customization</span><h1>Themes</h1><p>Theme presets control radius, surface treatment, borders, shadows, and motion.</p></header>
-      <section class="guide-section"><h2>Theme anatomy</h2><p>A theme combines mode, palette, accent, radius, elevation, borders, motion, and typography. Components consume semantic tokens rather than palette-specific values.</p></section><section class="guide-section"><h2>Select only what ships</h2><p>Production pages link the active palette/accent sheet. Keep alternative themes available for user selection without placing the complete matrix on every page.</p></section><section class="guide-section"><h2>Customize globally</h2><p>Override tokens at the application boundary for brand-wide changes. Keep component-local adjustments in the owning page or component.</p></section><section class="guide-section"><h2>Validate the system</h2><p>Use the design panel to compare presets, then verify the production build's theme link and CSS report.</p></section>
+      <section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>theme: <span>&#123;</span>
-      <section class="guide-section"><h2>Quick start</h2><pre><code>theme: <span>&#123;</span>
   default: "light",
   palette: "violet",
   accent: "violet",
-<span>&#125;</span></code></pre></section>
+<span>&#125;</span></code></pre><h3>What changes after this</h3><p>Only the selected theme is active while semantic tokens keep every component visually consistent.</p></section>
+      <section class="guide-section"><h2>Theme anatomy</h2><p>A theme combines mode, palette, accent, radius, elevation, borders, motion, and typography. Components consume semantic tokens rather than palette-specific values.</p></section><section class="guide-section"><h2>Select only what ships</h2><p>Production pages link the active palette/accent sheet. Keep alternative themes available for user selection without placing the complete matrix on every page.</p></section><section class="guide-section"><h2>Customize globally</h2><p>Override tokens at the application boundary for brand-wide changes. Keep component-local adjustments in the owning page or component.</p></section><section class="guide-section"><h2>Validate the system</h2><p>Use the design panel to compare presets, then verify the production build's theme link and CSS report.</p></section>
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

scripts/generate-showcase.mjs

@@ -2052,6 +2052,17 @@ page V06${identifier(title)}Guide {
 }
 
 const customizationGuides = new Set(["dark-mode", "themes", "colors", "fonts", "sizing"]);
+const guideOutcomes = {
+  installation: "The UI package becomes discoverable by development, type-check, and production builds without manually copying component CSS.",
+  "framework-guides": "The page depends on public component props, slots, and outputs, so framework upgrades do not depend on private markup.",
+  accessibility: "Keyboard, focus, naming, contrast, zoom, and reduced-motion behavior become explicit acceptance criteria.",
+  resources: "You can move from component contract to composed block, diagnose ownership, and preview upgrades with supported tools.",
+  "dark-mode": "The initial server document and hydrated client agree on light, dark, or system mode without a theme flash.",
+  themes: "Only the selected theme is active while semantic tokens keep every component visually consistent.",
+  colors: "Status and hierarchy use named semantic roles that remain understandable in both light and dark modes.",
+  fonts: "Typography loads only required families and weights while preserving a readable system fallback.",
+  sizing: "Control size and application density remain consistent without shrinking accessible touch targets.",
+};
 const guideDetails = {
   installation: {
     sections: [
@@ -2153,8 +2164,9 @@ for (const [slug, title, description, code] of docsSections) {
     <article class="page-docs guide-page">
       <nav class="docs-breadcrumbs" aria-label="Breadcrumb"><a href="/docs">Docs</a><span aria-hidden="true">/</span><span>${escapeText(title)}</span></nav>
       <header class="docs-intro"><span class="showcase-eyebrow">${section}</span><h1>${escapeText(title)}</h1><p>${escapeText(description)}</p></header>
+      ${details.code ? `<section class="guide-section guide-example"><h2>Configure and use it</h2><p>This is the smallest useful starting point. Copy it into the indicated application file or run it from the project root, then adjust the documented values for your product.</p><pre><code>${escapeCode(details.code)}</code></pre><h3>What changes after this</h3><p>${escapeText(guideOutcomes[slug] ?? "The application adopts the documented component-library contract and can verify it through the production toolchain.")}</p></section>` : ""}
       ${details.sections.map(([heading, copy]) => `<section class="guide-section"><h2>${escapeText(heading)}</h2><p>${escapeText(copy)}</p></section>`).join("")}
-      ${details.code ? `<section class="guide-section"><h2>Quick start</h2><pre><code>${escapeCode(details.code)}</code></pre></section>` : ""}
+      <section class="guide-section"><h2>Verify the result</h2><p>Type-check the application, inspect the resolved package and styles, and build the production artifact. Test the page at a narrow viewport, with keyboard navigation, and in both color modes before shipping.</p><pre><code>${escapeCode(`bunx wrnexus typecheck .\nbunx wrnexus inspect packages .\nbunx wrnexus inspect styles .\nbunx wrnexus build .`)}</code></pre><h3>Expected result</h3><p>The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.</p></section>
       <nav class="guide-next"><a href="/components/button">Explore components <span aria-hidden="true">→</span></a><a href="/block-library">Browse blocks <span aria-hidden="true">→</span></a></nav>
     </article>
   }

test/showcase.test.ts

@@ -349,6 +349,27 @@ test("generated playground boolean states avoid multiline-sensitive ternaries",
   }
 });
 
+test("getting started and customization guides include code, outcomes, and verification", () => {
+  for (const slug of [
+    "installation",
+    "framework-guides",
+    "accessibility",
+    "resources",
+    "dark-mode",
+    "themes",
+    "colors",
+    "fonts",
+    "sizing",
+  ]) {
+    const source = readFileSync(join(pagesDir, `${slug}.wrn`), "utf8");
+    expect(source).toContain("Configure and use it");
+    expect(source).toContain("What changes after this");
+    expect(source).toContain("Verify the result");
+    expect(source).toContain("Expected result");
+    expect(source).toContain("<pre><code>");
+  }
+});
+
 test("every generated showcase page compiles and is accepted by the route syntax parser", () => {
   const paths = [
     ...readdirSync(pagesDir)