@teseor/css 1.14.3 → 1.15.0

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

@@ -0,0 +1,235 @@
+---
+title: Sidebar Nav
+type: primitive
+id: sidebar-nav
+description: Navigation component for sidebars with support for groups, nested items, icons, and badges.
+api: ./sidebar-nav.api.json
+---
+
+<!-- @basic -->
+<!-- Simple navigation with grouped items. -->
+<nav class="ui-sidebar-nav" aria-label="Main navigation" style="block-size: 400px;">
+  <div class="ui-sidebar-nav__header">
+    <strong>App Name</strong>
+  </div>
+  <div class="ui-sidebar-nav__content">
+    <div class="ui-sidebar-nav__group">
+      <span class="ui-sidebar-nav__group-label">Main</span>
+      <ul class="ui-sidebar-nav__group-items">
+        <li>
+          <a class="ui-sidebar-nav__item ui-sidebar-nav__item--active" href="#" aria-current="page">
+            <span class="ui-sidebar-nav__label">Dashboard</span>
+          </a>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item" href="#">
+            <span class="ui-sidebar-nav__label">Projects</span>
+          </a>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item" href="#">
+            <span class="ui-sidebar-nav__label">Tasks</span>
+          </a>
+        </li>
+      </ul>
+    </div>
+    <div class="ui-sidebar-nav__group">
+      <span class="ui-sidebar-nav__group-label">Settings</span>
+      <ul class="ui-sidebar-nav__group-items">
+        <li>
+          <a class="ui-sidebar-nav__item" href="#">
+            <span class="ui-sidebar-nav__label">Profile</span>
+          </a>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item" href="#">
+            <span class="ui-sidebar-nav__label">Preferences</span>
+          </a>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <div class="ui-sidebar-nav__footer">
+    <a class="ui-sidebar-nav__item" href="#">
+      <span class="ui-sidebar-nav__label">Logout</span>
+    </a>
+  </div>
+</nav>
+
+<!-- @with_icons -->
+<!-- Navigation items with icons for visual clarity. -->
+<nav class="ui-sidebar-nav" aria-label="Navigation" style="block-size: 300px;">
+  <div class="ui-sidebar-nav__content">
+    <ul class="ui-sidebar-nav__group-items">
+      <li>
+        <a class="ui-sidebar-nav__item ui-sidebar-nav__item--active" href="#" aria-current="page">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Home</span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+              <circle cx="9" cy="7" r="4"></circle>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Users</span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="3"></circle>
+              <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Settings</span>
+        </a>
+      </li>
+    </ul>
+  </div>
+</nav>
+
+<!-- @with_badges -->
+<!-- Navigation items with badges for counts or status indicators. -->
+<nav class="ui-sidebar-nav" aria-label="Navigation" style="block-size: 200px;">
+  <div class="ui-sidebar-nav__content">
+    <ul class="ui-sidebar-nav__group-items">
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__label">Inbox</span>
+          <span class="ui-sidebar-nav__badge">
+            <span class="ui-badge ui-badge--primary">12</span>
+          </span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__label">Notifications</span>
+          <span class="ui-sidebar-nav__badge">
+            <span class="ui-badge ui-badge--danger">3</span>
+          </span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__label">Updates</span>
+          <span class="ui-sidebar-nav__badge">
+            <span class="ui-status ui-status--success"></span>
+          </span>
+        </a>
+      </li>
+    </ul>
+  </div>
+</nav>
+
+<!-- @nested_items -->
+<!-- Navigation with nested/indented items for sub-sections. -->
+<nav class="ui-sidebar-nav" aria-label="Navigation" style="block-size: 280px;">
+  <div class="ui-sidebar-nav__content">
+    <div class="ui-sidebar-nav__group">
+      <span class="ui-sidebar-nav__group-label">Components</span>
+      <ul class="ui-sidebar-nav__group-items">
+        <li>
+          <div class="ui-sidebar-nav__subgroup">
+            <span class="ui-sidebar-nav__subgroup-label">Actions</span>
+          </div>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item ui-sidebar-nav__item--nested" href="#">
+            <span class="ui-sidebar-nav__label">Button</span>
+          </a>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item ui-sidebar-nav__item--nested ui-sidebar-nav__item--active" href="#" aria-current="page">
+            <span class="ui-sidebar-nav__label">Button Group</span>
+          </a>
+        </li>
+        <li>
+          <span class="ui-sidebar-nav__subgroup-label">Forms</span>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item ui-sidebar-nav__item--nested" href="#">
+            <span class="ui-sidebar-nav__label">Input</span>
+          </a>
+        </li>
+        <li>
+          <a class="ui-sidebar-nav__item ui-sidebar-nav__item--nested" href="#">
+            <span class="ui-sidebar-nav__label">Select</span>
+          </a>
+        </li>
+      </ul>
+    </div>
+  </div>
+</nav>
+
+<!-- @collapsed -->
+<!-- Icon-only mode for compact sidebars. -->
+<nav class="ui-sidebar-nav ui-sidebar-nav--collapsed" aria-label="Navigation" style="block-size: 200px;">
+  <div class="ui-sidebar-nav__content">
+    <ul class="ui-sidebar-nav__group-items">
+      <li>
+        <a class="ui-sidebar-nav__item ui-sidebar-nav__item--active" href="#" aria-current="page" aria-label="Home">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Home</span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#" aria-label="Users">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
+              <circle cx="9" cy="7" r="4"></circle>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Users</span>
+        </a>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#" aria-label="Settings">
+          <span class="ui-sidebar-nav__icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="3"></circle>
+            </svg>
+          </span>
+          <span class="ui-sidebar-nav__label">Settings</span>
+        </a>
+      </li>
+    </ul>
+  </div>
+</nav>
+
+<!-- @disabled_items -->
+<!-- Non-interactive navigation items. -->
+<nav class="ui-sidebar-nav" aria-label="Navigation" style="block-size: 180px;">
+  <div class="ui-sidebar-nav__content">
+    <ul class="ui-sidebar-nav__group-items">
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__label">Active Link</span>
+        </a>
+      </li>
+      <li>
+        <span class="ui-sidebar-nav__item ui-sidebar-nav__item--disabled">
+          <span class="ui-sidebar-nav__label">Disabled Link</span>
+        </span>
+      </li>
+      <li>
+        <a class="ui-sidebar-nav__item" href="#">
+          <span class="ui-sidebar-nav__label">Another Link</span>
+        </a>
+      </li>
+    </ul>
+  </div>
+</nav>

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

package/src/layout/topbar/topbar.docs.html

@@ -0,0 +1,64 @@
+---
+title: Topbar
+type: primitive
+id: topbar
+description: Fixed or sticky header bar for app layouts with start, center, and end sections.
+api: ./topbar.api.json
+---
+
+<!-- @default -->
+<!-- Basic topbar with three sections: start (brand), center (search/nav), and end (actions). -->
+<header class="ui-topbar ui-topbar--bordered">
+  <div class="ui-topbar__start">
+    <strong>Brand</strong>
+  </div>
+  <div class="ui-topbar__center">
+    <span>Center content</span>
+  </div>
+  <div class="ui-topbar__end">
+    <span>Actions</span>
+  </div>
+</header>
+
+<!-- @sticky -->
+<!-- Stays at the top of the viewport on scroll. -->
+<header class="ui-topbar ui-topbar--sticky ui-topbar--bordered">
+  <div class="ui-topbar__start"><strong>Brand</strong></div>
+  <div class="ui-topbar__center">Nav</div>
+  <div class="ui-topbar__end">Actions</div>
+</header>
+
+<!-- @bordered -->
+<!-- Bottom border via inset box-shadow to preserve grid rhythm. -->
+<header class="ui-topbar ui-topbar--bordered">
+  <div class="ui-topbar__start">
+    <strong>Bordered</strong>
+  </div>
+  <div class="ui-topbar__end">
+    <span>Actions</span>
+  </div>
+</header>
+
+<!-- @raised -->
+<!-- Subtle drop shadow below the topbar. -->
+<header class="ui-topbar ui-topbar--raised">
+  <div class="ui-topbar__start">
+    <strong>Raised</strong>
+  </div>
+  <div class="ui-topbar__end">
+    <span>Actions</span>
+  </div>
+</header>
+
+<!-- @integration_with_sidebar -->
+<!-- Set --topbar-height on .app-shell so sidebar and main offset correctly. The topbar itself uses --fixed, and sidebar/main read --topbar-height. -->
+<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>

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

package/src/utilities/container/container.docs.html

@@ -0,0 +1,34 @@
+---
+title: Container
+type: utility
+id: container-utils
+description: Container query utilities for component-level responsive design.
+api: container.api.json
+---
+
+<!-- @inline_size_containment -->
+<!-- Establish inline-size containment so children can use container queries to respond to the container width. -->
+<div class="ui-container-inline ui-p-2" style="background: var(--ui-color-bg-muted)">
+  <div class="ui-card">This card is inside an inline-size container</div>
+</div>
+
+<!-- @size_containment -->
+<!-- Establish containment on both axes for container queries on width and height. -->
+<div class="ui-container-size ui-p-2" style="background: var(--ui-color-bg-muted); block-size: 12rem">
+  <div class="ui-card">Inside a size container</div>
+</div>
+
+<!-- @remove_containment -->
+<!-- Reset container type back to normal (no containment). -->
+<div class="ui-container-normal ui-p-2" style="background: var(--ui-color-bg-muted)">
+  <div class="ui-card">No containment on this container</div>
+</div>
+
+<!-- @with_responsive_card -->
+<!-- Combine container-inline with card--responsive for automatic horizontal layout at wider container sizes. -->
+<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">Card switches to horizontal layout when container is wide enough</div>
+  </div>
+</div>

package/src/utilities/display/display.docs.html

@@ -0,0 +1,30 @@
+---
+title: Display
+type: utility
+id: display-utils
+description: Flexbox and display utilities.
+api: display.api.json
+---
+
+<!-- @flex_layout -->
+<div class="ui-flex ui-justify-between ui-items-center ui-gap-2 ui-p-2" style="background: var(--ui-color-bg-muted)">
+  <span>Start</span>
+  <span>Center (items-center)</span>
+  <span>End</span>
+</div>
+
+<!-- @flex_direction | row -->
+<div class="ui-flex ui-flex-col ui-gap-1 ui-p-2" style="background: var(--ui-color-bg-muted)">
+  <span>Column 1</span>
+  <span>Column 2</span>
+  <span>Column 3</span>
+</div>
+<div class="ui-flex ui-flex-row ui-gap-1 ui-p-2" style="background: var(--ui-color-bg-muted)">
+  <span>Row 1</span>
+  <span>Row 2</span>
+  <span>Row 3</span>
+</div>
+
+<!-- @visibility | row -->
+<span class="ui-visible ui-p-1" style="background: var(--ui-color-bg-muted)">Visible</span>
+<span class="ui-invisible ui-p-1" style="background: var(--ui-color-bg-muted)">Invisible (hidden but occupies space)</span>

package/src/utilities/scroll-animation/scroll-animation.docs.html

@@ -0,0 +1,32 @@
+---
+title: Scroll Animation
+type: utility
+id: scroll-animation-utils
+description: Scroll-driven animation utilities for progress indicators and viewport-triggered effects. Wrapped in @supports — no impact on unsupported browsers.
+api: scroll-animation.api.json
+---
+
+<!-- @scroll_progress_indicator -->
+<!-- Fixed bar at the top of the viewport that fills as the user scrolls down. -->
+<div style="position: relative; block-size: 12rem; overflow-y: auto;">
+  <div class="ui-scroll-progress" style="position: absolute;"></div>
+  <div style="block-size: 40rem; padding: var(--ui-space-2);">
+    <p>Scroll down to see the progress bar fill.</p>
+  </div>
+</div>
+
+<!-- @view_fade -->
+<!-- Elements fade in as they enter the viewport. -->
+<div class="ui-view-fade ui-card ui-p-2">I fade in on scroll</div>
+
+<!-- @view_slide_up -->
+<!-- Elements slide up and fade in on viewport entry. -->
+<div class="ui-view-slide-up ui-card ui-p-2">I slide up into view</div>
+
+<!-- @view_slide_start -->
+<!-- Elements slide in from the start edge (left in LTR) on viewport entry. -->
+<div class="ui-view-slide-start ui-card ui-p-2">I slide from the start</div>
+
+<!-- @view_scale -->
+<!-- Elements scale up and fade in on viewport entry. -->
+<div class="ui-view-scale ui-card ui-p-2">I scale into view</div>

package/src/utilities/scroll-snap/scroll-snap.docs.html

@@ -0,0 +1,80 @@
+---
+title: Scroll Snap
+type: utility
+id: scroll-snap-utils
+description: Scroll-snap utilities for carousels, horizontal lists, and snap-to-position scrolling.
+api: scroll-snap.api.json
+---
+
+<!-- @horizontal_snap -->
+<!-- Snap children to start position on horizontal scroll. -->
+<div class="ui-snap-x ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Item 1</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Item 2</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Item 3</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Item 4</div>
+</div>
+
+<!-- @center_snap -->
+<!-- Snap children to center position. -->
+<div class="ui-snap-x ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-center ui-card ui-p-2" style="min-inline-size: 10rem">Center 1</div>
+  <div class="ui-snap-center ui-card ui-p-2" style="min-inline-size: 10rem">Center 2</div>
+  <div class="ui-snap-center ui-card ui-p-2" style="min-inline-size: 10rem">Center 3</div>
+</div>
+
+<!-- @vertical_snap -->
+<!-- Snap children on vertical scroll. -->
+<div class="ui-snap-y" style="max-block-size: 8rem">
+  <div class="ui-snap-start ui-card ui-p-2">Section 1</div>
+  <div class="ui-snap-start ui-card ui-p-2">Section 2</div>
+  <div class="ui-snap-start ui-card ui-p-2">Section 3</div>
+</div>
+
+<!-- @proximity_snap -->
+<!-- Softer snap that only engages when close to a snap point. -->
+<div class="ui-snap-x-proximity ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Proximity 1</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Proximity 2</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">Proximity 3</div>
+</div>
+<div class="ui-snap-y-proximity" style="max-block-size: 8rem">
+  <div class="ui-snap-start ui-card ui-p-2">Section 1</div>
+  <div class="ui-snap-start ui-card ui-p-2">Section 2</div>
+  <div class="ui-snap-start ui-card ui-p-2">Section 3</div>
+</div>
+
+<!-- @end_alignment_and_stop -->
+<!-- Snap children to end position or force stop at every snap point. -->
+<div class="ui-snap-x ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-end ui-card ui-p-2" style="min-inline-size: 10rem">End 1</div>
+  <div class="ui-snap-end ui-card ui-p-2" style="min-inline-size: 10rem">End 2</div>
+  <div class="ui-snap-end ui-card ui-p-2" style="min-inline-size: 10rem">End 3</div>
+</div>
+<div class="ui-snap-x ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-snap-always ui-card ui-p-2" style="min-inline-size: 10rem">Always 1</div>
+  <div class="ui-snap-start ui-snap-always ui-card ui-p-2" style="min-inline-size: 10rem">Always 2</div>
+  <div class="ui-snap-start ui-snap-always ui-card ui-p-2" style="min-inline-size: 10rem">Always 3</div>
+</div>
+
+<!-- @disable_snap -->
+<!-- Remove snap behavior from a container. -->
+<div class="ui-snap-none ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem; overflow-x: auto">
+  <div class="ui-card ui-p-2" style="min-inline-size: 10rem">No snap 1</div>
+  <div class="ui-card ui-p-2" style="min-inline-size: 10rem">No snap 2</div>
+</div>
+
+<!-- @scroll_padding -->
+<!-- Offset snap position for fixed headers or insets. -->
+<div class="ui-snap-x ui-snap-p-1 ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-1</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-1</div>
+</div>
+<div class="ui-snap-x ui-snap-p-2 ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-2</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-2</div>
+</div>
+<div class="ui-snap-x ui-snap-p-4 ui-flex ui-gap-2 ui-p-2" style="max-inline-size: 20rem">
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-4</div>
+  <div class="ui-snap-start ui-card ui-p-2" style="min-inline-size: 10rem">p-4</div>
+</div>

package/src/utilities/spacing/spacing.docs.html

@@ -0,0 +1,29 @@
+---
+title: Spacing
+type: utility
+id: spacing-utils
+description: Margin and padding utilities aligned to 8px grid.
+api: spacing.api.json
+---
+
+<!-- @padding | column -->
+<div class="ui-p-1" style="background: var(--ui-color-bg-muted)">p-1 (8px padding)</div>
+<div class="ui-p-2" style="background: var(--ui-color-bg-muted)">p-2 (16px padding)</div>
+<div class="ui-p-4" style="background: var(--ui-color-bg-muted)">p-4 (32px padding)</div>
+
+<!-- @directional_padding | column -->
+<div class="ui-px-4 ui-py-2" style="background: var(--ui-color-bg-muted)">px-4 py-2 (horizontal 32px, vertical 16px)</div>
+<div class="ui-pt-4 ui-pb-1" style="background: var(--ui-color-bg-muted)">pt-4 pb-1 (top 32px, bottom 8px)</div>
+<div class="ui-ps-4 ui-pe-1" style="background: var(--ui-color-bg-muted)">ps-4 pe-1 (start 32px, end 8px)</div>
+
+<!-- @margin | column -->
+<div class="ui-mb-2" style="background: var(--ui-color-bg-muted)">mb-2 (16px bottom margin)</div>
+<div class="ui-mt-4 ui-mb-2" style="background: var(--ui-color-bg-muted)">mt-4 mb-2 (top 32px, bottom 16px)</div>
+<div class="ui-mx-auto" style="background: var(--ui-color-bg-muted); max-inline-size: var(--ui-row-8)">mx-auto (centered with auto margins)</div>
+
+<!-- @gap -->
+<div class="ui-flex ui-gap-2">
+  <div class="ui-p-2" style="background: var(--ui-color-bg-muted)">Item</div>
+  <div class="ui-p-2" style="background: var(--ui-color-bg-muted)">Item</div>
+  <div class="ui-p-2" style="background: var(--ui-color-bg-muted)">Item</div>
+</div>

package/src/utilities/text/text.docs.html

@@ -0,0 +1,66 @@
+---
+title: Text
+type: utility
+id: text-utils
+description: Typography and text utilities. Font sizes follow a 1.2 modular scale.
+api: text.api.json
+---
+
+<!-- @sizes | column -->
+<!-- Font size utilities with 8px grid-snapped line-heights. -->
+<p class="ui-text-xs">text-xs: 12px / 16px line-height</p>
+<p class="ui-text-sm">text-sm: 14px / 24px line-height</p>
+<p class="ui-text-md">text-md: 16px / 24px line-height</p>
+<p class="ui-text-lg">text-lg: 20px / 32px line-height</p>
+<p class="ui-text-xl">text-xl: 24px / 32px line-height</p>
+<p class="ui-text-2xl">text-2xl: 28px / 32px line-height</p>
+<p class="ui-text-3xl">text-3xl: 32px / 40px line-height</p>
+<p class="ui-text-4xl">text-4xl: 40px / 48px line-height</p>
+
+<!-- @text_roles | column -->
+<!-- Semantic text styles for specific use cases. -->
+<p class="ui-text-lead">Lead: Opening paragraph style (20px / 32px)</p>
+<p class="ui-text-eyebrow">Eyebrow: Small caps label</p>
+<p class="ui-text-caption">Caption: Labels and hints (12px / 16px)</p>
+<p class="ui-text-body-sm">Body small: Secondary text (14px / 24px)</p>
+
+<!-- @weights | column -->
+<p class="ui-font-normal">font-normal (400)</p>
+<p class="ui-font-medium">font-medium (500)</p>
+<p class="ui-font-semibold">font-semibold (600)</p>
+<p class="ui-font-bold">font-bold (700)</p>
+
+<!-- @letter_spacing | column -->
+<p class="ui-text-2xl ui-tracking-display">tracking-display: Tight (-0.02em)</p>
+<p class="ui-tracking-body">tracking-body: Default (0)</p>
+<p class="ui-tracking-caps ui-uppercase">tracking-caps: Wide (+0.08em)</p>
+
+<!-- @line_length | column -->
+<!-- Constrain text width for optimal readability. -->
+<p class="ui-prose-sm">prose-sm: 45ch max-width</p>
+<p class="ui-prose">prose: 65ch max-width (recommended)</p>
+<p class="ui-prose-lg">prose-lg: 75ch max-width</p>
+
+<!-- @colors | column -->
+<p class="ui-text-primary">text-primary</p>
+<p class="ui-text-muted">text-muted</p>
+<p class="ui-text-success">text-success</p>
+<p class="ui-text-warning">text-warning</p>
+<p class="ui-text-danger">text-danger</p>
+
+<!-- @alignment | column -->
+<p class="ui-text-start">text-start (default)</p>
+<p class="ui-text-center">text-center</p>
+<p class="ui-text-end">text-end</p>
+
+<!-- @text_wrap | column -->
+<!-- Control how text wraps across lines. -->
+<p class="ui-text-balance ui-text-2xl ui-font-bold" style="max-inline-size: 20rem">Balanced: distributes text evenly across lines</p>
+<p class="ui-text-pretty" style="max-inline-size: 20rem">Pretty: avoids orphans and widows for cleaner body text paragraphs that wrap naturally</p>
+<p class="ui-text-nowrap">Nowrap: prevents text from wrapping to the next line</p>
+
+<!-- @multi_line_truncation | column -->
+<!-- Clamp text to a specific number of lines with ellipsis. -->
+<p class="ui-truncate-2" style="max-inline-size: 20rem">Truncate to 2 lines: This is a long paragraph that will be clamped after two lines of text. Any overflow content will be hidden and replaced with an ellipsis character.</p>
+<p class="ui-truncate-3" style="max-inline-size: 20rem">Truncate to 3 lines: This is a long paragraph that will be clamped after three lines of text. Any overflow content beyond the third line will be hidden and replaced with an ellipsis character at the end.</p>
+<p class="ui-truncate-4" style="max-inline-size: 20rem">Truncate to 4 lines: This is a long paragraph that will be clamped after four lines. It gives more room for content previews while still maintaining a consistent height. Overflow beyond line four is hidden with ellipsis.</p>