@teseor/css 1.14.2 → 1.15.0

package/src/config/tokens/colors/colors.docs.html

@@ -0,0 +1,75 @@
+---
+title: Colors
+type: token
+id: colors
+description: HSL-based color system with primitive and semantic tokens. Semantic tokens adapt to light/dark themes.
+skipValidation: true
+---
+
+<!-- @text_colors | column -->
+<!-- Use for typography and icons. -->
+<p style="color: var(--ui-color-text)">--ui-color-text: Default text</p>
+<p style="color: var(--ui-color-text-muted)">--ui-color-text-muted: Secondary text, captions</p>
+<p class="ui-p-1" style="color: var(--ui-color-text-inverse); background: var(--ui-color-neutral-900); border-radius: var(--ui-radius-sm)">--ui-color-text-inverse: Text on dark backgrounds</p>
+
+<!-- @background_colors | column -->
+<!-- Use for surfaces, cards, and containers. -->
+<div class="ui-p-2" style="background: var(--ui-color-bg); border: 1px solid var(--ui-color-border); border-radius: var(--ui-radius-md)">--ui-color-bg: Base background</div>
+<div class="ui-p-2" style="background: var(--ui-color-bg-subtle); border-radius: var(--ui-radius-md)">--ui-color-bg-subtle: Subtle emphasis</div>
+<div class="ui-p-2" style="background: var(--ui-color-bg-muted); border-radius: var(--ui-radius-md)">--ui-color-bg-muted: Stronger emphasis, code blocks</div>
+
+<!-- @border_colors | column -->
+<!-- Use for dividers, inputs, and card borders. -->
+<div class="ui-p-2" style="border: 2px solid var(--ui-color-border); border-radius: var(--ui-radius-md)">--ui-color-border: Default borders</div>
+<div class="ui-p-2" style="border: 2px solid var(--ui-color-border-strong); border-radius: var(--ui-radius-md)">--ui-color-border-strong: Emphasized borders</div>
+
+<!-- @interactive_colors | column -->
+<!-- Use for links, buttons, and interactive elements. -->
+<p style="color: var(--ui-color-interactive)">--ui-color-interactive: Links, primary actions</p>
+<p style="color: var(--ui-color-interactive-hover)">--ui-color-interactive-hover: Hover state</p>
+<div class="ui-p-1" style="display: inline-block; outline: 3px solid var(--ui-color-focus); outline-offset: 2px; border-radius: var(--ui-radius-sm)">--ui-color-focus: Focus rings</div>
+
+<!-- @status_colors -->
+<!-- Use for feedback, alerts, and validation. -->
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-success); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-success</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-warning); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-warning</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-danger); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-danger</span>
+</div>
+
+<!-- @primary_scale -->
+<!-- Brand color with light and dark variants. -->
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-primary-light); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-primary-light</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-primary); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-primary</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-primary-dark); border-radius: var(--ui-radius-sm)"></div>
+  <span>--ui-color-primary-dark</span>
+</div>
+
+<!-- @neutral_scale -->
+<!-- Gray scale for text, backgrounds, and borders. Derived from primary hue for subtle warmth. -->
+<div class="ui-row ui-row--sm" style="flex-wrap: wrap">
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-50); border: 1px solid var(--ui-color-border); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-100); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-200); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-300); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-400); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-500); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-600); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-700); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-800); border-radius: var(--ui-radius-sm)"></div>
+  <div style="width: var(--ui-space-4); height: var(--ui-row-2); background: var(--ui-color-neutral-900); border-radius: var(--ui-radius-sm)"></div>
+</div>

package/src/config/tokens/design-tokens.docs.html

@@ -0,0 +1,116 @@
+---
+title: Design Tokens
+type: token
+id: design-tokens
+description: Borders, radius, shadows, motion, z-index, and semantic tokens that form the visual foundation
+skipValidation: true
+---
+
+<!-- @borders | row -->
+<!-- Border width tokens derived from the 8px unit. -->
+<div style="width: var(--ui-space-8); height: var(--ui-row-2); border: var(--ui-border-width-sm) solid var(--ui-color-border-strong)"></div>
+<div style="width: var(--ui-space-8); height: var(--ui-row-2); border: var(--ui-border-width-md) solid var(--ui-color-border-strong)"></div>
+<div style="width: var(--ui-space-8); height: var(--ui-row-2); border: var(--ui-border-width-lg) solid var(--ui-color-border-strong)"></div>
+
+<!-- @radius | row -->
+<!-- Border radius tokens derived from the 8px unit. -->
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-row-3); height: var(--ui-row-3); background: var(--ui-color-primary); border-radius: var(--ui-radius-sm)"></div>
+  <small>sm (4px)</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-row-3); height: var(--ui-row-3); background: var(--ui-color-primary); border-radius: var(--ui-radius-md)"></div>
+  <small>md (8px)</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-row-3); height: var(--ui-row-3); background: var(--ui-color-primary); border-radius: var(--ui-radius-lg)"></div>
+  <small>lg (16px)</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-row-3); height: var(--ui-row-3); background: var(--ui-color-primary); border-radius: var(--ui-radius-full)"></div>
+  <small>full</small>
+</div>
+
+<!-- @shadows | row -->
+<!-- Elevation shadows using the primary hue for tinted depth. -->
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-8); height: var(--ui-row-3); background: var(--ui-color-bg); border-radius: var(--ui-radius-md); box-shadow: var(--ui-shadow-sm)"></div>
+  <small>sm</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-8); height: var(--ui-row-3); background: var(--ui-color-bg); border-radius: var(--ui-radius-md); box-shadow: var(--ui-shadow-md)"></div>
+  <small>md</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-8); height: var(--ui-row-3); background: var(--ui-color-bg); border-radius: var(--ui-radius-md); box-shadow: var(--ui-shadow-lg)"></div>
+  <small>lg</small>
+</div>
+
+<!-- @motion -->
+<!-- Duration and easing tokens. All durations drop to 0ms when prefers-reduced-motion is active. -->
+:root {
+  --ui-duration-instant: 50ms;
+  --ui-duration-fast: 100ms;
+  --ui-duration-base: 150ms;
+  --ui-duration-normal: 200ms;
+  --ui-duration-slow: 250ms;
+  --ui-duration-slower: 400ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --ui-duration-instant: 0ms;
+    --ui-duration-fast: 0ms;
+    /* ...all set to 0ms */
+  }
+}
+:root {
+  --ui-ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ui-ease-in:      cubic-bezier(0.4, 0, 1, 1);
+  --ui-ease-out:     cubic-bezier(0, 0, 0.2, 1);
+  --ui-ease-in-out:  cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+<!-- @z_index -->
+<!-- Layering scale with gaps to allow insertion without renumbering. -->
+:root {
+  --ui-z-base: 0;
+  --ui-z-sticky: 100;
+  --ui-z-dropdown: 200;
+  --ui-z-overlay: 300;
+  --ui-z-modal: 400;
+  --ui-z-popover: 500;
+  --ui-z-tooltip: 600;
+  --ui-z-toast: 700;
+  --ui-z-drawer: 800;
+  --ui-z-debug: 9999;
+}
+
+<!-- @semantic_colors -->
+<!-- Context-aware color tokens that resolve automatically in light and dark mode via light-dark(). -->
+:root {
+  color-scheme: light dark;
+  --ui-color-text: light-dark(var(--ui-color-neutral-900), var(--ui-color-neutral-100));
+  --ui-color-text-muted: light-dark(var(--ui-color-neutral-500), var(--ui-color-neutral-400));
+  --ui-color-bg: light-dark(var(--ui-color-neutral-50), var(--ui-color-neutral-900));
+  --ui-color-bg-subtle: light-dark(var(--ui-color-neutral-100), var(--ui-color-neutral-800));
+}
+:root {
+  --ui-color-border: light-dark(var(--ui-color-neutral-200), var(--ui-color-neutral-700));
+  --ui-color-border-strong: light-dark(var(--ui-color-neutral-300), var(--ui-color-neutral-600));
+  --ui-color-interactive: var(--ui-color-primary);
+  --ui-color-interactive-hover: var(--ui-color-primary-dark);
+  --ui-color-focus: var(--ui-color-primary-light);
+}
+
+<!-- @semantic_spacing -->
+<!-- Named spacing aliases that map to the numeric spacing scale for consistent layout patterns. -->
+:root {
+  --ui-spacing-xs: var(--ui-space-1);     /* 8px */
+  --ui-spacing-sm: var(--ui-space-2);     /* 16px */
+  --ui-spacing-md: var(--ui-space-4);     /* 32px */
+  --ui-spacing-lg: var(--ui-space-6);     /* 48px */
+  --ui-spacing-xl: var(--ui-space-8);     /* 64px */
+  --ui-spacing-gutter: var(--ui-space-4); /* 32px */
+  --ui-spacing-section: var(--ui-space-8);/* 64px */
+}

package/src/config/tokens/grid/grid.docs.html

@@ -0,0 +1,12 @@
+---
+title: Grid System
+type: token
+id: grid
+description: All spacing and heights align to the 8px grid.
+skipValidation: true
+---
+
+<!-- @default | column -->
+<div style="background: var(--ui-color-primary); color: var(--ui-color-text-inverse); height: var(--ui-row-1); display: flex; align-items: center; padding: 0 var(--ui-space-2)">row-1 (16px)</div>
+<div style="background: var(--ui-color-primary); color: var(--ui-color-text-inverse); height: var(--ui-row-2); display: flex; align-items: center; padding: 0 var(--ui-space-2)">row-2 (32px)</div>
+<div style="background: var(--ui-color-primary); color: var(--ui-color-text-inverse); height: var(--ui-row-3); display: flex; align-items: center; padding: 0 var(--ui-space-2)">row-3 (48px)</div>

package/src/config/tokens/spacing/spacing.docs.html

@@ -0,0 +1,33 @@
+---
+title: Spacing
+type: token
+id: spacing
+description: Spacing tokens based on the 8px unit.
+skipValidation: true
+---
+
+<!-- @default | row -->
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-1); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-1</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-2); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-2</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-3); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-3</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-4); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-4</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-6); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-6</small>
+</div>
+<div class="ui-column ui-column--xs" style="align-items: center">
+  <div style="width: var(--ui-space-8); height: var(--ui-space-4); background: var(--ui-color-primary)"></div>
+  <small>space-8</small>
+</div>

package/src/debug/debug.docs.html

@@ -0,0 +1,29 @@
+---
+title: Debug
+type: utility
+id: debug
+description: Visual debugging overlays for grid alignment, baseline rhythm, and element boundaries
+skipValidation: true
+---
+
+<!-- @grid_overlay -->
+<!-- Shows the 8px unit grid. Add the class to any container. -->
+<div class="ui-debug-grid" style="height: var(--ui-row-6); position: relative"></div>
+
+<!-- @row_grid -->
+<!-- Shows both 8px unit lines and stronger row (16px) lines. -->
+<div class="ui-debug-grid-rows" style="height: var(--ui-row-6); position: relative"></div>
+
+<!-- @baseline -->
+<!-- Horizontal baseline grid for verifying text alignment. -->
+<div class="ui-debug-baseline" style="height: var(--ui-row-6); position: relative"></div>
+
+<!-- @outline -->
+<!-- Outlines all child elements to reveal layout boundaries. -->
+<div class="ui-debug-outline">
+  <div class="ui-row ui-row--sm">
+    <div style="padding: var(--ui-space-1)">A</div>
+    <div style="padding: var(--ui-space-1)">B</div>
+    <div style="padding: var(--ui-space-1)">C</div>
+  </div>
+</div>

package/src/debug/index.scss

@@ -1 +1,81 @@
-@forward "./grid-overlay";
+@use '../config/tokens/variables' as t;
+// Debug grid overlay - add class="debug-grid" to body or any container
+.debug-grid,
+.debug-grid-rows,
+.debug-baseline {
+  position: relative;
+}
+
+.debug-grid {
+  // Fallback hue 220 (blue) when --ui-hue-primary not set
+  --debug-color: hsl(var(--ui-hue-primary, #{t.$hue-primary}) 80% 50% / 0.15);
+}
+
+.debug-grid::after {
+  content: "";
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: 0;
+  z-index: var(--ui-z-debug);
+
+  block-size: 100%;
+  inline-size: 100%;
+  min-block-size: 100vh;
+
+  background-image: linear-gradient(to right, var(--debug-color) 1px, transparent 1px),
+    linear-gradient(to bottom, var(--debug-color) 1px, transparent 1px);
+  pointer-events: none;
+  background-size: var(--ui-unit) var(--ui-unit);
+  background-position: 0 0;
+}
+
+// Stronger grid at row intervals
+.debug-grid-rows {
+  --debug-color: hsl(var(--ui-hue-primary, #{t.$hue-primary}) 80% 50% / 0.1);
+  --debug-color-strong: hsl(var(--ui-hue-primary, #{t.$hue-primary}) 80% 50% / 0.25);
+}
+
+.debug-grid-rows::after {
+  content: "";
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: 0;
+  z-index: var(--ui-z-debug);
+
+  block-size: 100%;
+  inline-size: 100%;
+  min-block-size: 100vh;
+
+  background-image: linear-gradient(to right, var(--debug-color) 1px, transparent 1px),
+    linear-gradient(to bottom, var(--debug-color) 1px, transparent 1px),
+    linear-gradient(to bottom, var(--debug-color-strong) 1px, transparent 1px);
+  pointer-events: none;
+  background-size: var(--ui-unit) var(--ui-unit), var(--ui-unit) var(--ui-unit), var(--ui-unit) var(--ui-row);
+  background-position: 0 0;
+}
+
+// Baseline grid only (horizontal lines)
+.debug-baseline {
+  --debug-color: hsl(var(--ui-hue-danger, 0) 80% 50% / 0.2);
+}
+
+.debug-baseline::after {
+  content: "";
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: 0;
+  z-index: var(--ui-z-debug);
+
+  block-size: 100%;
+  inline-size: 100%;
+  min-block-size: 100vh;
+
+  background-image: linear-gradient(to bottom, var(--debug-color) 1px, transparent 1px);
+  pointer-events: none;
+  background-size: 100% var(--ui-unit);
+}
+
+// Element boundaries outline
+.debug-outline * {
+  outline: 1px solid hsl(0 100% 50% / 0.5);
+}

package/src/layout/app-shell/app-shell.docs.html

@@ -0,0 +1,102 @@
+---
+title: Layout
+type: primitive
+id: layout
+description: Layout primitives for app shells with sidebars and content containers.
+api: app-shell.api.json
+---
+
+<!-- @app_shell_sidebar_main -->
+<!-- This page uses the layout primitives: -->
+<body class="ui-app-shell">
+  <aside class="ui-sidebar">
+    <!-- sidebar content -->
+  </aside>
+  <main class="ui-main">
+    <div class="ui-container">
+      <!-- page content -->
+    </div>
+  </main>
+</body>
+
+<!-- @with_topbar -->
+<!-- Add a fixed topbar by setting --topbar-height on app-shell. Sidebar and main offset automatically. -->
+<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>
+    <div class="ui-topbar__end">User</div>
+  </header>
+  <aside class="ui-sidebar">Sidebar</aside>
+  <main class="ui-main">
+    <div class="ui-container">Content</div>
+  </main>
+</body>
+
+<!-- @sidebar_widths | column -->
+<div class="ui-row ui-row--sm">
+  <code>.ui-sidebar--sm</code>
+  <span>192px (24 units)</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-sidebar--md</code>
+  <span>240px (30 units) - default</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-sidebar--lg</code>
+  <span>320px (40 units)</span>
+</div>
+
+<!-- @sidebar_position -->
+<!-- By default, sidebar is on the start (left in LTR). Use .ui-sidebar--end for right-side: -->
+<aside class="ui-sidebar ui-sidebar--end">...</aside>
+<main class="ui-main ui-main--sidebar-end">...</main>
+
+<!-- @container_widths | column -->
+<div class="ui-row ui-row--sm">
+  <code>.ui-container--sm</code>
+  <span>640px (80 units)</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-container--md</code>
+  <span>800px (100 units)</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-container--lg</code>
+  <span>960px (120 units) - default</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-container--xl</code>
+  <span>1280px (160 units)</span>
+</div>
+<div class="ui-row ui-row--sm">
+  <code>.ui-container--full</code>
+  <span>No max width</span>
+</div>
+
+<!-- @with_footer -->
+<!-- Place footer inside the content area, after the container. -->
+<body class="ui-app-shell">
+  <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>
+
+<!-- @topbar_variants -->
+<!-- Sticky stays in flow, raised adds shadow. -->
+<header class="ui-topbar ui-topbar--sticky ui-topbar--bordered">...</header>
+<header class="ui-topbar ui-topbar--raised">...</header>
+
+<!-- @footer_variants -->
+<!-- Sticky, fixed, and raised options. -->
+<footer class="ui-footer ui-footer--sticky ui-footer--bordered">...</footer>
+<footer class="ui-footer ui-footer--fixed">...</footer>
+<footer class="ui-footer ui-footer--raised">...</footer>
+
+<!-- @centered_container -->
+<div class="ui-container ui-container--center">
+  <!-- centered content with max-width -->
+</div>

package/src/layout/app-shell/app-shell.visual.spec.ts

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

package/src/layout/aspect-ratio/aspect-ratio.docs.html

@@ -0,0 +1,41 @@
+---
+title: Aspect Ratio
+type: primitive
+id: aspect-ratio
+description: Constrains a container to a specific aspect ratio. Media children fill the container automatically.
+api: aspect-ratio.api.json
+---
+
+<!-- @presets -->
+<div class="ui-row ui-row--md">
+  <div class="ui-aspect-ratio ui-aspect-ratio--square" style="inline-size: 160px; background: var(--ui-color-bg-muted)">
+    <span style="padding: var(--ui-space-2)">square</span>
+  </div>
+  <div class="ui-aspect-ratio ui-aspect-ratio--video" style="inline-size: 160px; background: var(--ui-color-bg-muted)">
+    <span style="padding: var(--ui-space-2)">video</span>
+  </div>
+  <div class="ui-aspect-ratio ui-aspect-ratio--photo" style="inline-size: 160px; background: var(--ui-color-bg-muted)">
+    <span style="padding: var(--ui-space-2)">photo</span>
+  </div>
+  <div class="ui-aspect-ratio ui-aspect-ratio--wide" style="inline-size: 160px; background: var(--ui-color-bg-muted)">
+    <span style="padding: var(--ui-space-2)">wide</span>
+  </div>
+  <div class="ui-aspect-ratio ui-aspect-ratio--portrait" style="inline-size: 160px; background: var(--ui-color-bg-muted)">
+    <span style="padding: var(--ui-space-2)">portrait</span>
+  </div>
+</div>
+
+<!-- @with_media -->
+<div class="ui-row ui-row--md">
+  <div class="ui-aspect-ratio ui-aspect-ratio--video" style="inline-size: 240px">
+    <div style="inline-size: 100%; block-size: 100%; background: var(--ui-color-primary); color: var(--ui-color-on-primary); display: grid; place-items: center">img (video)</div>
+  </div>
+  <div class="ui-aspect-ratio ui-aspect-ratio--square" style="inline-size: 240px">
+    <div style="inline-size: 100%; block-size: 100%; background: var(--ui-color-primary); color: var(--ui-color-on-primary); display: grid; place-items: center">img (square)</div>
+  </div>
+</div>
+
+<!-- @custom_ratio -->
+<div class="ui-aspect-ratio" style="--ui-aspect-ratio: 2.35 / 1; inline-size: 320px; background: var(--ui-color-bg-muted)">
+  <span style="padding: var(--ui-space-2)">2.35:1 (cinemascope)</span>
+</div>

package/src/layout/aspect-ratio/aspect-ratio.visual.spec.ts

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

package/src/layout/box/box.docs.html

@@ -0,0 +1,27 @@
+---
+title: Box
+type: primitive
+id: box
+description: Base container with style props. Foundation for layout primitives.
+api: box.api.json
+---
+
+<!-- @default -->
+<div class="ui-box">Content</div>
+
+<!-- @padding | column -->
+<div class="ui-box ui-box--p-1 ui-box--bg-subtle">Padding 1</div>
+<div class="ui-box ui-box--p-2 ui-box--bg-subtle">Padding 2</div>
+<div class="ui-box ui-box--p-3 ui-box--bg-subtle">Padding 3</div>
+<div class="ui-box ui-box--p-4 ui-box--bg-subtle">Padding 4</div>
+
+<!-- @background | column -->
+<div class="ui-box ui-box--p-2 ui-box--bg-subtle">Subtle background</div>
+<div class="ui-box ui-box--p-2 ui-box--bg-muted">Muted background</div>
+
+<!-- @rounded | row -->
+<div class="ui-box ui-box--p-3 ui-box--bg-subtle ui-box--rounded">Rounded</div>
+<div class="ui-box ui-box--p-3 ui-box--bg-subtle ui-box--rounded-lg">Rounded lg</div>
+
+<!-- @custom_via_css_variables -->
+<div class="ui-box" style="--box-padding: var(--ui-space-3); --box-bg: var(--ui-color-primary); --box-color: white; --box-radius: var(--ui-radius-lg);">Custom box</div>

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

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

package/src/layout/center/center.docs.html

@@ -0,0 +1,26 @@
+---
+title: Center
+type: primitive
+id: center
+description: Centers content horizontally and vertically.
+api: center.api.json
+---
+
+<!-- @basic -->
+<!-- Centers children both horizontally and vertically using flexbox. -->
+<div class="ui-center" style="height: var(--ui-row-4); background: var(--ui-color-bg-muted)">
+  <span>Centered content</span>
+</div>
+
+<!-- @column_direction -->
+<!-- Stack centered children vertically. -->
+<div class="ui-center ui-center--column" style="height: var(--ui-row-6); background: var(--ui-color-bg-muted)">
+  <span>First line</span>
+  <span>Second line</span>
+</div>
+
+<!-- @full_page_center -->
+<!-- Center content within a full viewport area, useful for loading or empty states. -->
+<div class="ui-center" style="height: var(--ui-row-8); background: var(--ui-color-bg-muted)">
+  <p>No results found</p>
+</div>

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

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

package/src/layout/column/column.docs.html

@@ -0,0 +1,32 @@
+---
+title: Column
+type: primitive
+id: column
+description: Vertical layout with consistent gap.
+api: column.api.json
+---
+
+<!-- @basic -->
+<div class="ui-column ui-column--sm">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Item 1</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Item 2</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-2)">Item 3</div>
+</div>
+
+<!-- @sizes -->
+<div class="ui-column ui-column--xs">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xs gap</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xs gap</div>
+</div>
+<div class="ui-column ui-column--md">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">md gap</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">md gap</div>
+</div>
+<div class="ui-column ui-column--lg">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">lg gap</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">lg gap</div>
+</div>
+<div class="ui-column ui-column--xl">
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xl gap</div>
+  <div style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">xl gap</div>
+</div>