@teseor/css 1.14.3 → 1.15.1

package/src/components/feedback/progress-circle/docs.html

@@ -0,0 +1,62 @@
+---
+title: Progress Circle
+description: Circular progress indicator showing completion as a donut ring. Set value via --ui-progress-circle-value (0-100).
+mergeInto: progress
+---
+
+<!-- @default | row -->
+<svg class="ui-progress-circle" style="--ui-progress-circle-value: 25" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle" style="--ui-progress-circle-value: 50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle" style="--ui-progress-circle-value: 75" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="75" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+
+<!-- @sizes | row -->
+<svg class="ui-progress-circle ui-progress-circle--sm" style="--ui-progress-circle-value: 50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle" style="--ui-progress-circle-value: 50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle ui-progress-circle--lg" style="--ui-progress-circle-value: 50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle ui-progress-circle--xl" style="--ui-progress-circle-value: 50" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+
+<!-- @colors | row -->
+<svg class="ui-progress-circle" style="--ui-progress-circle-value: 65" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle ui-progress-circle--success" style="--ui-progress-circle-value: 65" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle ui-progress-circle--warning" style="--ui-progress-circle-value: 65" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+<svg class="ui-progress-circle ui-progress-circle--danger" style="--ui-progress-circle-value: 65" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-valuenow="65" aria-valuemin="0" aria-valuemax="100">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>
+
+<!-- @indeterminate -->
+<!-- For unknown progress duration -->
+<svg class="ui-progress-circle ui-progress-circle--indeterminate" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="progressbar" aria-label="Loading">
+  <circle class="ui-progress-circle__track" cx="50" cy="50" r="45"></circle>
+  <circle class="ui-progress-circle__fill" cx="50" cy="50" r="45"></circle>
+</svg>

package/src/components/feedback/progress-circle/{progress-circle.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, 'progress-circle.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('progress-circle visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'progress-circle');
     await saveForLostPixel(page, 'progress-circle');
-    await expect(page.locator('body')).toHaveScreenshot('progress-circle.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/feedback/skeleton/docs.html

@@ -0,0 +1,37 @@
+---
+title: Skeleton
+description: Loading placeholder with shimmer animation for content loading states.
+---
+
+<!-- @text_lines -->
+<div style="display: flex; flex-direction: column; gap: var(--ui-space-1);">
+  <div class="ui-skeleton ui-skeleton--text"></div>
+  <div class="ui-skeleton ui-skeleton--text" style="width: 80%;"></div>
+  <div class="ui-skeleton ui-skeleton--text" style="width: 60%;"></div>
+</div>
+
+<!-- @shapes -->
+<div style="display: flex; gap: var(--ui-space-2); align-items: flex-start;">
+  <div class="ui-skeleton ui-skeleton--circle"></div>
+  <div style="flex: 1; display: flex; flex-direction: column; gap: var(--ui-space-1);">
+    <div class="ui-skeleton ui-skeleton--heading"></div>
+    <div class="ui-skeleton ui-skeleton--text"></div>
+  </div>
+</div>
+
+<!-- @card_skeleton -->
+<div class="ui-card" style="width: 300px;">
+  <div class="ui-skeleton ui-skeleton--rect"></div>
+  <div style="padding: var(--ui-space-2); display: flex; flex-direction: column; gap: var(--ui-space-1);">
+    <div class="ui-skeleton ui-skeleton--heading"></div>
+    <div class="ui-skeleton ui-skeleton--text"></div>
+    <div class="ui-skeleton ui-skeleton--text" style="width: 70%;"></div>
+  </div>
+</div>
+
+<!-- @pulse_animation -->
+<div class="ui-skeleton ui-skeleton--text ui-skeleton--pulse"></div>
+
+<!-- @static -->
+<!-- No animation, just a placeholder block. -->
+<div class="ui-skeleton ui-skeleton--static" style="width: 200px;"></div>

package/src/components/feedback/skeleton/{skeleton.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, 'skeleton.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('skeleton visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'skeleton');
     await saveForLostPixel(page, 'skeleton');
-    await expect(page.locator('body')).toHaveScreenshot('skeleton.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/feedback/spinner/docs.html

@@ -0,0 +1,26 @@
+---
+title: Spinner
+description: Loading indicator with pure CSS animation. Inherits color from parent.
+---
+
+<!-- @default | row -->
+<div class="ui-spinner"></div>
+
+<!-- @sizes | row -->
+{% for s in api.modifiers.size.values %}
+<div class="ui-spinner ui-spinner--{{ s }}"></div>
+{% endfor %}
+<div class="ui-spinner"></div>
+
+<!-- @color_inheritance -->
+<div class="ui-row" style="gap: var(--ui-space-2);">
+  <div style="color: var(--ui-color-primary);"><div class="ui-spinner"></div></div>
+  <div style="color: var(--ui-color-danger);"><div class="ui-spinner"></div></div>
+  <div style="color: var(--ui-color-success);"><div class="ui-spinner"></div></div>
+</div>
+
+<!-- @in_button -->
+<button class="ui-button ui-button--primary" disabled style="opacity: 0.7;">
+  <div class="ui-spinner ui-spinner--xs"></div>
+  <span>{{ t('loading', 'Loading...') }}</span>
+</button>

package/src/components/feedback/spinner/{spinner.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, 'spinner.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('spinner visual regression', () => {
   // TODO: Skip grid rhythm until #154 is resolved (CSS var resolution issue)
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     // await validateGridRhythm(page, 'spinner');
     await saveForLostPixel(page, 'spinner');
-    await expect(page.locator('body')).toHaveScreenshot('spinner.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/feedback/toast/docs.html

@@ -0,0 +1,106 @@
+---
+title: Toast
+---
+
+<!-- @default -->
+<div class="ui-toast">
+  <span class="ui-toast__icon">i</span>
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">Notification</p>
+    <p class="ui-toast__description">Your changes have been saved.</p>
+  </div>
+  <button class="ui-toast__close">X</button>
+</div>
+
+<!-- @variants | column -->
+<div class="ui-toast ui-toast--success">
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">Success</p>
+    <p class="ui-toast__description">Operation completed successfully.</p>
+  </div>
+</div>
+<div class="ui-toast ui-toast--warning">
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">Warning</p>
+    <p class="ui-toast__description">Please review before continuing.</p>
+  </div>
+</div>
+<div class="ui-toast ui-toast--danger">
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">Error</p>
+    <p class="ui-toast__description">Something went wrong.</p>
+  </div>
+</div>
+<div class="ui-toast ui-toast--info">
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">Info</p>
+    <p class="ui-toast__description">New updates available.</p>
+  </div>
+</div>
+
+<!-- @with_action -->
+<div class="ui-toast">
+  <div class="ui-toast__content">
+    <p class="ui-toast__title">File deleted</p>
+    <p class="ui-toast__description">document.pdf was moved to trash.</p>
+  </div>
+  <button class="ui-toast__action ui-button ui-button--sm ui-button--secondary">Undo</button>
+  <button class="ui-toast__close">X</button>
+</div>
+
+<!-- @viewport_positions | column -->
+<!-- Container positions for toast placement -->
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--top-end" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Top End</p>
+      </div>
+    </div>
+  </div>
+</div>
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--bottom-end" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Bottom End</p>
+      </div>
+    </div>
+  </div>
+</div>
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--top-start" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Top Start</p>
+      </div>
+    </div>
+  </div>
+</div>
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--top-center" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Top Center</p>
+      </div>
+    </div>
+  </div>
+</div>
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--bottom-start" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Bottom Start</p>
+      </div>
+    </div>
+  </div>
+</div>
+<div style="position:relative;height:200px;border:1px solid var(--ui-color-border);border-radius:var(--ui-radius-md)">
+  <div class="ui-toast-viewport ui-toast-viewport--bottom-center" style="position:absolute">
+    <div class="ui-toast">
+      <div class="ui-toast__content">
+        <p class="ui-toast__title">Bottom Center</p>
+      </div>
+    </div>
+  </div>
+</div>

package/src/components/feedback/toast/{toast.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, 'toast.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('toast visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'toast');
     await saveForLostPixel(page, 'toast');
-    await expect(page.locator('body')).toHaveScreenshot('toast.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/forms/checkbox/docs.html

@@ -0,0 +1,30 @@
+---
+title: Checkbox
+description: Native checkbox input with custom styling. Supports checked, indeterminate, and disabled states.
+---
+
+<!-- @default | row -->
+<input class="ui-checkbox" type="checkbox"></input>
+<input class="ui-checkbox" type="checkbox" checked></input>
+
+<!-- @sizes | row -->
+<input class="ui-checkbox" type="checkbox" checked></input>
+<input class="ui-checkbox ui-checkbox--lg" type="checkbox" checked></input>
+
+<!-- @states | row -->
+<input class="ui-checkbox" type="checkbox"></input>
+<input class="ui-checkbox" type="checkbox" checked></input>
+<input class="ui-checkbox" type="checkbox" disabled></input>
+<input class="ui-checkbox" type="checkbox" checked disabled></input>
+
+<!-- @validation_states | row -->
+<input class="ui-checkbox ui-checkbox--error" type="checkbox"></input>
+<input class="ui-checkbox ui-checkbox--error" type="checkbox" checked></input>
+<input class="ui-checkbox ui-checkbox--success" type="checkbox"></input>
+<input class="ui-checkbox ui-checkbox--success" type="checkbox" checked></input>
+
+<!-- @with_label -->
+<label class="ui-row" style="gap: var(--ui-space-1); cursor: pointer;">
+  <input class="ui-checkbox" type="checkbox"></input>
+  <span>Accept terms and conditions</span>
+</label>

package/src/components/forms/checkbox/{checkbox.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, 'checkbox.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('checkbox visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'checkbox');
     await saveForLostPixel(page, 'checkbox');
-    await expect(page.locator('body')).toHaveScreenshot('checkbox.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/forms/checkbox-group/docs.html

@@ -0,0 +1,101 @@
+---
+title: Checkbox Group
+description: Groups related checkboxes with a legend and consistent spacing. Built on native fieldset semantics.
+mergeInto: checkbox
+---
+
+<!-- @default -->
+<fieldset class="ui-checkbox-group">
+  <legend class="ui-checkbox-group__legend">Notifications</legend>
+  <div class="ui-checkbox-group__items">
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Email</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>SMS</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>Push</span>
+    </label>
+  </div>
+</fieldset>
+
+<!-- @horizontal -->
+<fieldset class="ui-checkbox-group ui-checkbox-group--horizontal">
+  <legend class="ui-checkbox-group__legend">Interests</legend>
+  <div class="ui-checkbox-group__items">
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Design</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>Engineering</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Product</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>Marketing</span>
+    </label>
+  </div>
+</fieldset>
+
+<!-- @compact -->
+<fieldset class="ui-checkbox-group ui-checkbox-group--compact">
+  <legend class="ui-checkbox-group__legend">Features</legend>
+  <div class="ui-checkbox-group__items">
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Dark mode</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Notifications</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>Analytics</span>
+    </label>
+  </div>
+</fieldset>
+
+<!-- @error_state -->
+<fieldset class="ui-checkbox-group ui-checkbox-group--error">
+  <legend class="ui-checkbox-group__legend">Terms</legend>
+  <div class="ui-checkbox-group__items">
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox ui-checkbox--error" type="checkbox"></input>
+      <span>I accept the terms of service</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox ui-checkbox--error" type="checkbox"></input>
+      <span>I accept the privacy policy</span>
+    </label>
+  </div>
+  <span class="ui-form-error">You must accept all terms to continue</span>
+</fieldset>
+
+<!-- @disabled -->
+<fieldset class="ui-checkbox-group" disabled>
+  <legend class="ui-checkbox-group__legend">Permissions (locked)</legend>
+  <div class="ui-checkbox-group__items">
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Read</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox" checked></input>
+      <span>Write</span>
+    </label>
+    <label class="ui-checkbox-group__item">
+      <input class="ui-checkbox" type="checkbox"></input>
+      <span>Admin</span>
+    </label>
+  </div>
+</fieldset>

package/src/components/forms/checkbox-group/{checkbox-group.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, 'checkbox-group.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('checkbox-group visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'checkbox-group');
     await saveForLostPixel(page, 'checkbox-group');
-    await expect(page.locator('body')).toHaveScreenshot('checkbox-group.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });

package/src/components/forms/field/docs.html

@@ -0,0 +1,60 @@
+---
+title: Field
+description: Form field wrapper that combines label, control, helper text, and error message.
+---
+
+<!-- @default -->
+<div class="ui-field">
+  <label class="ui-label" for="email">Email</label>
+  <div class="ui-field__control">
+    <input class="ui-input" type="email" id="email" placeholder="Enter email"></input>
+  </div>
+</div>
+
+<!-- @with_helper_text -->
+<div class="ui-field">
+  <label class="ui-label" for="password">Password</label>
+  <div class="ui-field__control">
+    <input class="ui-input" type="password" id="password"></input>
+    <span class="ui-form-helper">Must be at least 8 characters</span>
+  </div>
+</div>
+
+<!-- @with_error -->
+<div class="ui-field">
+  <label class="ui-label" for="username">Username</label>
+  <div class="ui-field__control">
+    <input class="ui-input ui-input--error" type="text" id="username" value="ab"></input>
+    <span class="ui-form-error">Username must be at least 3 characters</span>
+  </div>
+</div>
+
+<!-- @horizontal_layout -->
+<!-- Label beside control for wider forms -->
+<div class="ui-field ui-field--horizontal">
+  <label class="ui-label ui-field__label" for="name">Full Name</label>
+  <div class="ui-field__control">
+    <input class="ui-input" type="text" id="name"></input>
+    <span class="ui-form-helper">As it appears on your ID</span>
+  </div>
+</div>
+
+<!-- @responsive_layout -->
+<!-- Auto-switches to horizontal layout when container is wide enough (>= 30rem). Requires a parent with container-type: inline-size (use ui-container-inline utility). -->
+<div class="ui-container-inline">
+  <div class="ui-field ui-field--responsive">
+    <label class="ui-label ui-field__label" for="resp-name">Full Name</label>
+    <div class="ui-field__control">
+      <input class="ui-input" type="text" id="resp-name"></input>
+      <span class="ui-form-helper">Stacks vertically in narrow containers, horizontal at >= 30rem</span>
+    </div>
+  </div>
+</div>
+
+<!-- @required_field -->
+<div class="ui-field">
+  <label class="ui-label ui-label--required" for="req">Required Field</label>
+  <div class="ui-field__control">
+    <input class="ui-input" type="text" id="req" required></input>
+  </div>
+</div>

package/src/components/forms/field/{field.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, 'field.docs.json');
+const DOCS_PATH = resolve(__dirname, 'docs.html');
 
 test.describe('field visual regression', () => {
   test('all variations', async ({ page }) => {
-    await setupVisualTestFromDocs(page, DOCS_PATH);
+    await setupVisualTestFromHtmlDocs(page, DOCS_PATH);
     await validateGridRhythm(page, 'field');
     await saveForLostPixel(page, 'field');
-    await expect(page.locator('body')).toHaveScreenshot('field.visual.png');
+    await expect(page.locator('body')).toHaveScreenshot('visual.png');
   });
 });