@teseor/css 1.14.3 → 1.15.1

package/src/components/content/spacer/docs.html

@@ -0,0 +1,20 @@
+---
+title: Spacer
+description: Flexible space filler that grows to fill available space in flex containers.
+---
+
+<!-- @default -->
+<div class="ui-row" style="inline-size: 100%; background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">Start</span>
+  <div class="ui-spacer"></div>
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">End</span>
+</div>
+
+<!-- @between_items -->
+<div class="ui-row" style="inline-size: 100%; background: var(--ui-color-bg-subtle); padding: var(--ui-space-2)">
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">Logo</span>
+  <div class="ui-spacer"></div>
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">Nav 1</span>
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">Nav 2</span>
+  <span style="background: var(--ui-color-bg-muted); padding: var(--ui-space-1)">Nav 3</span>
+</div>

package/src/components/content/spacer/{spacer.visual.spec.ts → visual.spec.ts}

@@ -1,14 +1,14 @@
 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, 'spacer.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('spacer visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     // skip validateGridRhythm: spacer has no intrinsic height
     await saveForLostPixel(page, 'spacer');
-    await expect(page.locator('body')).toHaveScreenshot('spacer.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/data-display/avatar/docs.html

@@ -0,0 +1,64 @@
+---
+title: Avatar
+description: User or entity thumbnail representation. Supports image with fallback to initials.
+---
+
+<!-- @default | row -->
+<div class="ui-avatar">
+  <span class="ui-avatar__fallback">JD</span>
+</div>
+<div class="ui-avatar">
+  <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=1" alt="User"></img>
+</div>
+
+<!-- @sizes | row -->
+<div class="ui-avatar ui-avatar--xs">
+  <span class="ui-avatar__fallback">XS</span>
+</div>
+<div class="ui-avatar ui-avatar--sm">
+  <span class="ui-avatar__fallback">SM</span>
+</div>
+<div class="ui-avatar">
+  <span class="ui-avatar__fallback">MD</span>
+</div>
+<div class="ui-avatar ui-avatar--lg">
+  <span class="ui-avatar__fallback">LG</span>
+</div>
+<div class="ui-avatar ui-avatar--xl">
+  <span class="ui-avatar__fallback">XL</span>
+</div>
+
+<!-- @square_shape | row -->
+<div class="ui-avatar ui-avatar--square">
+  <span class="ui-avatar__fallback">ORG</span>
+</div>
+<div class="ui-avatar ui-avatar--square">
+  <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=org" alt="Org"></img>
+</div>
+
+<!-- @with_images | row -->
+<div class="ui-avatar ui-avatar--sm">
+  <img class="ui-avatar__image" src="https://i.pravatar.cc/64?u=a" alt="User A"></img>
+</div>
+<div class="ui-avatar">
+  <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=b" alt="User B"></img>
+</div>
+<div class="ui-avatar ui-avatar--lg">
+  <img class="ui-avatar__image" src="https://i.pravatar.cc/96?u=c" alt="User C"></img>
+</div>
+
+<!-- @avatar_group -->
+<div class="ui-avatar-group">
+  <div class="ui-avatar">
+    <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=g1" alt></img>
+  </div>
+  <div class="ui-avatar">
+    <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=g2" alt></img>
+  </div>
+  <div class="ui-avatar">
+    <img class="ui-avatar__image" src="https://i.pravatar.cc/80?u=g3" alt></img>
+  </div>
+  <div class="ui-avatar">
+    <span class="ui-avatar__fallback">+5</span>
+  </div>
+</div>

package/src/components/data-display/avatar/{avatar.visual.spec.ts → visual.spec.ts}

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

package/src/components/data-display/badge/docs.html

@@ -0,0 +1,37 @@
+---
+title: Badge
+description: Inline labels for status indicators, counts, and categories
+labels:
+  sm: Small
+  lg: Large
+  primary: Primary
+  success: Success
+  warning: Warning
+  danger: Danger
+---
+
+<!-- @default -->
+<span class="ui-badge">{{ t('default', 'Default') }}</span>
+
+<!-- @variants | row -->
+<span class="ui-badge">{{ t('default', 'Default') }}</span>
+{% for v in api.modifiers.variant.values %}
+<span class="ui-badge ui-badge--{{ v }}">{{ t(v, labels[v]) }}</span>
+{% endfor %}
+
+<!-- @sizes | row -->
+{% for s in api.modifiers.size.values %}
+<span class="ui-badge ui-badge--{{ s }}">{{ t(s, labels[s]) }}</span>
+{% endfor %}
+<span class="ui-badge">{{ t('default', 'Default') }}</span>
+
+<!-- @use_cases -->
+<div class="ui-row">
+  <span>{{ t('notifications', 'Notifications') }}</span>
+  <span class="ui-badge ui-badge--primary">5</span>
+</div>
+<div class="ui-row">
+  <span class="ui-badge ui-badge--success">{{ t('published', 'Published') }}</span>
+  <span class="ui-badge ui-badge--warning">{{ t('draft', 'Draft') }}</span>
+  <span class="ui-badge ui-badge--danger">{{ t('archived', 'Archived') }}</span>
+</div>

package/src/components/data-display/badge/{badge.visual.spec.ts → visual.spec.ts}

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

package/src/components/data-display/card/docs.html

@@ -0,0 +1,33 @@
+---
+title: Card
+---
+
+<!-- @default -->
+<div class="ui-card">Default card with padding and border</div>
+
+<!-- @background_variants | column -->
+<div class="ui-card">Default background</div>
+<div class="ui-card ui-card--subtle">Subtle background</div>
+<div class="ui-card ui-card--muted">Muted background</div>
+
+<!-- @padding_variants | column -->
+<div class="ui-card ui-card--sm">Small padding</div>
+<div class="ui-card">Default padding</div>
+<div class="ui-card ui-card--lg">Large padding</div>
+<div class="ui-card ui-card--flush">No padding (flush)</div>
+
+<!-- @interactive | column -->
+<div class="ui-card ui-card--interactive">Hover and click this card</div>
+<div class="ui-card ui-card--interactive ui-card--subtle">Interactive subtle card</div>
+
+<!-- @responsive_container_query -->
+<!-- Switches to horizontal layout when container is wide enough. Requires a parent with container-type: inline-size (use ui-container-inline utility). -->
+<div class="ui-container-inline">
+  <div class="ui-card ui-card--responsive">
+    <div class="ui-card__media" style="background: var(--ui-color-bg-muted); min-block-size: 6rem"></div>
+    <div class="ui-card__body">
+      <strong>Responsive Card</strong>
+      <p>Stacks vertically in narrow containers, switches to side-by-side at >= 30rem.</p>
+    </div>
+  </div>
+</div>

package/src/components/data-display/card/{card.visual.spec.ts → visual.spec.ts}

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

package/src/components/data-display/data-list/docs.html

@@ -0,0 +1,94 @@
+---
+title: Data List
+---
+
+<!-- @default -->
+<dl class="ui-data-list">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Name</dt>
+    <dd class="ui-data-list__value">John Doe</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Email</dt>
+    <dd class="ui-data-list__value">john@example.com</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Role</dt>
+    <dd class="ui-data-list__value">Administrator</dd>
+  </div>
+</dl>
+
+<!-- @horizontal_layout -->
+<!-- Side-by-side label and value -->
+<dl class="ui-data-list ui-data-list--horizontal">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Status</dt>
+    <dd class="ui-data-list__value">Active</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Created</dt>
+    <dd class="ui-data-list__value">Dec 8, 2025</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Updated</dt>
+    <dd class="ui-data-list__value">Dec 8, 2025</dd>
+  </div>
+</dl>
+
+<!-- @divided -->
+<!-- With separator lines between items -->
+<dl class="ui-data-list ui-data-list--divided">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Order ID</dt>
+    <dd class="ui-data-list__value">#12345</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Total</dt>
+    <dd class="ui-data-list__value">$99.00</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Payment</dt>
+    <dd class="ui-data-list__value">Credit Card</dd>
+  </div>
+</dl>
+
+<!-- @striped -->
+<!-- Alternating background for readability -->
+<dl class="ui-data-list ui-data-list--striped">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">CPU</dt>
+    <dd class="ui-data-list__value">Intel i7</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Memory</dt>
+    <dd class="ui-data-list__value">16 GB</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Storage</dt>
+    <dd class="ui-data-list__value">512 GB SSD</dd>
+  </div>
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Display</dt>
+    <dd class="ui-data-list__value">14" Retina</dd>
+  </div>
+</dl>
+
+<!-- @sizes | column -->
+<dl class="ui-data-list ui-data-list--sm">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Small</dt>
+    <dd class="ui-data-list__value">Compact display</dd>
+  </div>
+</dl>
+<dl class="ui-data-list">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Default</dt>
+    <dd class="ui-data-list__value">Standard display</dd>
+  </div>
+</dl>
+<dl class="ui-data-list ui-data-list--lg">
+  <div class="ui-data-list__item">
+    <dt class="ui-data-list__label">Large</dt>
+    <dd class="ui-data-list__value">Spacious display</dd>
+  </div>
+</dl>

package/src/components/data-display/data-list/{data-list.visual.spec.ts → visual.spec.ts}

@@ -2,18 +2,18 @@ import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
 import {
   saveForLostPixel,
-  setupVisualTestFromDocs,
+  setupVisualTestFromHtmlDocs,
   validateGridRhythm,
 } from '../../../../test-utils';
 
-const DOCS_PATH = resolve(__dirname, 'data-list.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('data-list visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     // TODO: fix grid rhythm - 1px borders cause off-grid heights (#179)
     // await validateGridRhythm(page, 'data-list');
     await saveForLostPixel(page, 'data-list');
-    await expect(page.locator('body')).toHaveScreenshot('data-list.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/data-display/icon/docs.html

@@ -0,0 +1,69 @@
+---
+title: Icon
+description: CSS classes for sizing and styling SVG icons. Works with any stroke-based icon set like Lucide, Heroicons, or Feather.
+---
+
+<!-- @basic_usage -->
+<!-- Add the `ui-icon` class to any SVG. Icons inherit color from their parent via `currentColor`. -->
+<svg class="ui-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14"/></svg>
+
+<!-- @with_lucide_icons -->
+<!-- Recommended icon set. Copy SVG from lucide.dev and add the ui-icon class. -->
+<div class="ui-row ui-row--gap-2">
+  <svg class="ui-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><polyline points="9 22 9 12 15 12 15 22"/></svg>
+  <svg class="ui-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <svg class="ui-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9"/><path d="M10.3 21a1.94 1.94 0 0 0 3.4 0"/></svg>
+  <svg class="ui-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/></svg>
+</div>
+
+<!-- @sizes | row -->
+<!-- Scale icons from extra small to extra large. -->
+<div class="ui-column" style="align-items: center; gap: var(--ui-space-1)">
+  <svg class="ui-icon ui-icon--xs" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <small>xs</small>
+</div>
+<div class="ui-column" style="align-items: center; gap: var(--ui-space-1)">
+  <svg class="ui-icon ui-icon--sm" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <small>sm</small>
+</div>
+<div class="ui-column" style="align-items: center; gap: var(--ui-space-1)">
+  <svg class="ui-icon ui-icon--md" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <small>md</small>
+</div>
+<div class="ui-column" style="align-items: center; gap: var(--ui-space-1)">
+  <svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <small>lg</small>
+</div>
+<div class="ui-column" style="align-items: center; gap: var(--ui-space-1)">
+  <svg class="ui-icon ui-icon--xl" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  <small>xl</small>
+</div>
+
+<!-- @stroke_width | row -->
+<!-- Adjust stroke thickness for visual weight. -->
+<svg class="ui-icon ui-icon--lg ui-icon--stroke-thin" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+<svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+<svg class="ui-icon ui-icon--lg ui-icon--stroke-thick" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+
+<!-- @filled_icons | row -->
+<!-- For solid icons, use the `--filled` modifier. -->
+<svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"/></svg>
+<svg class="ui-icon ui-icon--lg ui-icon--filled" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z"/></svg>
+
+<!-- @spin_animation -->
+<!-- Use `--spin` for loading indicators. -->
+<svg class="ui-icon ui-icon--lg ui-icon--spin" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 12a9 9 0 1 1-6.219-8.56"/></svg>
+
+<!-- @color_inheritance -->
+<!-- Icons inherit color from parent text color. -->
+<div class="ui-row ui-row--gap-2">
+  <span style="color: var(--ui-color-primary)">
+    <svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  </span>
+  <span style="color: var(--ui-color-success)">
+    <svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  </span>
+  <span style="color: var(--ui-color-danger)">
+    <svg class="ui-icon ui-icon--lg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+  </span>
+</div>

package/src/components/data-display/icon/{icon.visual.spec.ts → visual.spec.ts}

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

package/src/components/data-display/image/docs.html

@@ -0,0 +1,64 @@
+---
+title: Image
+description: Responsive image with fallback placeholder, optional caption, and shape modifiers.
+---
+
+<!-- @default -->
+<figure class="ui-image">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='160'%3E%3Crect fill='%23b0bec5' width='192' height='160'/%3E%3C/svg%3E" alt="Placeholder"></img>
+</figure>
+
+<!-- @sizes | row -->
+<figure class="ui-image ui-image--sm">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96'%3E%3Crect fill='%2390a4ae' width='96' height='96'/%3E%3C/svg%3E" alt="Small"></img>
+</figure>
+<figure class="ui-image ui-image--md">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='192'%3E%3Crect fill='%2378909c' width='192' height='192'/%3E%3C/svg%3E" alt="Medium"></img>
+</figure>
+<figure class="ui-image ui-image--lg">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='320'%3E%3Crect fill='%23607d8b' width='320' height='320'/%3E%3C/svg%3E" alt="Large"></img>
+</figure>
+<figure class="ui-image ui-image--xl">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='480' height='480'%3E%3Crect fill='%23546e7a' width='480' height='480'/%3E%3C/svg%3E" alt="XL"></img>
+</figure>
+<figure class="ui-image ui-image--full">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='600' height='200'%3E%3Crect fill='%23455a64' width='600' height='200'/%3E%3C/svg%3E" alt="Full"></img>
+</figure>
+
+<!-- @rounded -->
+<figure class="ui-image ui-image--md ui-image--rounded">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='140'%3E%3Crect fill='%234db6ac' width='192' height='140'/%3E%3C/svg%3E" alt="Rounded"></img>
+</figure>
+
+<!-- @circle | row -->
+<figure class="ui-image ui-image--sm ui-image--circle">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='96' height='96'%3E%3Crect fill='%23ce93d8' width='96' height='96'/%3E%3C/svg%3E" alt="Circle small"></img>
+</figure>
+<figure class="ui-image ui-image--md ui-image--circle">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='192'%3E%3Crect fill='%23ba68c8' width='192' height='192'/%3E%3C/svg%3E" alt="Circle medium"></img>
+</figure>
+
+<!-- @object_fit | row -->
+<figure class="ui-image ui-image--md ui-image--cover">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='150'%3E%3Crect fill='%2364b5f6' width='300' height='150'/%3E%3Ctext x='150' y='80' text-anchor='middle' fill='%23fff' font-size='16'%3Ecover%3C/text%3E%3C/svg%3E" alt="Cover fit"></img>
+</figure>
+<figure class="ui-image ui-image--md ui-image--contain">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='150'%3E%3Crect fill='%2381c784' width='300' height='150'/%3E%3Ctext x='150' y='80' text-anchor='middle' fill='%23fff' font-size='16'%3Econtain%3C/text%3E%3C/svg%3E" alt="Contain fit"></img>
+</figure>
+
+<!-- @caption -->
+<figure class="ui-image ui-image--md ui-image--rounded">
+  <img class="ui-image__img" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='192' height='140'%3E%3Crect fill='%23ffb74d' width='192' height='140'/%3E%3C/svg%3E" alt="With caption"></img>
+  <figcaption class="ui-image__caption">An optional image caption</figcaption>
+</figure>
+
+<!-- @fallback | row -->
+<figure class="ui-image ui-image--sm">
+  <img class="ui-image__img" src alt="Broken image"></img>
+</figure>
+<figure class="ui-image ui-image--sm ui-image--rounded">
+  <img class="ui-image__img" src alt="Broken rounded"></img>
+</figure>
+<figure class="ui-image ui-image--sm ui-image--circle">
+  <img class="ui-image__img" src alt="Broken circle"></img>
+</figure>

package/src/components/data-display/image/{image.visual.spec.ts → visual.spec.ts}

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

package/src/components/data-display/stat/docs.html

@@ -0,0 +1,32 @@
+---
+title: Stat
+description: Statistic display with prominent value and descriptive label.
+---
+
+<!-- @default -->
+<div class="ui-stat">
+  <span class="ui-stat__value">2,847</span>
+  <span class="ui-stat__label">Total users</span>
+</div>
+
+<!-- @multiple_stats -->
+<div class="ui-row ui-row--lg">
+  <div class="ui-stat">
+    <span class="ui-stat__value">12.5k</span>
+    <span class="ui-stat__label">Revenue</span>
+  </div>
+  <div class="ui-stat">
+    <span class="ui-stat__value">573</span>
+    <span class="ui-stat__label">Orders</span>
+  </div>
+  <div class="ui-stat">
+    <span class="ui-stat__value">98%</span>
+    <span class="ui-stat__label">Satisfaction</span>
+  </div>
+</div>
+
+<!-- @small -->
+<div class="ui-stat ui-stat--sm">
+  <span class="ui-stat__value">42</span>
+  <span class="ui-stat__label">Active now</span>
+</div>

package/src/components/data-display/stat/{stat.visual.spec.ts → visual.spec.ts}

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