@teseor/css 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teseor/css",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "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/02-base/typography/typography.scss

@@ -103,6 +103,22 @@
     background: none;
   }
 
+  // Links - inherit design system colors
+  a {
+    text-decoration: underline;
+    color: var(--ui-color-primary);
+
+    transition: color var(--ui-duration-fast) var(--ui-ease-default);
+
+    &:hover {
+      color: var(--ui-color-primary-hover);
+    }
+
+    &:visited {
+      color: var(--ui-color-primary);
+    }
+  }
+
   // ==========================================================================
   // RESPONSIVE BREAKPOINTS
   // ==========================================================================

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/accordion/accordion.api.json

@@ -1,7 +1,11 @@
 {
   "name": "accordion",
   "element": "div",
-  "modifiers": {},
+  "modifiers": {
+    "separated": {
+      "type": "boolean"
+    }
+  },
   "cssVars": [
     {
       "name": "--ui-accordion-border-color",

package/src/04-components/alert/alert.api.json

@@ -6,6 +6,12 @@
       "values": ["info", "success", "warning", "danger"]
     }
   },
+  "elements": {
+    "content": {},
+    "title": {},
+    "description": {},
+    "icon": {}
+  },
   "cssVars": [
     {
       "name": "--ui-alert-padding",

package/src/04-components/alert/index.scss

@@ -5,39 +5,34 @@
 
 @layer components.tokens {
   .alert {
+    // Single accent color - variants override, bg/border derived via color-mix
+    --_accent: var(--ui-alert-accent, var(--ui-color-border, #{t.$color-border}));
+
     --_padding: var(--ui-alert-padding, var(--ui-space-2, #{t.$space-2}));
     --_border-width: var(--ui-alert-border-width, var(--ui-border-width-sm, #{t.$border-width-sm}));
     --_gap: var(--ui-alert-gap, var(--ui-space-1, #{t.$space-1}));
     --_radius: var(--ui-alert-radius, var(--ui-radius-md, #{t.$radius-md}));
-    --_bg: var(--ui-alert-bg, var(--ui-color-bg-subtle, #{t.$color-bg-subtle}));
-    --_border-color: var(--ui-alert-border-color, var(--ui-color-border, #{t.$color-border}));
+    --_bg: color-mix(in oklch, var(--_accent) 8%, white);
+    --_border-color: var(--_accent);
     --_color: var(--ui-alert-color, var(--ui-color-text, #{t.$color-text}));
-    --_icon-color: var(--ui-alert-icon-color, currentcolor);
+    --_icon-color: var(--_accent);
   }
 
   // @modifier variant
   .alert--info {
-    --_bg: var(--ui-alert-info-bg, var(--ui-color-bg-subtle, #{t.$color-bg-subtle}));
-    --_border-color: var(--ui-alert-info-border, var(--ui-color-primary, #{t.$color-primary}));
-    --_icon-color: var(--ui-alert-info-icon, var(--ui-color-primary, #{t.$color-primary}));
+    --_accent: var(--ui-color-primary, #{t.$color-primary});
   }
 
   .alert--success {
-    --_bg: var(--ui-alert-success-bg, var(--ui-color-bg-subtle, #{t.$color-bg-subtle}));
-    --_border-color: var(--ui-alert-success-border, var(--ui-color-success, #{t.$color-success}));
-    --_icon-color: var(--ui-alert-success-icon, var(--ui-color-success, #{t.$color-success}));
+    --_accent: var(--ui-color-success, #{t.$color-success});
   }
 
   .alert--warning {
-    --_bg: var(--ui-alert-warning-bg, var(--ui-color-bg-subtle, #{t.$color-bg-subtle}));
-    --_border-color: var(--ui-alert-warning-border, var(--ui-color-warning, #{t.$color-warning}));
-    --_icon-color: var(--ui-alert-warning-icon, var(--ui-color-warning, #{t.$color-warning}));
+    --_accent: var(--ui-color-warning, #{t.$color-warning});
   }
 
   .alert--danger {
-    --_bg: var(--ui-alert-danger-bg, var(--ui-color-bg-subtle, #{t.$color-bg-subtle}));
-    --_border-color: var(--ui-alert-danger-border, var(--ui-color-danger, #{t.$color-danger}));
-    --_icon-color: var(--ui-alert-danger-icon, var(--ui-color-danger, #{t.$color-danger}));
+    --_accent: var(--ui-color-danger, #{t.$color-danger});
   }
 }
 

package/src/04-components/avatar/avatar.api.json

@@ -9,6 +9,11 @@
       "type": "boolean"
     }
   },
+  "elements": {
+    "fallback": {},
+    "image": {}
+  },
+  "relatedComponents": ["avatar-group"],
   "cssVars": [
     {
       "name": "--ui-avatar-size",

package/src/04-components/badge/index.scss

@@ -5,12 +5,15 @@
 
 @layer components.tokens {
   .badge {
+    // Single accent color - variants override this
+    --_accent: var(--ui-badge-accent, var(--ui-color-bg-muted, #{t.$color-bg-muted}));
+
     --_height: var(--ui-badge-height, calc(var(--ui-row, #{t.$row}) * 1.25));
     --_padding-x: var(--ui-badge-padding-x, var(--ui-space-1, #{t.$space-1}));
     --_font-size: var(--ui-badge-font-size, var(--ui-font-size-xs, #{t.$font-size-xs}));
     --_font-weight: var(--ui-badge-font-weight, var(--ui-weight-medium, #{t.$weight-medium}));
     --_radius: var(--ui-badge-radius, var(--ui-radius-full, #{t.$radius-full}));
-    --_bg: var(--ui-badge-bg, var(--ui-color-bg-muted, #{t.$color-bg-muted}));
+    --_bg: var(--_accent);
     --_text: var(--ui-badge-text, var(--ui-color-text, #{t.$color-text}));
   }
 
@@ -23,23 +26,23 @@
 
   // @modifier variant
   .badge--primary {
-    --_bg: var(--ui-badge-primary-bg, var(--ui-color-primary, #{t.$color-primary}));
-    --_text: var(--ui-badge-primary-text, var(--ui-color-text-inverse, #{t.$color-text-inverse}));
+    --_accent: var(--ui-color-primary, #{t.$color-primary});
+    --_text: var(--ui-color-text-inverse, #{t.$color-text-inverse});
   }
 
   .badge--success {
-    --_bg: var(--ui-badge-success-bg, var(--ui-color-success, #{t.$color-success}));
-    --_text: var(--ui-badge-success-text, var(--ui-color-text-inverse, #{t.$color-text-inverse}));
+    --_accent: var(--ui-color-success, #{t.$color-success});
+    --_text: var(--ui-color-text-inverse, #{t.$color-text-inverse});
   }
 
   .badge--warning {
-    --_bg: var(--ui-badge-warning-bg, var(--ui-color-warning, #{t.$color-warning}));
-    --_text: var(--ui-badge-warning-text, var(--ui-color-text, #{t.$color-text}));
+    --_accent: var(--ui-color-warning, #{t.$color-warning});
+    --_text: var(--ui-color-text, #{t.$color-text});
   }
 
   .badge--danger {
-    --_bg: var(--ui-badge-danger-bg, var(--ui-color-danger, #{t.$color-danger}));
-    --_text: var(--ui-badge-danger-text, var(--ui-color-text-inverse, #{t.$color-text-inverse}));
+    --_accent: var(--ui-color-danger, #{t.$color-danger});
+    --_text: var(--ui-color-text-inverse, #{t.$color-text-inverse});
   }
 }
 

package/src/04-components/breadcrumb/breadcrumb.api.json

@@ -2,6 +2,11 @@
   "name": "breadcrumb",
   "element": "div",
   "modifiers": {},
+  "elements": {
+    "item": {},
+    "link": {},
+    "current": {}
+  },
   "cssVars": [
     {
       "name": "--ui-breadcrumb-height",