@teseor/css 1.14.2 → 1.15.0

package/src/components/typography/code-block/code-block.docs.html

@@ -0,0 +1,87 @@
+---
+title: Code Block
+type: component
+id: code-block
+description: Multi-line code display with monospace font, horizontal scroll, and optional line numbers.
+api: ./code-block.api.json
+mergeInto: code
+---
+
+<!-- @default -->
+<pre class="ui-code-block">
+  <code class="ui-code-block__code">.button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ui-space-1);
+}</code>
+</pre>
+
+<!-- @horizontal_overflow -->
+<pre class="ui-code-block">
+  <code class="ui-code-block__code">export function calculateGridRhythm(element: HTMLElement, unit: number): { violations: string[]; totalHeight: number } {
+  const computed = getComputedStyle(element);
+  return { violations: [], totalHeight: parseFloat(computed.height) };
+}</code>
+</pre>
+
+<!-- @compact -->
+<pre class="ui-code-block ui-code-block--compact">
+  <code class="ui-code-block__code">npm install @teseor/css
+import "@teseor/css/dist/index.css";</code>
+</pre>
+
+<!-- @line_numbers -->
+<pre class="ui-code-block ui-code-block--line-numbers">
+  <code class="ui-code-block__code">
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>@layer components {</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>  .card {</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>    padding: var(--_padding);</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>    background: var(--_bg);</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>    border-radius: var(--_radius);</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>  }</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>}</span>
+    </span>
+  </code>
+</pre>
+
+<!-- @inline_code -->
+<!-- Use the related ui-code class for inline snippets. -->
+<p>
+  <span>Use </span>
+  <code class="ui-code">var(--ui-space-2)</code>
+  <span> for consistent spacing.</span>
+</p>
+
+<!-- @compact_with_line_numbers -->
+<pre class="ui-code-block ui-code-block--compact ui-code-block--line-numbers">
+  <code class="ui-code-block__code">
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>const name = "world";</span>
+    </span>
+    <span class="ui-code-block__line">
+      <span class="ui-code-block__line-number"></span>
+      <span>console.log(`Hello, ${name}`);</span>
+    </span>
+  </code>
+</pre>

package/src/components/typography/code-block/code-block.visual.spec.ts

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

package/src/components/typography/heading/heading.docs.html

@@ -0,0 +1,26 @@
+---
+title: Heading
+type: component
+id: heading
+description: Semantic headings with visual size control. Use semantic level (h1-h6) for structure, size modifier for visual styling.
+api: ./heading.api.json
+---
+
+<!-- @sizes | column -->
+<h1 class="ui-heading ui-heading--4xl">Heading 4xl</h1>
+<h2 class="ui-heading ui-heading--3xl">Heading 3xl</h2>
+<h3 class="ui-heading ui-heading--2xl">Heading 2xl</h3>
+<h4 class="ui-heading ui-heading--xl">Heading xl</h4>
+<h5 class="ui-heading ui-heading--lg">Heading lg</h5>
+<h6 class="ui-heading ui-heading--md">Heading md</h6>
+<p class="ui-heading ui-heading--sm">Heading sm</p>
+
+<!-- @decoupled_sizing | column -->
+<!-- Use any size with any semantic level. -->
+<h2 class="ui-heading ui-heading--3xl">h2 styled as 3xl</h2>
+<h1 class="ui-heading ui-heading--lg">h1 styled as lg</h1>
+
+<!-- @with_text_utilities | column -->
+<!-- Combine with text utilities for color and other styles. -->
+<h2 class="ui-heading ui-heading--2xl ui-text-muted">Muted heading</h2>
+<h2 class="ui-heading ui-heading--2xl ui-text-primary">Primary heading</h2>

package/src/components/typography/heading/heading.visual.spec.ts

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

package/src/components/typography/kbd/kbd.docs.html

@@ -0,0 +1,16 @@
+---
+title: Kbd
+type: component
+description: Keyboard shortcut display with monospace font and key-cap styling.
+api: ./kbd.api.json
+---
+
+<!-- @default -->
+<p>{{ t('press', 'Press') }} <kbd class="ui-kbd">Ctrl</kbd> + <kbd class="ui-kbd">S</kbd> {{ t('to_save', 'to save') }}</p>
+
+<!-- @variations | row -->
+<kbd class="ui-kbd">Esc</kbd>
+<kbd class="ui-kbd">Enter</kbd>
+<kbd class="ui-kbd">Tab</kbd>
+<kbd class="ui-kbd">Shift</kbd>
+<kbd class="ui-kbd">Space</kbd>

package/src/components/typography/kbd/kbd.visual.spec.ts

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

package/src/components/typography/link/link.docs.html

@@ -0,0 +1,33 @@
+---
+title: Link
+type: component
+id: link
+description: Styled anchor element for text links with consistent hover and focus states.
+api: ./link.api.json
+---
+
+<!-- @default -->
+<a class="ui-link" href="#">Default link</a>
+
+<!-- @muted_variant -->
+<!-- For secondary or less prominent links -->
+<a class="ui-link ui-link--muted" href="#">Muted link</a>
+
+<!-- @subtle_variant -->
+<!-- No underline by default, shows on hover -->
+<a class="ui-link ui-link--subtle" href="#">Subtle link</a>
+
+<!-- @external_link -->
+<!-- Adds arrow indicator for external links -->
+<a class="ui-link ui-link--external" href="#">External link</a>
+
+<!-- @disabled -->
+<a class="ui-link ui-link--disabled" href="#" aria-disabled="true">Disabled link</a>
+
+<!-- @in_context -->
+<!-- Links inherit text size from context -->
+<p style="font-size: var(--ui-size-sm);">
+Read our 
+  <a class="ui-link" href="#">privacy policy</a>
+ for more information.
+</p>

package/src/components/typography/link/link.visual.spec.ts

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

package/src/components/typography/list/list.docs.html

@@ -0,0 +1,79 @@
+---
+title: List
+type: component
+id: list
+description: Ordered and unordered lists with spacing control, inline layout, and marker customization.
+api: ./list.api.json
+---
+
+<!-- @default -->
+<!-- Unordered list with default bullet markers. -->
+<ul class="ui-list">
+  <li class="ui-list__item">First item in the list</li>
+  <li class="ui-list__item">Second item in the list</li>
+  <li class="ui-list__item">Third item in the list</li>
+</ul>
+
+<!-- @ordered -->
+<!-- Use on ol for numbered markers. -->
+<ol class="ui-list">
+  <li>Create the branch</li>
+  <li>Implement the feature</li>
+  <li>Open a pull request</li>
+  <li>Merge after review</li>
+</ol>
+
+<!-- @unstyled -->
+<!-- Removes markers and indent for nav or custom lists. -->
+<ul class="ui-list ui-list--unstyled">
+  <li>No bullet markers</li>
+  <li>No inline padding</li>
+  <li>Clean vertical stack</li>
+</ul>
+
+<!-- @inline -->
+<!-- Horizontal flow with wrapping. Markers removed. -->
+<ul class="ui-list ui-list--inline">
+  <li>HTML</li>
+  <li>CSS</li>
+  <li>JavaScript</li>
+  <li>TypeScript</li>
+  <li>React</li>
+</ul>
+
+<!-- @spacing -->
+<!-- Control gap between items with compact or loose variants. -->
+<div class="ui-column" style="gap: var(--ui-space-2)">
+  <p>Compact</p>
+  <ul class="ui-list ui-list--compact">
+    <li>Tight spacing</li>
+    <li>No gap between items</li>
+    <li>Dense content</li>
+  </ul>
+  <p>Default</p>
+  <ul class="ui-list">
+    <li>Standard spacing</li>
+    <li>One grid unit gap</li>
+    <li>Balanced readability</li>
+  </ul>
+  <p>Loose</p>
+  <ul class="ui-list ui-list--loose">
+    <li>Extra breathing room</li>
+    <li>Two grid units gap</li>
+    <li>Prominent separation</li>
+  </ul>
+</div>
+
+<!-- @nested -->
+<!-- Lists inside lists inherit spacing and show sub-level markers. -->
+<ul class="ui-list">
+  <li>Top-level item</li>
+  <li>
+    <span>Parent with children</span>
+    <ul class="ui-list">
+      <li>Nested child</li>
+      <li>Another nested child</li>
+    </ul>
+  </li>
+  <li>Back to top level</li>
+</ul>

package/src/components/typography/list/list.visual.spec.ts

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

package/src/components/typography/mark/mark.docs.html

@@ -0,0 +1,12 @@
+---
+title: Mark
+type: component
+description: Highlighted text for search results, emphasis, or annotations.
+api: ./mark.api.json
+---
+
+<!-- @default -->
+<p>{{ t('the', 'The') }} <mark class="ui-mark">{{ t('highlighted', 'highlighted') }}</mark> {{ t('text_stands_out', 'text stands out from surrounding content.') }}</p>
+
+<!-- @search_results -->
+<p>{{ t('results_for', 'Results for') }} <mark class="ui-mark">{{ t('design_tokens', 'design tokens') }}</mark>: CSS custom properties that store <mark class="ui-mark">{{ t('design', 'design') }}</mark> decisions as reusable <mark class="ui-mark">{{ t('tokens', 'tokens') }}</mark>.</p>

package/src/components/typography/mark/mark.visual.spec.ts

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

package/src/config/guides/accessibility.docs.html

@@ -0,0 +1,108 @@
+---
+title: Accessibility
+type: guide
+id: accessibility
+description: Built-in accessibility features: reduced motion, system theme detection, high contrast, and keyboard focus indicators
+skipValidation: true
+weight: 3
+---
+
+<!-- @reduced_motion -->
+<!-- All animations and transitions respect prefers-reduced-motion. Duration tokens are set to 0ms, and component animations are disabled with animation: none. -->
+// Motion tokens (config/tokens/motion)
+:root {
+  --ui-duration-fast: 100ms;
+  --ui-duration-base: 150ms;
+  --ui-duration-slow: 250ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --ui-duration-fast: 0ms;
+    --ui-duration-base: 0ms;
+    --ui-duration-slow: 0ms;
+  }
+}
+// Example: spinner
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+<!-- @system_theme_detection -->
+<!-- Dark mode activates automatically when the OS is set to dark and no explicit data-theme attribute is present. Set data-theme to override. -->
+<div class="ui-card">
+  <p>Follows system preference when no data-theme is set</p>
+</div>
+<div class="ui-card" data-theme="dark">
+  <p>Forced dark regardless of system preference</p>
+</div>
+// Explicit toggle (highest priority)
+[data-theme="dark"] {
+  --ui-color-bg: var(--ui-color-neutral-900);
+  ...
+}
+
+// Auto-detect (only when no data-theme is set)
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --ui-color-bg: var(--ui-color-neutral-900);
+    ...
+  }
+}
+
+<!-- @focus_indicators -->
+<!-- All interactive elements use :focus-visible for keyboard-only focus rings. Mouse clicks do not show focus outlines. -->
+<div class="ui-row ui-row--sm">
+  <button class="ui-button ui-button--focus">Button</button>
+  <input class="ui-input ui-input--focus" placeholder="Input"></input>
+  <select class="ui-select ui-select--focus">
+    <option>Select</option>
+  </select>
+</div>
+
+<!-- @contrast_preference -->
+<!-- Adapts border visibility, muted text, and subtle backgrounds when users request more or less contrast via OS settings. -->
+@media (prefers-contrast: more) {
+  :root {
+    --ui-color-border: var(--ui-color-neutral-400);
+    --ui-color-border-strong: var(--ui-color-neutral-600);
+    --ui-color-text-muted: var(--ui-color-neutral-600);
+    --ui-color-bg-subtle: var(--ui-color-neutral-200);
+  }
+}
+@media (prefers-contrast: less) {
+  :root {
+    --ui-color-border: var(--ui-color-neutral-150);
+    --ui-color-border-strong: var(--ui-color-neutral-200);
+  }
+}
+// Tokens affected by prefers-contrast:
+// --ui-color-border (default: neutral-200 -> more: neutral-400)
+// --ui-color-border-strong (default: neutral-300 -> more: neutral-600)
+// --ui-color-text-muted (default: neutral-500 -> more: neutral-600)
+// --ui-color-bg-subtle (default: neutral-100 -> more: neutral-200)
+
+<!-- @forced_colors_high_contrast -->
+<!-- Windows High Contrast Mode support. Focus rings use transparent outlines that become visible in forced-colors mode, and the focus color maps to the system Highlight color. -->
+// Normal mode: box-shadow visible, outline transparent
+.input:focus-visible {
+  outline: var(--ui-border-width-md) solid transparent;
+  outline-offset: var(--ui-border-width-sm);
+  box-shadow: 0 0 0 var(--ui-border-width-md)
+    var(--ui-color-focus);
+}
+
+// Forced colors: browser removes box-shadow,
+// transparent outline becomes system-colored
+@media (forced-colors: active) {
+  :root {
+    --ui-color-focus: Highlight;
+  }
+}
+// Components with forced-colors support:
+// Forms: input, select, checkbox, radio, slider
+// Actions: button, close-button
+// Navigation: tabs, breadcrumb, pagination
+// Overlays: modal, drawer, dialog

package/src/config/guides/getting-started.docs.html

@@ -0,0 +1,47 @@
+---
+title: Getting Started
+type: guide
+id: getting-started
+description: Install, import, and start using the CSS library in your project
+skipValidation: true
+weight: 1
+---
+
+<!-- @installation -->
+<!-- Install the package from npm. -->
+npm install @teseor/css
+# or
+pnpm add @teseor/css
+# or
+yarn add @teseor/css
+
+<!-- @import -->
+<!-- Import the compiled CSS in your app entry point. -->
+import '@teseor/css';
+// or
+import '@teseor/css/dist/index.css';
+<link rel="stylesheet" href="node_modules/@teseor/css/dist/index.css">
+
+<!-- @root_class -->
+<!-- Add the .ui-root class to set baseline typography and colors. -->
+<div class="ui-root">
+  <p>Text inherits font, size, color from .ui-root</p>
+</div>
+
+<!-- @first_component -->
+<!-- Use any component by adding its class. No JS required. -->
+<div class="ui-row ui-row--sm">
+  <button class="ui-button">Primary</button>
+  <button class="ui-button ui-button--secondary">Secondary</button>
+  <button class="ui-button ui-button--danger">Danger</button>
+</div>
+<div class="ui-card">
+  <h3 class="ui-heading ui-heading--4">Card Title</h3>
+  <p>Cards use semantic tokens for padding, border, and background.</p>
+</div>
+
+<!-- @customize -->
+<!-- Override design tokens with CSS custom properties. No build step required. -->
+<div class="theme-demo" style="--ui-hue-primary: 270">
+  <button class="ui-button">Purple brand</button>
+</div>

package/src/config/guides/theming.docs.html

@@ -0,0 +1,71 @@
+---
+title: Theming
+type: guide
+id: theming
+description: Customize the design system with CSS custom properties
+skipValidation: true
+weight: 2
+---
+
+<!-- @brand_colors -->
+<!-- Change the entire color palette by adjusting hue values -->
+<div class="theme-demo">
+  <button class="ui-button">Primary</button>
+  <button class="ui-button ui-button--secondary">Secondary</button>
+  <button class="ui-button ui-button--danger">Danger</button>
+</div>
+<div class="theme-demo theme-purple">
+  <button class="ui-button">Primary</button>
+  <button class="ui-button ui-button--secondary">Secondary</button>
+  <button class="ui-button ui-button--danger">Danger</button>
+</div>
+<div class="theme-demo theme-teal">
+  <button class="ui-button">Primary</button>
+  <button class="ui-button ui-button--secondary">Secondary</button>
+  <button class="ui-button ui-button--danger">Danger</button>
+</div>
+<div class="theme-demo theme-orange">
+  <button class="ui-button">Primary</button>
+  <button class="ui-button ui-button--secondary">Secondary</button>
+  <button class="ui-button ui-button--danger">Danger</button>
+</div>
+
+<!-- @dark_mode -->
+<!-- Dark mode uses the CSS light-dark() function. Tokens resolve automatically based on color-scheme. Override with data-theme attribute. -->
+<div class="theme-demo">
+  <div class="ui-card">
+    <p>Follows OS color scheme</p>
+  </div>
+</div>
+<div class="theme-demo" data-theme="light">
+  <div class="ui-card">
+    <p>Always light</p>
+  </div>
+</div>
+<div class="theme-demo" data-theme="dark">
+  <div class="ui-card">
+    <p>Always dark</p>
+  </div>
+</div>
+
+<!-- @component_overrides -->
+<!-- Override specific component tokens -->
+<div class="theme-demo custom-buttons">
+  <button class="ui-button ui-button--sm">Small</button>
+  <button class="ui-button">Default</button>
+  <button class="ui-button ui-button--lg">Large</button>
+</div>
+<div class="theme-demo custom-cards">
+  <div class="ui-card">
+    <p>Card with custom padding</p>
+  </div>
+</div>
+
+<!-- @full_theme_example -->
+<!-- Complete theme customization -->
+<div class="theme-demo theme-corporate">
+  <button class="ui-button">Action</button>
+  <div class="ui-card">
+    <p>Corporate theme with teal accent and sharp corners</p>
+  </div>
+</div>