@teseor/css 1.14.1 → 1.14.3

package/src/components/navigation/dropdown-menu/dropdown-menu.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'dropdown-menu.docs.json');
 

package/src/components/navigation/menu/menu.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'menu.docs.json');
 

package/src/components/navigation/nav/nav.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'nav.docs.json');
 

package/src/components/navigation/pagination/pagination.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'pagination.docs.json');
 

package/src/components/navigation/tabs/tabs.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'tabs.docs.json');
 

package/src/components/overlays/dialog/dialog.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'dialog.docs.json');
 

package/src/components/overlays/drawer/drawer.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'drawer.docs.json');
 

package/src/components/overlays/modal/modal.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'modal.docs.json');
 

package/src/components/overlays/overlay/overlay.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'overlay.docs.json');
 

package/src/components/overlays/popover/popover.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'popover.docs.json');
 

package/src/components/overlays/tooltip/tooltip.visual.spec.ts

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'tooltip.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'blockquote.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'code.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'code-block.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'heading.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'kbd.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'link.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'list.docs.json');
 

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

@@ -1,6 +1,10 @@
 import { resolve } from 'node:path';
 import { expect, test } from '@playwright/test';
-import { saveForLostPixel, setupVisualTestFromDocs, validateGridRhythm } from '../../../testing';
+import {
+  saveForLostPixel,
+  setupVisualTestFromDocs,
+  validateGridRhythm,
+} from '../../../../test-utils';
 
 const DOCS_PATH = resolve(__dirname, 'mark.docs.json');
 

package/src/config/{tokens → guides}/accessibility.docs.json

@@ -3,6 +3,7 @@
   "type": "guide",
   "title": "Accessibility",
   "description": "Built-in accessibility features: reduced motion, system theme detection, high contrast, and keyboard focus indicators",
+  "weight": 3,
   "skipValidation": true,
   "sections": [
     {

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

@@ -0,0 +1,106 @@
+{
+  "id": "getting-started",
+  "type": "guide",
+  "title": "Getting Started",
+  "description": "Install, import, and start using the CSS library in your project",
+  "weight": 1,
+  "skipValidation": true,
+  "sections": [
+    {
+      "title": "Installation",
+      "description": "Install the package from npm.",
+      "examples": [
+        {
+          "title": "npm / pnpm / yarn",
+          "code": "npm install @teseor/css\n# or\npnpm add @teseor/css\n# or\nyarn add @teseor/css"
+        }
+      ]
+    },
+    {
+      "title": "Import",
+      "description": "Import the compiled CSS in your app entry point.",
+      "examples": [
+        {
+          "title": "JS / TS entry",
+          "code": "import '@teseor/css';\n// or\nimport '@teseor/css/dist/index.css';"
+        },
+        {
+          "title": "HTML link",
+          "code": "<link rel=\"stylesheet\" href=\"node_modules/@teseor/css/dist/index.css\">"
+        }
+      ]
+    },
+    {
+      "title": "Root Class",
+      "description": "Add the .ui-root class to set baseline typography and colors.",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-root",
+              "children": [{ "tag": "p", "text": "Text inherits font, size, color from .ui-root" }]
+            }
+          ],
+          "code": "<html class=\"ui-root\">\n  <body>\n    <!-- All children inherit base styles -->\n  </body>\n</html>"
+        }
+      ]
+    },
+    {
+      "title": "First Component",
+      "description": "Use any component by adding its class. No JS required.",
+      "examples": [
+        {
+          "title": "Button",
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-row ui-row--sm",
+              "children": [
+                { "tag": "button", "class": "ui-button", "text": "Primary" },
+                { "tag": "button", "class": "ui-button ui-button--secondary", "text": "Secondary" },
+                { "tag": "button", "class": "ui-button ui-button--danger", "text": "Danger" }
+              ]
+            }
+          ],
+          "code": "<button class=\"ui-button\">Primary</button>\n<button class=\"ui-button ui-button--secondary\">Secondary</button>\n<button class=\"ui-button ui-button--danger\">Danger</button>"
+        },
+        {
+          "title": "Card",
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-card",
+              "children": [
+                { "tag": "h3", "class": "ui-heading ui-heading--4", "text": "Card Title" },
+                {
+                  "tag": "p",
+                  "text": "Cards use semantic tokens for padding, border, and background."
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-card\">\n  <h3 class=\"ui-heading ui-heading--4\">Card Title</h3>\n  <p>Content goes here.</p>\n</div>"
+        }
+      ]
+    },
+    {
+      "title": "Customize",
+      "description": "Override design tokens with CSS custom properties. No build step required.",
+      "examples": [
+        {
+          "title": "Change brand color",
+          "items": [
+            {
+              "tag": "div",
+              "class": "theme-demo",
+              "style": { "--ui-hue-primary": "270" },
+              "children": [{ "tag": "button", "class": "ui-button", "text": "Purple brand" }]
+            }
+          ],
+          "code": ":root {\n  --ui-hue-primary: 270; /* purple */\n}"
+        }
+      ]
+    }
+  ]
+}

package/src/config/{tokens → guides}/theming.docs.json

@@ -3,6 +3,7 @@
   "type": "guide",
   "title": "Theming",
   "description": "Customize the design system with CSS custom properties",
+  "weight": 2,
   "skipValidation": true,
   "sections": [
     {

package/src/config/tokens/_variables.scss

@@ -3,9 +3,12 @@
 // SCSS Variables - Source of truth for fallback values
 // These are the computed values that CSS custom properties resolve to.
 // Import this file in components that need standalone fallbacks.
+// Section order mirrors config/tokens/index.scss import order.
 
-// Grid - all derived from $unit
-$unit: 0.5rem; // 8px
+// ==========================================================================
+// 1. Grid — all derived from $unit
+// ==========================================================================
+$unit: 0.5rem; // 8px (matches --ui-unit: 8px)
 $row: $unit * 2; // 16px
 $row-1: $row;
 $row-2: $row * 2; // 32px
@@ -14,7 +17,41 @@ $row-4: $row * 4;
 $row-5: $row * 5;
 $row-6: $row * 6;
 
-// Spacing - derived from $unit
+// ==========================================================================
+// 2. Colors — OKLCH for perceptual uniformity
+// ==========================================================================
+
+// Theming hue — used in HSL fallbacks for shadows, debug overlays
+$hue-primary: 220;
+
+// Base palette
+$color-primary: oklch(55% 0.22 250);
+$color-success: oklch(60% 0.18 145);
+$color-warning: oklch(75% 0.18 70);
+$color-danger: oklch(60% 0.22 25);
+$color-neutral: oklch(50% 0.02 250);
+
+// Neutral scale — HSL approximation of color-mix(in oklch, ...) results.
+// CSS tokens use oklch color-mix(); these HSL values are static SCSS
+// fallbacks for when custom properties are unavailable.
+$color-neutral-50: hsl(220 10% 98%);
+$color-neutral-100: hsl(220 10% 96%);
+$color-neutral-200: hsl(220 10% 90%);
+$color-neutral-300: hsl(220 10% 80%);
+$color-neutral-400: hsl(220 10% 60%);
+$color-neutral-500: hsl(220 10% 45%);
+$color-neutral-600: hsl(220 10% 35%);
+$color-neutral-700: hsl(220 10% 25%);
+$color-neutral-800: hsl(220 10% 15%);
+$color-neutral-900: hsl(220 10% 10%);
+
+// Primary shades (CSS uses color-mix)
+$color-primary-light: oklch(75% 0.15 250);
+$color-primary-dark: oklch(40% 0.18 250);
+
+// ==========================================================================
+// 3. Spacing — derived from $unit
+// ==========================================================================
 $space-px: $unit * 0.125; // 1px - hairline
 $space-quarter: $unit * 0.25; // 2px - micro spacing
 $space-0: $unit * 0.5; // 4px
@@ -39,11 +76,15 @@ $sizes: (
   @return map.get($sizes, $name);
 }
 
-// Typography - Font families (system stack, consumers override via CSS tokens)
+// ==========================================================================
+// 4. Typography
+// ==========================================================================
+
+// Font families (system stack, consumers override via CSS tokens)
 $font-sans: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", roboto, "Helvetica Neue", arial, sans-serif;
 $font-mono: ui-monospace, sfmono-regular, "SF Mono", menlo, consolas, "Liberation Mono", monospace;
 
-// Typography - Font sizes (1.2 modular scale)
+// Font sizes (1.2 modular scale)
 $font-size-xs: 0.75rem; // 12px
 $font-size-sm: 0.875rem; // 14px
 $font-size-md: 1rem; // 16px (base)
@@ -53,13 +94,13 @@ $font-size-2xl: 1.75rem; // 28px
 $font-size-3xl: 2rem; // 32px
 $font-size-4xl: 2.5rem; // 40px
 
-// Typography - Tight line heights (for compact UI elements)
+// Tight line heights (compact UI elements)
 $leading-tight-xs: $row;
 $leading-tight-sm: $row;
 $leading-tight-md: $unit * 3;
 $leading-tight-lg: $unit * 3;
 
-// Typography - Line heights (for body text)
+// Normal line heights (body text)
 $leading-xs: $row;
 $leading-sm: $unit * 3;
 $leading-md: $unit * 3;
@@ -69,54 +110,68 @@ $leading-2xl: $row-2;
 $leading-3xl: $unit * 5;
 $leading-4xl: $unit * 6;
 
-// Typography - Font weights
+// Font weights
 $weight-normal: 400;
 $weight-medium: 500;
 $weight-semibold: 600;
 $weight-bold: 700;
 
-// Typography - Letter spacing
+// Letter spacing
 $tracking-display: -0.02em;
 $tracking-body: 0;
 $tracking-caps: 0.08em;
 
-
-// Radius - derived from $unit (0.5rem = 8px)
+// ==========================================================================
+// 5. Radius — derived from $unit
+// ==========================================================================
 $radius-sm: $unit * 0.5; // 4px
 $radius-md: $unit; // 8px
 $radius-lg: $unit * 2; // 16px
 $radius-full: 9999px;
 
-// Borders - derived from $unit (0.5rem = 8px)
+// ==========================================================================
+// 6. Borders — derived from $unit
+// ==========================================================================
 $border-width-sm: $unit * 0.125; // 1px
 $border-width-md: $unit * 0.25; // 2px
 $border-width-lg: $unit * 0.5; // 4px
 
-// Base colors - OKLCH for perceptual uniformity
-// These are fallback values; CSS custom properties take precedence
-$color-primary: oklch(55% 0.22 250);
-$color-success: oklch(60% 0.18 145);
-$color-warning: oklch(75% 0.18 70);
-$color-danger: oklch(60% 0.22 25);
-$color-neutral: oklch(50% 0.02 250);
+// ==========================================================================
+// 7. Shadows — static hue fallback
+// ==========================================================================
+$shadow-sm: 0 1px 2px hsl(220 10% 20% / 0.05);
+$shadow-md: 0 4px 6px hsl(220 10% 20% / 0.1);
+$shadow-lg: 0 10px 15px hsl(220 10% 20% / 0.15);
 
-// Neutral scale - approximated from color-mix in oklch
-$color-neutral-50: hsl(220 10% 98%);
-$color-neutral-100: hsl(220 10% 96%);
-$color-neutral-200: hsl(220 10% 90%);
-$color-neutral-300: hsl(220 10% 80%);
-$color-neutral-400: hsl(220 10% 60%);
-$color-neutral-500: hsl(220 10% 45%);
-$color-neutral-600: hsl(220 10% 35%);
-$color-neutral-700: hsl(220 10% 25%);
-$color-neutral-800: hsl(220 10% 15%);
-$color-neutral-900: hsl(220 10% 10%);
+// ==========================================================================
+// 8. Z-index scale
+// ==========================================================================
+$z-base: 0;
+$z-sticky: 100;
+$z-dropdown: 200;
+$z-overlay: 300;
+$z-modal: 400;
+$z-popover: 500;
+$z-tooltip: 600;
+$z-toast: 700;
+$z-drawer: 800;
+$z-debug: 9999;
 
-// Primary shades - fallbacks (CSS uses color-mix)
-$color-primary-light: oklch(75% 0.15 250);
-$color-primary-dark: oklch(40% 0.18 250);
+// ==========================================================================
+// 9. Motion
+// ==========================================================================
+$duration-instant: 50ms;
+$duration-fast: 100ms;
+$duration-base: 150ms;
+$duration-normal: 200ms;
+$duration-slow: 250ms;
+$duration-slower: 400ms;
 
-// Semantic colors (light theme defaults)
+$ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+
+// ==========================================================================
+// 10. Semantic colors (light theme defaults)
+// ==========================================================================
 $color-text: $color-neutral-900;
 $color-text-muted: $color-neutral-500;
 $color-text-inverse: $color-neutral-50;
@@ -133,37 +188,6 @@ $color-interactive-hover: $color-primary-dark;
 
 $color-focus: $color-primary-light;
 
-// Motion - duration scale (matches config/tokens/motion)
-$duration-instant: 50ms;
-$duration-fast: 100ms;
-$duration-base: 150ms;
-$duration-normal: 200ms;
-$duration-slow: 250ms;
-$duration-slower: 400ms;
-
-// Motion - easing (matches config/tokens/motion)
-$ease-default: cubic-bezier(0.4, 0, 0.2, 1);
-
-// Shadows (matches config/tokens/shadows, static hue fallback)
-$shadow-sm: 0 1px 2px hsl(220 10% 20% / 0.05);
-$shadow-md: 0 4px 6px hsl(220 10% 20% / 0.1);
-$shadow-lg: 0 10px 15px hsl(220 10% 20% / 0.15);
-
-// Z-index scale (matches config/tokens/zindex)
-$z-base: 0;
-$z-sticky: 100;
-$z-dropdown: 200;
-$z-overlay: 300;
-$z-modal: 400;
-$z-popover: 500;
-$z-tooltip: 600;
-$z-toast: 700;
-$z-drawer: 800;
-$z-debug: 9999;
-
-// Theming
-$hue-primary: 220;
-
 // State opacity
 $opacity-disabled: 0.5;
 $opacity-loading: 0.7;
@@ -174,17 +198,32 @@ $overlay-bg-light: rgb(255 255 255 / 0.7);
 $overlay-bg-blur: rgb(0 0 0 / 0.3);
 $overlay-bg-subtle: rgb(0 0 0 / 0.1);
 
-// Component defaults - icons
+// ==========================================================================
+// 11. Semantic spacing
+// ==========================================================================
+$spacing-xs: $space-1;
+$spacing-sm: $space-2;
+$spacing-md: $space-4;
+$spacing-lg: $space-6;
+$spacing-xl: $space-8;
+$spacing-gutter: $space-4;
+$spacing-section: $space-8;
+
+// ==========================================================================
+// 12. Component defaults
+// ==========================================================================
+
+// Icons
 $icon-stroke: 2;
 $icon-stroke-thin: 1;
 $icon-stroke-thick: 2.5;
 
-// Component defaults - feedback
+// Feedback
 $spinner-duration: 750ms;
 $progress-circle-stroke-width: 8;
 $skeleton-shimmer: rgb(255 255 255 / 0.5);
 
-// Component defaults - misc
+// Misc
 $slider-thumb-shadow: 0 1px 3px rgb(0 0 0 / 0.2);
 $toast-viewport-max-width: 420px;
 $spacer-size: 1;