@teseor/css 1.1.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teseor/css",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "CSS library - reset, primitives, components, utilities",
   "license": "MIT",
   "author": "letanure",

package/src/00-config/tokens/_variables.scss

@@ -1,3 +1,5 @@
+@use 'sass:map';
+
 // 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.
@@ -23,6 +25,20 @@ $space-4: $unit * 4;
 $space-6: $unit * 6;
 $space-8: $unit * 8;
 
+// T-shirt sizes map for looping
+$sizes: (
+  xs: $unit,        // 8px
+  sm: $unit * 1.5,  // 12px
+  md: $unit * 2,    // 16px
+  lg: $unit * 2.5,  // 20px
+  xl: $unit * 3     // 24px
+);
+
+// Helper function to get size value
+@function size($name) {
+  @return map.get($sizes, $name);
+}
+
 // Typography - Font families
 $font-sans: "Noto Sans", system-ui, -apple-system, sans-serif;
 $font-mono: "Noto Sans Mono", ui-monospace, "Cascadia Code", monospace;
@@ -76,31 +92,29 @@ $border-width-sm: $unit * 0.125; // 1px
 $border-width-md: $unit * 0.25; // 2px
 $border-width-lg: $unit * 0.5; // 4px
 
-// Color primitives
-$hue-primary: 220;
-$hue-success: 142;
-$hue-warning: 38;
-$hue-danger: 0;
-
-$color-neutral-50: hsl($hue-primary 10% 98%);
-$color-neutral-100: hsl($hue-primary 10% 96%);
-$color-neutral-200: hsl($hue-primary 10% 90%);
-$color-neutral-300: hsl($hue-primary 10% 80%);
-$color-neutral-400: hsl($hue-primary 10% 60%);
-$color-neutral-500: hsl($hue-primary 10% 45%);
-$color-neutral-600: hsl($hue-primary 10% 35%);
-$color-neutral-700: hsl($hue-primary 10% 25%);
-$color-neutral-800: hsl($hue-primary 10% 15%);
-$color-neutral-900: hsl($hue-primary 10% 10%);
-
-$color-primary-light: hsl($hue-primary 85% 65%);
-$color-primary: hsl($hue-primary 85% 50%);
-$color-primary-dark: hsl($hue-primary 85% 40%);
-
-$color-success: hsl($hue-success 70% 45%);
-$color-warning: hsl($hue-warning 90% 50%);
-$color-danger: hsl($hue-danger 70% 50%);
-$color-danger-dark: hsl($hue-danger 70% 40%);
+// 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);
+
+// 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%);
+
+// Primary shades - fallbacks (CSS uses color-mix)
+$color-primary-light: oklch(75% 0.15 250);
+$color-primary-dark: oklch(40% 0.18 250);
 
 // Semantic colors (light theme defaults)
 $color-text: $color-neutral-900;

package/src/00-config/tokens/colors/index.scss

@@ -1,25 +1,26 @@
 :root {
-  --ui-hue-primary: 220;
-  --ui-hue-success: 142;
-  --ui-hue-warning: 38;
-  --ui-hue-danger: 0;
+  // Base colors - override these to customize the design system
+  --ui-color-primary: oklch(55% 0.22 250);
+  --ui-color-success: oklch(60% 0.18 145);
+  --ui-color-warning: oklch(75% 0.18 70);
+  --ui-color-danger: oklch(60% 0.22 25);
+  --ui-color-neutral: oklch(50% 0.02 250);
 
-  --ui-color-neutral-50: hsl(var(--ui-hue-primary) 10% 98%);
-  --ui-color-neutral-100: hsl(var(--ui-hue-primary) 10% 96%);
-  --ui-color-neutral-200: hsl(var(--ui-hue-primary) 10% 90%);
-  --ui-color-neutral-300: hsl(var(--ui-hue-primary) 10% 80%);
-  --ui-color-neutral-400: hsl(var(--ui-hue-primary) 10% 60%);
-  --ui-color-neutral-500: hsl(var(--ui-hue-primary) 10% 45%);
-  --ui-color-neutral-600: hsl(var(--ui-hue-primary) 10% 35%);
-  --ui-color-neutral-700: hsl(var(--ui-hue-primary) 10% 25%);
-  --ui-color-neutral-800: hsl(var(--ui-hue-primary) 10% 15%);
-  --ui-color-neutral-900: hsl(var(--ui-hue-primary) 10% 10%);
+  // Primary shades - auto-generated via color-mix
+  --ui-color-primary-light: color-mix(in oklch, var(--ui-color-primary) 50%, white);
+  --ui-color-primary-dark: color-mix(in oklch, var(--ui-color-primary) 75%, black);
+  --ui-color-primary-subtle: color-mix(in oklch, var(--ui-color-primary) 12%, white);
+  --ui-color-primary-hover: color-mix(in oklch, var(--ui-color-primary) 85%, black);
 
-  --ui-color-primary-light: hsl(var(--ui-hue-primary) 85% 65%);
-  --ui-color-primary: hsl(var(--ui-hue-primary) 85% 50%);
-  --ui-color-primary-dark: hsl(var(--ui-hue-primary) 85% 40%);
-
-  --ui-color-success: hsl(var(--ui-hue-success) 70% 45%);
-  --ui-color-warning: hsl(var(--ui-hue-warning) 90% 50%);
-  --ui-color-danger: hsl(var(--ui-hue-danger) 70% 50%);
+  // Neutral scale - auto-generated via color-mix
+  --ui-color-neutral-50: color-mix(in oklch, var(--ui-color-neutral) 3%, white);
+  --ui-color-neutral-100: color-mix(in oklch, var(--ui-color-neutral) 6%, white);
+  --ui-color-neutral-200: color-mix(in oklch, var(--ui-color-neutral) 12%, white);
+  --ui-color-neutral-300: color-mix(in oklch, var(--ui-color-neutral) 25%, white);
+  --ui-color-neutral-400: color-mix(in oklch, var(--ui-color-neutral) 50%, white);
+  --ui-color-neutral-500: var(--ui-color-neutral);
+  --ui-color-neutral-600: color-mix(in oklch, var(--ui-color-neutral) 85%, black);
+  --ui-color-neutral-700: color-mix(in oklch, var(--ui-color-neutral) 70%, black);
+  --ui-color-neutral-800: color-mix(in oklch, var(--ui-color-neutral) 50%, black);
+  --ui-color-neutral-900: color-mix(in oklch, var(--ui-color-neutral) 35%, black);
 }

package/src/00-config/tokens/shadows/index.scss

@@ -1,5 +1,5 @@
 :root {
-  --shadow-sm: 0 1px 2px hsl(var(--ui-hue-primary) 10% 20% / 0.05);
-  --shadow-md: 0 4px 6px hsl(var(--ui-hue-primary) 10% 20% / 0.1);
-  --shadow-lg: 0 10px 15px hsl(var(--ui-hue-primary) 10% 20% / 0.15);
+  --shadow-sm: 0 1px 2px hsl(var(--ui-hue-primary, 220) 10% 20% / 0.05);
+  --shadow-md: 0 4px 6px hsl(var(--ui-hue-primary, 220) 10% 20% / 0.1);
+  --shadow-lg: 0 10px 15px hsl(var(--ui-hue-primary, 220) 10% 20% / 0.15);
 }

package/src/03-layout/cluster/cluster.visual.spec.ts

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path';
+import { expect, test } from '@playwright/test';
+import { saveForLostPixel, setupVisualTestFromDocs } from '../../testing';
+
+const DOCS_PATH = resolve(__dirname, 'cluster.docs.json');
+
+test.describe('cluster visual regression', () => {
+  test('all variations', async ({ page }) => {
+    await setupVisualTestFromDocs(page, DOCS_PATH);
+    // skip validateGridRhythm: cluster is a layout primitive that
+    // controls gap/alignment, not child height
+    await saveForLostPixel(page, 'cluster');
+    await expect(page.locator('body')).toHaveScreenshot('cluster.visual.png');
+  });
+});

package/src/03-layout/sidebar/sidebar.docs.json

@@ -0,0 +1,62 @@
+{
+  "id": "sidebar",
+  "type": "primitive",
+  "title": "Sidebar",
+  "description": "Fixed-position sidebar for app layouts with adjustable widths and positioning.",
+  "api": "./sidebar.api.json",
+  "sections": [
+    {
+      "title": "Basic",
+      "description": "Default sidebar positioned on the start side. Use inside an app-shell layout.",
+      "examples": [
+        {
+          "code": "<aside class=\"ui-sidebar\">\n  <p>Sidebar content</p>\n</aside>"
+        }
+      ]
+    },
+    {
+      "title": "Widths",
+      "description": "Three width options via size modifiers.",
+      "examples": [
+        {
+          "layout": "stack",
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-cluster",
+              "children": [
+                { "tag": "code", "text": "--sm" },
+                { "tag": "span", "text": "192px (24 units)" }
+              ]
+            },
+            {
+              "tag": "div",
+              "class": "ui-cluster",
+              "children": [
+                { "tag": "code", "text": "--md" },
+                { "tag": "span", "text": "240px (30 units, default)" }
+              ]
+            },
+            {
+              "tag": "div",
+              "class": "ui-cluster",
+              "children": [
+                { "tag": "code", "text": "--lg" },
+                { "tag": "span", "text": "320px (40 units)" }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "End Position",
+      "description": "Position sidebar on the end side with --end modifier.",
+      "examples": [
+        {
+          "code": "<aside class=\"ui-sidebar ui-sidebar--end\">\n  <p>End sidebar</p>\n</aside>"
+        }
+      ]
+    }
+  ]
+}

package/src/03-layout/sidebar/sidebar.visual.spec.ts

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

package/src/03-layout/sidebar-nav/sidebar-nav.api.json

@@ -1,115 +1,64 @@
 {
   "name": "sidebar-nav",
-  "baseClass": "sidebar-nav",
   "element": "nav",
-  "description": "Navigation component for sidebars with support for groups, nested items, icons, and badges",
   "modifiers": {
     "collapsed": {
-      "type": "boolean",
-      "description": "Icon-only mode, hides labels and badges"
+      "type": "boolean"
     }
   },
   "elements": {
-    "header": {
-      "element": "div",
-      "description": "Sticky header section"
-    },
-    "content": {
-      "element": "div",
-      "description": "Scrollable content area"
-    },
-    "footer": {
-      "element": "div",
-      "description": "Sticky footer section"
-    },
-    "group": {
-      "element": "div",
-      "description": "Navigation group container"
-    },
-    "group-label": {
-      "element": "span",
-      "description": "Group section heading"
-    },
-    "group-items": {
-      "element": "ul",
-      "description": "List of nav items in a group"
-    },
-    "subgroup-label": {
-      "element": "span",
-      "description": "Nested subgroup heading"
-    },
+    "header": {},
+    "content": {},
+    "footer": {},
+    "group": {},
+    "group-label": {},
+    "group-items": {},
+    "subgroup-label": {},
     "item": {
-      "element": "a",
-      "description": "Navigation link",
       "modifiers": {
         "active": {
-          "type": "boolean",
-          "description": "Current/active page state"
+          "type": "boolean"
         },
         "disabled": {
-          "type": "boolean",
-          "description": "Non-interactive item"
+          "type": "boolean"
         },
         "nested": {
-          "type": "boolean",
-          "description": "Indented nested item"
+          "type": "boolean"
         }
       }
     },
-    "icon": {
-      "element": "span",
-      "description": "Icon container"
-    },
-    "label": {
-      "element": "span",
-      "description": "Text label"
-    },
-    "badge": {
-      "element": "span",
-      "description": "Badge or count indicator"
-    }
-  },
-  "accessibility": {
-    "role": "navigation",
-    "aria-label": "Required - descriptive label for the navigation",
-    "aria-current": "Use 'page' on active item link",
-    "keyboard": "Tab navigation between focusable items"
+    "icon": {},
+    "label": {},
+    "badge": {}
   },
-  "customization": [
+  "cssVars": [
     {
-      "token": "--ui-sidebar-nav-width",
-      "default": "calc(var(--ui-unit) * 30)",
-      "description": "Default sidebar width"
+      "name": "--ui-sidebar-nav-width",
+      "default": "calc(var(--ui-unit) * 30)"
     },
     {
-      "token": "--ui-sidebar-nav-width-collapsed",
-      "default": "var(--ui-row-3)",
-      "description": "Width in collapsed/icon-only mode"
+      "name": "--ui-sidebar-nav-width-collapsed",
+      "default": "var(--ui-row-3)"
     },
     {
-      "token": "--ui-sidebar-nav-bg",
-      "default": "var(--ui-color-bg-subtle)",
-      "description": "Background color"
+      "name": "--ui-sidebar-nav-bg",
+      "default": "var(--ui-color-bg-subtle)"
     },
     {
-      "token": "--ui-sidebar-nav-item-height",
-      "default": "var(--ui-row-2)",
-      "description": "Nav item height"
+      "name": "--ui-sidebar-nav-item-height",
+      "default": "var(--ui-row-2)"
     },
     {
-      "token": "--ui-sidebar-nav-item-hover-bg",
-      "default": "var(--ui-color-bg-muted)",
-      "description": "Item hover background"
+      "name": "--ui-sidebar-nav-item-hover-bg",
+      "default": "var(--ui-color-bg-muted)"
     },
     {
-      "token": "--ui-sidebar-nav-item-active-bg",
-      "default": "var(--ui-color-primary-subtle)",
-      "description": "Active item background"
+      "name": "--ui-sidebar-nav-item-active-bg",
+      "default": "var(--ui-color-primary-subtle)"
     },
     {
-      "token": "--ui-sidebar-nav-item-active-color",
-      "default": "var(--ui-color-primary)",
-      "description": "Active item text color"
+      "name": "--ui-sidebar-nav-item-active-color",
+      "default": "var(--ui-color-primary)"
     }
   ]
 }

package/src/04-components/{button → actions/button}/button.api.json

@@ -3,7 +3,7 @@
   "element": "button",
   "modifiers": {
     "size": {
-      "values": ["sm", "lg"]
+      "values": ["sm", "md", "lg"]
     },
     "variant": {
       "values": ["secondary", "ghost", "outline", "danger", "link"]
@@ -21,7 +21,24 @@
       "type": "boolean"
     }
   },
+  "elements": {
+    "icon": {
+      "modifiers": {
+        "start": {
+          "type": "boolean"
+        },
+        "end": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
   "cssVars": [
+    {
+      "name": "--ui-button-accent",
+      "description": "Primary accent color. All shades auto-generated via color-mix.",
+      "default": "var(--ui-color-primary)"
+    },
     {
       "name": "--ui-button-height",
       "default": "var(--ui-row-2)"
@@ -42,29 +59,29 @@
       "name": "--ui-button-radius",
       "default": "var(--ui-radius-md)"
     },
-    {
-      "name": "--ui-button-bg",
-      "default": "var(--ui-color-primary)"
-    },
-    {
-      "name": "--ui-button-bg-hover",
-      "default": "var(--ui-color-primary-dark)"
-    },
     {
       "name": "--ui-button-text",
       "default": "var(--ui-color-text-inverse)"
     },
     {
       "name": "--ui-button-height-sm",
-      "default": "var(--row)"
+      "default": "calc(var(--row) * 1.5)"
     },
     {
       "name": "--ui-button-font-size-sm",
       "default": "var(--ui-font-size-xs)"
     },
+    {
+      "name": "--ui-button-height-md",
+      "default": "var(--ui-row-2)"
+    },
+    {
+      "name": "--ui-button-font-size-md",
+      "default": "var(--ui-font-size-sm)"
+    },
     {
       "name": "--ui-button-height-lg",
-      "default": "var(--row)"
+      "default": "calc(var(--row) * 2.5)"
     },
     {
       "name": "--ui-button-padding-x-lg",
@@ -87,52 +104,9 @@
       "default": "var(--ui-color-text)"
     },
     {
-      "name": "--ui-button-ghost-bg",
-      "default": "transparent"
-    },
-    {
-      "name": "--ui-button-ghost-bg-hover",
-      "default": "var(--ui-color-bg-subtle)"
-    },
-    {
-      "name": "--ui-button-ghost-text",
-      "default": "var(--ui-color-primary)"
-    },
-    {
-      "name": "--ui-button-outline-bg",
-      "default": "transparent"
-    },
-    {
-      "name": "--ui-button-outline-bg-hover",
-      "default": "var(--ui-color-primary)"
-    },
-    {
-      "name": "--ui-button-outline-text",
-      "default": "var(--ui-color-primary)"
-    },
-    {
-      "name": "--ui-button-outline-text-hover",
-      "default": "var(--ui-color-text-inverse)"
-    },
-    {
-      "name": "--ui-button-outline-border",
-      "default": "var(--ui-border-width-sm)"
-    },
-    {
-      "name": "--ui-button-danger-bg",
+      "name": "--ui-color-danger",
+      "description": "Used by --danger variant as accent color",
       "default": "var(--ui-color-danger)"
-    },
-    {
-      "name": "--ui-button-danger-bg-hover",
-      "default": "#{t.$color-danger-dark}"
-    },
-    {
-      "name": "--ui-button-link-text",
-      "default": "var(--ui-color-primary)"
-    },
-    {
-      "name": "--ui-button-link-text-hover",
-      "default": "var(--ui-color-primary-dark)"
     }
   ]
 }

package/src/04-components/{button → actions/button}/button.docs.json

@@ -22,6 +22,81 @@
     }
   },
   "sections": [
+    {
+      "title": "Variants",
+      "description": "Button styles for different purposes and emphasis levels.",
+      "examples": [
+        {
+          "layout": "cluster",
+          "items": [
+            { "tag": "button", "class": "ui-button", "text": "Primary" },
+            { "tag": "button", "class": "ui-button ui-button--secondary", "text": "Secondary" },
+            { "tag": "button", "class": "ui-button ui-button--outline", "text": "Outline" },
+            { "tag": "button", "class": "ui-button ui-button--ghost", "text": "Ghost" },
+            { "tag": "button", "class": "ui-button ui-button--danger", "text": "Danger" },
+            { "tag": "button", "class": "ui-button ui-button--link", "text": "Link" }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Sizes",
+      "description": "Small for dense UIs, default for most cases, large for prominent CTAs.",
+      "examples": [
+        {
+          "layout": "cluster",
+          "items": [
+            { "tag": "button", "class": "ui-button ui-button--sm", "text": "Small" },
+            { "tag": "button", "class": "ui-button ui-button--md", "text": "Medium" },
+            { "tag": "button", "class": "ui-button ui-button--lg", "text": "Large" }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Radius",
+      "description": "Override border radius. Use radius-full for pill-shaped buttons.",
+      "examples": [
+        {
+          "layout": "cluster",
+          "items": [
+            { "tag": "button", "class": "ui-button ui-button--radius-none", "text": "None" },
+            { "tag": "button", "class": "ui-button ui-button--radius-sm", "text": "Small" },
+            { "tag": "button", "class": "ui-button", "text": "Default" },
+            { "tag": "button", "class": "ui-button ui-button--radius-lg", "text": "Large" },
+            { "tag": "button", "class": "ui-button ui-button--radius-full", "text": "Full" }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Block",
+      "description": "Full width button for mobile or form submit.",
+      "examples": [
+        {
+          "items": [
+            { "tag": "button", "class": "ui-button ui-button--block", "text": "Block Button" }
+          ]
+        }
+      ]
+    },
+    {
+      "title": "Loading",
+      "description": "Shows spinner animation. Button becomes non-interactive.",
+      "examples": [
+        {
+          "layout": "cluster",
+          "items": [
+            { "tag": "button", "class": "ui-button ui-button--loading", "text": "Loading" },
+            {
+              "tag": "button",
+              "class": "ui-button ui-button--secondary ui-button--loading",
+              "text": "Loading"
+            }
+          ]
+        }
+      ]
+    },
     {
       "title": "Icon Button",
       "description": "Square icon-only buttons. Use with SVG icons from Lucide or similar sets.",

package/src/04-components/{button → actions/button}/button.visual.spec.ts

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