@teseor/css 1.14.3 → 1.15.0

package/src/layout/content/content.docs.html

@@ -0,0 +1,38 @@
+---
+title: Content
+type: primitive
+id: content
+description: Content wrapper with consistent vertical spacing. Use inside container for padded, spaced content areas.
+api: ./content.api.json
+---
+
+<!-- @default -->
+<!-- Vertical flex layout with gap between children and block/inline padding. -->
+<div class="ui-content" style="0: b; 1: a; 2: c; 3: k; 4: g; 5: r; 6: o; 7: u; 8: n; 9: d; 10: :; 11:  ; 12: v; 13: a; 14: r; 15: (; 16: -; 17: -; 18: u; 19: i; 20: -; 21: c; 22: o; 23: l; 24: o; 25: r; 26: -; 27: b; 28: g; 29: -; 30: s; 31: u; 32: b; 33: t; 34: l; 35: e; 36: )">
+  <p>First section of content with consistent spacing.</p>
+  <p>Second section automatically spaced by the gap token.</p>
+  <p>Third section follows the same rhythm.</p>
+</div>
+
+<!-- @prose -->
+<!-- Narrower max-width for readable long-form text (640px / 80 units). -->
+<div class="ui-content ui-content--prose" style="0: b; 1: a; 2: c; 3: k; 4: g; 5: r; 6: o; 7: u; 8: n; 9: d; 10: :; 11:  ; 12: v; 13: a; 14: r; 15: (; 16: -; 17: -; 18: u; 19: i; 20: -; 21: c; 22: o; 23: l; 24: o; 25: r; 26: -; 27: b; 28: g; 29: -; 30: s; 31: u; 32: b; 33: t; 34: l; 35: e; 36: )">
+  <p>Prose content is constrained to a comfortable reading width. Long paragraphs stay readable without requiring the eye to travel too far across the screen.</p>
+  <p>This works well for articles, documentation, and form layouts.</p>
+</div>
+
+<!-- @flush -->
+<!-- No padding, only gap between children. Useful when the parent handles padding. -->
+<div class="ui-content ui-content--flush" style="0: b; 1: a; 2: c; 3: k; 4: g; 5: r; 6: o; 7: u; 8: n; 9: d; 10: :; 11:  ; 12: v; 13: a; 14: r; 15: (; 16: -; 17: -; 18: u; 19: i; 20: -; 21: c; 22: o; 23: l; 24: o; 25: r; 26: -; 27: b; 28: g; 29: -; 30: s; 31: u; 32: b; 33: t; 34: l; 35: e; 36: )">
+  <p>Flush content has no padding.</p>
+  <p>Gap between children is preserved.</p>
+</div>
+
+<!-- @with_container -->
+<!-- Content inside a centered container for a typical page layout. -->
+<div class="ui-container ui-container--center">
+  <div class="ui-content">
+    <h2 class="ui-heading ui-heading--3">Page Title</h2>
+    <p>Content with consistent spacing and max-width.</p>
+  </div>
+</div>

package/src/layout/content/content.visual.spec.ts

@@ -1,12 +1,16 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../test-utils';
+import {
+  saveForLostPixel,
+  setupVisualTestFromHtmlDocs,
+  validateGridRhythm,
+} from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'content.docs.json');
+const DOCS_PATH = resolve(__dirname, 'content.docs.html');
 
 test.describe('content visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'content');
     await saveForLostPixel(page, 'content');
     await expect(page.locator('body')).toHaveScreenshot('content.visual.png');

package/src/layout/footer/footer.docs.html

@@ -0,0 +1,73 @@
+---
+title: Footer
+type: primitive
+id: footer
+description: Page footer with start, center, and end sections. Supports sticky/fixed positioning and border/shadow variants.
+api: ./footer.api.json
+---
+
+<!-- @default -->
+<!-- Basic footer with three sections. -->
+<footer class="ui-footer ui-footer--bordered">
+  <div class="ui-footer__start">
+    <small>2026 Brand</small>
+  </div>
+  <div class="ui-footer__center">
+    <span>Footer links</span>
+  </div>
+  <div class="ui-footer__end">
+    <small>v1.0.0</small>
+  </div>
+</footer>
+
+<!-- @sticky -->
+<!-- Stays at the bottom of the viewport on scroll. -->
+<footer class="ui-footer ui-footer--sticky ui-footer--bordered">
+  <div class="ui-footer__start"><small>Brand</small></div>
+  <div class="ui-footer__center">Links</div>
+  <div class="ui-footer__end"><small>v1.0.0</small></div>
+</footer>
+
+<!-- @bordered -->
+<!-- Top border via inset box-shadow to preserve grid rhythm. -->
+<footer class="ui-footer ui-footer--bordered">
+  <div class="ui-footer__start">
+    <small>Bordered footer</small>
+  </div>
+  <div class="ui-footer__end">
+    <small>v1.0.0</small>
+  </div>
+</footer>
+
+<!-- @raised -->
+<!-- Subtle drop shadow above the footer. -->
+<footer class="ui-footer ui-footer--raised">
+  <div class="ui-footer__start">
+    <small>Raised footer</small>
+  </div>
+  <div class="ui-footer__end">
+    <small>v1.0.0</small>
+  </div>
+</footer>
+
+<!-- @fixed -->
+<!-- Fixed to viewport bottom, always visible. -->
+<footer class="ui-footer ui-footer--fixed ui-footer--bordered">
+  <div class="ui-footer__start"><small>Brand</small></div>
+  <div class="ui-footer__end"><small>v1.0.0</small></div>
+</footer>
+
+<!-- @full_layout -->
+<!-- Footer inside an app-shell with topbar and sidebar. -->
+<body class="ui-app-shell">
+  <header class="ui-topbar ui-topbar--bordered">
+    <div class="ui-topbar__start"><strong>App</strong></div>
+  </header>
+  <main class="ui-main ui-main--full">
+    <div class="ui-container">Content</div>
+    <footer class="ui-footer ui-footer--bordered">
+      <div class="ui-footer__start"><small>Brand</small></div>
+      <div class="ui-footer__end"><small>v1.0.0</small></div>
+    </footer>
+  </main>
+</body>

package/src/layout/footer/footer.visual.spec.ts

@@ -1,12 +1,16 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../test-utils';
+import {
+  saveForLostPixel,
+  setupVisualTestFromHtmlDocs,
+  validateGridRhythm,
+} from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'footer.docs.json');
+const DOCS_PATH = resolve(__dirname, 'footer.docs.html');
 
 test.describe('footer visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'footer');
     await saveForLostPixel(page, 'footer');
     await expect(page.locator('body')).toHaveScreenshot('footer.visual.png');

package/src/layout/grid/grid.docs.html

@@ -0,0 +1,87 @@
+---
+title: Grid
+type: primitive
+id: grid-primitive
+description: CSS Grid with column variants, subgrid support, and span utilities.
+api: grid.api.json
+---
+
+<!-- @columns -->
+<div class="ui-grid ui-grid--2">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">2</div>
+</div>
+<div class="ui-grid ui-grid--3">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">2</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">3</div>
+</div>
+<div class="ui-grid ui-grid--4">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">2</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">3</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">4</div>
+</div>
+<div class="ui-grid ui-grid--auto">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Auto</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Auto</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Auto</div>
+</div>
+
+<!-- @subgrid -->
+<!-- Children inherit parent grid tracks for cross-item alignment. -->
+<div class="ui-grid ui-grid--3">
+  <div class="ui-grid--subgrid" style="grid-column: span 3">
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Subgrid child 1</div>
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Subgrid child 2</div>
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Subgrid child 3</div>
+  </div>
+</div>
+<div class="ui-grid ui-grid--3" style="grid-template-rows: auto 1fr auto">
+  <div class="ui-grid--subgrid-rows" style="grid-row: span 3; border: 1px solid var(--ui-color-border); padding: var(--ui-space-2)">
+    <strong>Card A</strong>
+    <p>Short content.</p>
+    <span style="color: var(--ui-color-text-muted)">Footer</span>
+  </div>
+  <div class="ui-grid--subgrid-rows" style="grid-row: span 3; border: 1px solid var(--ui-color-border); padding: var(--ui-space-2)">
+    <strong>Card B</strong>
+    <p>Longer content that wraps to multiple lines to demonstrate row alignment.</p>
+    <span style="color: var(--ui-color-text-muted)">Footer</span>
+  </div>
+  <div class="ui-grid--subgrid-rows" style="grid-row: span 3; border: 1px solid var(--ui-color-border); padding: var(--ui-space-2)">
+    <strong>Card C</strong>
+    <p>Medium text.</p>
+    <span style="color: var(--ui-color-text-muted)">Footer</span>
+  </div>
+</div>
+<div class="ui-grid ui-grid--3" style="grid-template-rows: auto auto">
+  <div class="ui-grid--subgrid-both" style="grid-column: span 3; grid-row: span 2">
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">A1</div>
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">A2</div>
+    <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">A3</div>
+    <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">B1</div>
+    <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">B2</div>
+    <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">B3</div>
+  </div>
+</div>
+
+<!-- @column_span -->
+<!-- Span multiple columns with .ui-grid-col-span-{2,3,4,full} utilities. -->
+<div class="ui-grid ui-grid--4">
+  <div style="grid-column: span 2; background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Span 2</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">1</div>
+  <div style="grid-column: span 3; background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Span 3</div>
+  <div style="grid-column: 1 / -1; background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Span full</div>
+</div>
+
+<!-- @row_span -->
+<!-- Span multiple rows with .ui-grid-row-span-{2,3,full} utilities. -->
+<div class="ui-grid ui-grid--3">
+  <div style="grid-row: span 2; background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Row span 2</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">1</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">2</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">3</div>
+  <div style="background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">4</div>
+</div>

package/src/layout/grid/grid.visual.spec.ts

@@ -1,12 +1,12 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs } from '../../../test-utils';
+import { saveForLostPixel, setupVisualTestFromHtmlDocs } from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'grid.docs.json');
+const DOCS_PATH = resolve(__dirname, 'grid.docs.html');
 
 test.describe('grid visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await saveForLostPixel(page, 'grid');
     await expect(page.locator('body')).toHaveScreenshot('grid.visual.png');
   });

package/src/layout/main/main.docs.html

@@ -0,0 +1,31 @@
+---
+title: Main
+type: primitive
+id: main
+description: Main content area that accounts for sidebar and topbar offsets in app layouts.
+api: main.api.json
+---
+
+<!-- @default -->
+<!-- Offsets content for a start-side sidebar and optional topbar. -->
+<div style="position: relative; height: var(--ui-row-4)">
+  <main class="ui-main" style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">
+    <p>Main content area</p>
+  </main>
+</div>
+
+<!-- @sidebar_end -->
+<!-- Offsets content for an end-side sidebar instead of start. -->
+<div style="position: relative; height: var(--ui-row-4)">
+  <main class="ui-main ui-main--sidebar-end" style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">
+    <p>Content with end sidebar</p>
+  </main>
+</div>
+
+<!-- @full_width -->
+<!-- No sidebar offset. Use when there is no sidebar. -->
+<div style="position: relative; height: var(--ui-row-4)">
+  <main class="ui-main ui-main--full" style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">
+    <p>Full width content</p>
+  </main>
+</div>

package/src/layout/nav-rail/nav-rail.docs.html

@@ -0,0 +1,42 @@
+---
+title: Nav Rail
+type: primitive
+id: nav-rail
+description: Narrow fixed vertical navigation rail for icon-based navigation with bottom actions.
+api: ./nav-rail.api.json
+---
+
+<!-- @default -->
+<!-- Fixed narrow rail with icon items and bottom actions. -->
+<nav class="ui-nav-rail" style="0: p; 1: o; 2: s; 3: i; 4: t; 5: i; 6: o; 7: n; 8: :; 9:  ; 10: r; 11: e; 12: l; 13: a; 14: t; 15: i; 16: v; 17: e; 18: ;; 19:  ; 20: b; 21: l; 22: o; 23: c; 24: k; 25: -; 26: s; 27: i; 28: z; 29: e; 30: :; 31:  ; 32: 3; 33: 2; 34: 0; 35: p; 36: x">
+  <div class="ui-nav-rail__items">
+    <button class="ui-button ui-button--ghost ui-button--icon">H</button>
+    <button class="ui-button ui-button--ghost ui-button--icon">S</button>
+    <button class="ui-button ui-button--ghost ui-button--icon">M</button>
+  </div>
+  <div class="ui-nav-rail__actions">
+    <button class="ui-button ui-button--ghost ui-button--icon">G</button>
+  </div>
+</nav>
+
+<!-- @end_position -->
+<!-- Rail on the end (right in LTR) side. -->
+<nav class="ui-nav-rail ui-nav-rail--end">
+  <div class="ui-nav-rail__items">
+    <!-- icon buttons -->
+  </div>
+  <div class="ui-nav-rail__actions">
+    <!-- settings, profile -->
+  </div>
+</nav>
+
+<!-- @with_topbar -->
+<!-- Nav rail respects --topbar-height, offsetting below the topbar. -->
+<body class="ui-app-shell" style="--topbar-height: var(--ui-row-3)">
+  <header class="ui-topbar ui-topbar--fixed ui-topbar--bordered">
+    <div class="ui-topbar__start"><strong>App</strong></div>
+  </header>
+  <nav class="ui-nav-rail">
+    <div class="ui-nav-rail__items"><!-- icons --></div>
+  </nav>
+</body>

package/src/layout/nav-rail/nav-rail.visual.spec.ts

@@ -1,12 +1,16 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../test-utils';
+import {
+  saveForLostPixel,
+  setupVisualTestFromHtmlDocs,
+  validateGridRhythm,
+} from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'nav-rail.docs.json');
+const DOCS_PATH = resolve(__dirname, 'nav-rail.docs.html');
 
 test.describe('nav-rail visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'nav-rail');
     await saveForLostPixel(page, 'nav-rail');
     await expect(page.locator('body')).toHaveScreenshot('nav-rail.visual.png');

package/src/layout/page-header/page-header.docs.html

@@ -0,0 +1,52 @@
+---
+title: Page Header
+type: primitive
+id: page-header
+description: Content area header with title, description, actions, and optional breadcrumb.
+api: ./page-header.api.json
+---
+
+<!-- @default -->
+<!-- Title with actions on the end side. -->
+<header class="ui-page-header ui-page-header--bordered">
+  <div class="ui-page-header__title">
+    <h1 class="ui-heading ui-heading--xl">Users</h1>
+    <p>Manage user accounts and permissions.</p>
+  </div>
+  <div class="ui-page-header__actions">
+    <button class="ui-button ui-button--primary">Add user</button>
+  </div>
+</header>
+
+<!-- @with_breadcrumb -->
+<!-- Breadcrumb spans the full width above the title row. -->
+<header class="ui-page-header ui-page-header--bordered">
+  <nav class="ui-page-header__breadcrumb">
+    <span>Home / Settings / Users</span>
+  </nav>
+  <div class="ui-page-header__title">
+    <h1 class="ui-heading ui-heading--xl">Users</h1>
+  </div>
+  <div class="ui-page-header__actions">
+    <button class="ui-button">Export</button>
+  </div>
+</header>
+
+<!-- @bordered -->
+<!-- Bottom border via inset box-shadow. -->
+<header class="ui-page-header ui-page-header--bordered">
+  <div class="ui-page-header__title">
+    <h1 class="ui-heading ui-heading--xl">Dashboard</h1>
+  </div>
+</header>
+
+<!-- @sticky -->
+<!-- Sticks to the top of the scroll container. -->
+<header class="ui-page-header ui-page-header--sticky ui-page-header--bordered">
+  <div class="ui-page-header__title">
+    <h1 class="ui-heading ui-heading--xl">Sticky Header</h1>
+  </div>
+  <div class="ui-page-header__actions">
+    <button class="ui-button">Save</button>
+  </div>
+</header>

package/src/layout/page-header/page-header.visual.spec.ts

@@ -1,12 +1,16 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../test-utils';
+import {
+  saveForLostPixel,
+  setupVisualTestFromHtmlDocs,
+  validateGridRhythm,
+} from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'page-header.docs.json');
+const DOCS_PATH = resolve(__dirname, 'page-header.docs.html');
 
 test.describe('page-header visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'page-header');
     await saveForLostPixel(page, 'page-header');
     await expect(page.locator('body')).toHaveScreenshot('page-header.visual.png');

package/src/layout/row/row.docs.html

@@ -0,0 +1,47 @@
+---
+title: Row
+type: primitive
+id: row
+description: Horizontal layout with wrapping.
+api: row.api.json
+---
+
+<!-- @basic -->
+<div class="ui-row ui-row--md">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Tag 1</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Tag 2</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Tag 3</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Tag 4</div>
+</div>
+
+<!-- @sizes -->
+<div class="ui-row ui-row--xs">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xs</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xs</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xs</div>
+</div>
+<div class="ui-row ui-row--lg">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">lg</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">lg</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">lg</div>
+</div>
+<div class="ui-row ui-row--sm">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">sm</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">sm</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">sm</div>
+</div>
+
+<!-- @alignment -->
+<div class="ui-row ui-row--start" style="background: var(--ui-color-bg-muted)">
+  <div style="background: var(--ui-color-bg); padding: var(--ui-space-2)">Start</div>
+</div>
+<div class="ui-row ui-row--center" style="background: var(--ui-color-bg-muted)">
+  <div style="background: var(--ui-color-bg); padding: var(--ui-space-2)">Center</div>
+</div>
+<div class="ui-row ui-row--end" style="background: var(--ui-color-bg-muted)">
+  <div style="background: var(--ui-color-bg); padding: var(--ui-space-2)">End</div>
+</div>
+<div class="ui-row ui-row--between" style="background: var(--ui-color-bg-muted)">
+  <div style="background: var(--ui-color-bg); padding: var(--ui-space-2)">Between A</div>
+  <div style="background: var(--ui-color-bg); padding: var(--ui-space-2)">Between B</div>
+</div>

package/src/layout/row/row.visual.spec.ts

@@ -1,12 +1,12 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs } from '../../../test-utils';
+import { saveForLostPixel, setupVisualTestFromHtmlDocs } from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'row.docs.json');
+const DOCS_PATH = resolve(__dirname, 'row.docs.html');
 
 test.describe('row visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     // skip validateGridRhythm: row is a layout primitive that
     // controls gap/alignment, not child height
     await saveForLostPixel(page, 'row');

package/src/layout/sidebar/sidebar.docs.html

@@ -0,0 +1,30 @@
+---
+title: Sidebar
+type: primitive
+id: sidebar
+description: Fixed-position sidebar for app layouts with adjustable widths and positioning.
+api: ./sidebar.api.json
+---
+
+<!-- @basic -->
+<!-- Default sidebar positioned on the start side. Use inside an app-shell layout. -->
+<aside class="ui-sidebar">
+  <p>Sidebar content</p>
+</aside>
+
+<!-- @widths | column -->
+<aside class="ui-sidebar ui-sidebar--sm" style="position: relative; height: auto;">
+  <p>Small (192px)</p>
+</aside>
+<aside class="ui-sidebar ui-sidebar--md" style="position: relative; height: auto;">
+  <p>Medium (240px, default)</p>
+</aside>
+<aside class="ui-sidebar ui-sidebar--lg" style="position: relative; height: auto;">
+  <p>Large (320px)</p>
+</aside>
+
+<!-- @end_position -->
+<!-- Position sidebar on the end side with --end modifier. -->
+<aside class="ui-sidebar ui-sidebar--end">
+  <p>End sidebar</p>
+</aside>

package/src/layout/sidebar/sidebar.visual.spec.ts

@@ -1,12 +1,16 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../test-utils';
+import {
+  saveForLostPixel,
+  setupVisualTestFromHtmlDocs,
+  validateGridRhythm,
+} from '../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'sidebar.docs.json');
+const DOCS_PATH = resolve(__dirname, 'sidebar.docs.html');
 
 test.describe('sidebar visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'sidebar');
     await saveForLostPixel(page, 'sidebar');
     await expect(page.locator('body')).toHaveScreenshot('sidebar.visual.png');