From bec9ef2889cfde7ec4d1cdd1aa01e46a5dd32e41 Mon Sep 17 00:00:00 2001 From: Ajay Ghanwat Date: Mon, 10 Aug 2026 14:18:42 +0530 Subject: [PATCH] docs: teach component setup with verified examples --- app/pages/accessibility.wrn | 8 ++++++-- app/pages/colors.wrn | 8 ++++++-- app/pages/dark-mode.wrn | 10 +++++++--- app/pages/fonts.wrn | 10 +++++++--- app/pages/framework-guides.wrn | 8 ++++++-- app/pages/installation.wrn | 10 +++++++--- app/pages/resources.wrn | 10 +++++++--- app/pages/sizing.wrn | 8 ++++++-- app/pages/themes.wrn | 10 +++++++--- scripts/generate-showcase.mjs | 14 +++++++++++++- test/showcase.test.ts | 21 +++++++++++++++++++++ 11 files changed, 93 insertions(+), 24 deletions(-) diff --git a/app/pages/accessibility.wrn b/app/pages/accessibility.wrn index 7719477..445fb59 100644 --- a/app/pages/accessibility.wrn +++ b/app/pages/accessibility.wrn @@ -8,9 +8,13 @@ page AccessibilityGuide {
Getting Started

Accessibility

Keyboard interaction, visible focus states, labels, and reduced-motion support ship by default.

+

Configure and use it

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.

bunx wrnexus test accessibility .
+bunx wrnexus security headers .

What changes after this

Keyboard, focus, naming, contrast, zoom, and reduced-motion behavior become explicit acceptance criteria.

Keyboard first

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.

Names and descriptions

Provide visible labels or accessible names for icon-only actions. Associate help and validation messages with their fields rather than relying on color alone.

Focus and overlays

Keep visible focus rings. Modal, drawer, dropdown, and popover components manage focus and dismissal; test Escape, Tab, Shift+Tab, and focus restoration.

Motion and contrast

Theme tokens preserve semantic contrast, while components honor reduced motion. Verify custom colors in light and dark modes at 200% zoom.

-

Quick start

bunx wrnexus test accessibility .
-bunx wrnexus security headers .
+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/colors.wrn b/app/pages/colors.wrn index 046a464..d39923e 100644 --- a/app/pages/colors.wrn +++ b/app/pages/colors.wrn @@ -8,9 +8,13 @@ page ColorsGuide {
Customization

Colors

Semantic primary, secondary, success, warning, danger, and info tokens remain available in every palette.

+

Configure and use it

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.

<Button color="primary">Save</Button>
+<Alert color="danger">Unable to save</Alert>

What changes after this

Status and hierarchy use named semantic roles that remain understandable in both light and dark modes.

Semantic roles

Primary and secondary communicate hierarchy; success, warning, danger, and info communicate state. Use roles consistently instead of choosing colors by appearance.

Component colors

Every maintained component accepts the shared color contract. Prefer the color prop for supported variants and tokens for application-owned surfaces.

Accessible combinations

Check text, icons, borders, hover, focus, selected, and disabled states. Never make color the only carrier of meaning.

Brand overrides

Define brand values once through theme tokens. Derived surfaces and on-colors keep contrast coherent across light and dark modes.

-

Quick start

<Button color="primary">Save</Button>
-<Alert color="danger">Unable to save</Alert>
+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/dark-mode.wrn b/app/pages/dark-mode.wrn index 67103dc..6350a41 100644 --- a/app/pages/dark-mode.wrn +++ b/app/pages/dark-mode.wrn @@ -8,11 +8,15 @@ page DarkModeGuide {
Customization

Dark mode

Choose light, dark, or system mode. The selection persists and updates every preview.

-

Choose a default

Set light, dark, or system in wrnexus.config.ts. System mode follows the operating-system preference until the user selects an explicit value.

Persist preference

Use PreferenceSwitcher or your own control to update the document theme. The selected value persists and is applied before interactive components hydrate.

Author with tokens

Use semantic --wire-* variables instead of hard-coded light colors. Tokens switch surfaces, text, borders, focus, and status colors together.

Test both modes

Check content, overlays, charts, disabled controls, focus rings, and browser autofill in both modes. Do not treat dark mode as a simple color inversion.

-

Quick start

theme: {
+      
Configure and use it
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.
theme: {
   default: "system",
   palette: "violet",
-}

+}

What changes after this

The initial server document and hydrated client agree on light, dark, or system mode without a theme flash.

+

Choose a default

Set light, dark, or system in wrnexus.config.ts. System mode follows the operating-system preference until the user selects an explicit value.

Persist preference

Use PreferenceSwitcher or your own control to update the document theme. The selected value persists and is applied before interactive components hydrate.

Author with tokens

Use semantic --wire-* variables instead of hard-coded light colors. Tokens switch surfaces, text, borders, focus, and status colors together.

Test both modes

Check content, overlays, charts, disabled controls, focus rings, and browser autofill in both modes. Do not treat dark mode as a simple color inversion.

+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/fonts.wrn b/app/pages/fonts.wrn index 5dc5b62..be75976 100644 --- a/app/pages/fonts.wrn +++ b/app/pages/fonts.wrn @@ -8,11 +8,15 @@ page FontsGuide {
Customization

Fonts

Select a font family globally while components continue to inherit typography correctly.

-

Configure families

Declare the application sans family and optional hosted families in wrnexus.config.ts. Components inherit typography without per-component imports.

Control loading

Request only used weights and styles. Keep a system fallback so content remains readable before hosted fonts finish loading.

Preserve hierarchy

Use semantic heading, body, label, caption, and code roles. Avoid arbitrary sizes that break density and responsive rhythm.

Test real content

Check long headings, translated labels, numeric tables, code, and form errors. Font choices must remain legible at zoom and on narrow screens.

-

Quick start

fonts: {
+      
Configure and use it
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.
fonts: {
   sans: '"Plus Jakarta Sans", system-ui, sans-serif',
   google: [{ family: "Plus Jakarta Sans", weights: [400, 500, 600, 700] }],
-}

+}

What changes after this

Typography loads only required families and weights while preserving a readable system fallback.

+

Configure families

Declare the application sans family and optional hosted families in wrnexus.config.ts. Components inherit typography without per-component imports.

Control loading

Request only used weights and styles. Keep a system fallback so content remains readable before hosted fonts finish loading.

Preserve hierarchy

Use semantic heading, body, label, caption, and code roles. Avoid arbitrary sizes that break density and responsive rhythm.

Test real content

Check long headings, translated labels, numeric tables, code, and form errors. Font choices must remain legible at zoom and on narrow screens.

+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/framework-guides.wrn b/app/pages/framework-guides.wrn index a1ab92a..939c0a4 100644 --- a/app/pages/framework-guides.wrn +++ b/app/pages/framework-guides.wrn @@ -8,9 +8,13 @@ page FrameworkGuidesGuide {
Getting Started

Framework guides

WRNexus components use native HTML semantics and framework component mounts.

+

Configure and use it

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.

bunx wrnexus inspect component Navbar .
+bunx wrnexus typecheck .

What changes after this

The page depends on public component props, slots, and outputs, so framework upgrades do not depend on private markup.

Mount components

Use the component mount name directly in .wrn views. Props are typed, slots remain server-rendered, and declared outputs reach parent bindings.

Own page composition

Keep application structure in pages and layouts. Use library components for reusable behavior, then add application-specific styles in the owning .wrn file.

Prefer semantic contracts

Choose props, slots, and outputs over selectors that depend on a component's internal markup. This keeps applications compatible with framework upgrades.

Inspect before integrating

Use the CLI component inspector for the exact prop, slot, and output contract, then type-check the finished page.

-

Quick start

bunx wrnexus inspect component Navbar .
-bunx wrnexus typecheck .
+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/installation.wrn b/app/pages/installation.wrn index e670c29..9d5ef43 100644 --- a/app/pages/installation.wrn +++ b/app/pages/installation.wrn @@ -8,11 +8,15 @@ page InstallationGuide {
Getting Started

Installation

Install the package and import the shared stylesheet once in your application.

-

Prerequisites

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.

Install the UI package

Add @wrnexus/ui to the application. The dev server and production builder discover its component directory, styles, tokens, and metadata automatically.

Verify discovery

Run the type checker and inspect packages. A healthy application reports valid application types and lists @wrnexus/ui among its resolved packages.

Production check

Build once before deployment. Confirm the report lists UI components, the selected active theme, and the application stylesheet without loading the complete theme matrix.

-

Quick start

bun add @wrnexus/ui@0.8.7
+      
Configure and use it
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.
bun add @wrnexus/ui@0.8.7
 bunx wrnexus typecheck .
 bunx wrnexus inspect packages .
-bunx wrnexus build .

+bunx wrnexus build .

What changes after this

The UI package becomes discoverable by development, type-check, and production builds without manually copying component CSS.

+

Prerequisites

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.

Install the UI package

Add @wrnexus/ui to the application. The dev server and production builder discover its component directory, styles, tokens, and metadata automatically.

Verify discovery

Run the type checker and inspect packages. A healthy application reports valid application types and lists @wrnexus/ui among its resolved packages.

Production check

Build once before deployment. Confirm the report lists UI components, the selected active theme, and the application stylesheet without loading the complete theme matrix.

+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/resources.wrn b/app/pages/resources.wrn index 018b683..af337e9 100644 --- a/app/pages/resources.wrn +++ b/app/pages/resources.wrn @@ -8,10 +8,14 @@ page ResourcesGuide {
Getting Started

Resources

Use the component API pages, blocks, and templates as production starting points.

-

Component contracts

Each component page contains live variants, typed props, slots, outputs, copyable WRN source, behavior notes, and responsive guidance.

Blocks and templates

Blocks demonstrate production composition patterns. Templates combine those patterns into public pages, authentication surfaces, and application dashboards.

Framework diagnostics

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.

Upgrade safely

Preview framework migrations, commit the current application, apply the update, and review generated migration reports before deployment.

-

Quick start

bunx wrnexus doctor .
+      
Configure and use it
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.
bunx wrnexus doctor .
 bunx wrnexus inspect styles .
-bunx wrnexus update . --latest --dry-run

+bunx wrnexus update . --latest --dry-run

What changes after this

You can move from component contract to composed block, diagnose ownership, and preview upgrades with supported tools.

+

Component contracts

Each component page contains live variants, typed props, slots, outputs, copyable WRN source, behavior notes, and responsive guidance.

Blocks and templates

Blocks demonstrate production composition patterns. Templates combine those patterns into public pages, authentication surfaces, and application dashboards.

Framework diagnostics

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.

Upgrade safely

Preview framework migrations, commit the current application, apply the update, and review generated migration reports before deployment.

+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/sizing.wrn b/app/pages/sizing.wrn index ebc174d..575ae9b 100644 --- a/app/pages/sizing.wrn +++ b/app/pages/sizing.wrn @@ -8,9 +8,13 @@ page SizingGuide {
Customization

Sizing

Compact through large scales adjust the complete component system consistently.

+

Configure and use it

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.

<Button size="sm">Compact action</Button>
+<Input size="lg" label="Search" />

What changes after this

Control size and application density remain consistent without shrinking accessible touch targets.

Component size

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.

Interface density

Compact, default, comfortable, and large adjust the system globally. Choose density from audience and task complexity rather than viewport alone.

Responsive composition

Let containers, grids, columns, navigation, and sections adapt layout. Avoid shrinking touch targets to force desktop arrangements onto mobile.

Override deliberately

Use tokens for application-wide spacing changes and component props for local intent. Measure dense tables and large marketing layouts separately.

-

Quick start

<Button size="sm">Compact action</Button>
-<Input size="lg" label="Search" />
+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/app/pages/themes.wrn b/app/pages/themes.wrn index bf4ee93..c9b2d7b 100644 --- a/app/pages/themes.wrn +++ b/app/pages/themes.wrn @@ -8,12 +8,16 @@ page ThemesGuide {
Customization

Themes

Theme presets control radius, surface treatment, borders, shadows, and motion.

-

Theme anatomy

A theme combines mode, palette, accent, radius, elevation, borders, motion, and typography. Components consume semantic tokens rather than palette-specific values.

Select only what ships

Production pages link the active palette/accent sheet. Keep alternative themes available for user selection without placing the complete matrix on every page.

Customize globally

Override tokens at the application boundary for brand-wide changes. Keep component-local adjustments in the owning page or component.

Validate the system

Use the design panel to compare presets, then verify the production build's theme link and CSS report.

-

Quick start

theme: {
+      
Configure and use it
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.
theme: {
   default: "light",
   palette: "violet",
   accent: "violet",
-}

+}

What changes after this

Only the selected theme is active while semantic tokens keep every component visually consistent.

+

Theme anatomy

A theme combines mode, palette, accent, radius, elevation, borders, motion, and typography. Components consume semantic tokens rather than palette-specific values.

Select only what ships

Production pages link the active palette/accent sheet. Keep alternative themes available for user selection without placing the complete matrix on every page.

Customize globally

Override tokens at the application boundary for brand-wide changes. Keep component-local adjustments in the owning page or component.

Validate the system

Use the design panel to compare presets, then verify the production build's theme link and CSS report.

+

Verify the result

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.

bunx wrnexus typecheck .
+bunx wrnexus inspect packages .
+bunx wrnexus inspect styles .
+bunx wrnexus build .

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/scripts/generate-showcase.mjs b/scripts/generate-showcase.mjs index 88c54b5..e3bb634 100644 --- a/scripts/generate-showcase.mjs +++ b/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) {
${section}

${escapeText(title)}

${escapeText(description)}

+ ${details.code ? `

Configure and use it

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.

${escapeCode(details.code)}

What changes after this

${escapeText(guideOutcomes[slug] ?? "The application adopts the documented component-library contract and can verify it through the production toolchain.")}

` : ""} ${details.sections.map(([heading, copy]) => `

${escapeText(heading)}

${escapeText(copy)}

`).join("")} - ${details.code ? `

Quick start

${escapeCode(details.code)}
` : ""} +

Verify the result

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.

${escapeCode(`bunx wrnexus typecheck .\nbunx wrnexus inspect packages .\nbunx wrnexus inspect styles .\nbunx wrnexus build .`)}

Expected result

The commands exit successfully, the build reports the installed UI components and active theme, and the rendered page remains usable before and after hydration.

} diff --git a/test/showcase.test.ts b/test/showcase.test.ts index 8c01520..af1358e 100644 --- a/test/showcase.test.ts +++ b/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("
");
+  }
+});
+
 test("every generated showcase page compiles and is accepted by the route syntax parser", () => {
   const paths = [
     ...readdirSync(pagesDir)