@teseor/css 1.7.0 → 1.9.0

package/src/{03-layout → layout}/topbar/index.scss

@@ -1,9 +1,20 @@
+// @component topbar
+// @element header
+
 @layer primitives {
   .topbar {
+    --_space-2: var(--ui-space-2);
+    --_border-width-sm: var(--ui-border-width-sm);
+    --_shadow-sm: var(--ui-shadow-sm);
+    // @desc Overall height
     --_height: var(--ui-topbar-height, var(--ui-row-3));
+    // @desc Background color
     --_bg: var(--ui-topbar-bg, var(--ui-color-bg));
+    // @desc Horizontal padding
     --_padding-inline: var(--ui-topbar-padding-inline, var(--ui-space-3));
+    // @desc Border color
     --_border-color: var(--ui-topbar-border-color, var(--ui-color-border));
+    // @desc Z-index stacking order
     --_z: var(--ui-topbar-z, var(--ui-z-sticky));
 
     display: flex;
@@ -21,7 +32,7 @@
     display: flex;
     flex-shrink: 0;
     align-items: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   .topbar__center {
@@ -29,22 +40,24 @@
     flex: 1;
     align-items: center;
     justify-content: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   .topbar__end {
     display: flex;
     flex-shrink: 0;
     align-items: center;
-    gap: var(--ui-space-2);
+    gap: var(--_space-2);
   }
 
   // Position modifiers
+  // @modifier boolean sticky
   .topbar--sticky {
     position: sticky;
     inset-block-start: 0;
   }
 
+  // @modifier boolean fixed
   .topbar--fixed {
     position: fixed;
     inset-block-start: 0;
@@ -52,11 +65,13 @@
   }
 
   // Visual modifiers
+  // @modifier boolean bordered
   .topbar--bordered {
-    box-shadow: inset 0 calc(var(--ui-border-width-sm) * -1) 0 0 var(--_border-color);
+    box-shadow: inset 0 calc(var(--_border-width-sm) * -1) 0 0 var(--_border-color);
   }
 
+  // @modifier boolean raised
   .topbar--raised {
-    box-shadow: var(--shadow-sm);
+    box-shadow: var(--_shadow-sm);
   }
 }

package/src/{03-layout → layout}/topbar/topbar.api.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
   "name": "topbar",
   "element": "header",
   "modifiers": {
@@ -23,23 +24,28 @@
   "cssVars": [
     {
       "name": "--ui-topbar-height",
-      "default": "var(--ui-row-3)"
+      "default": "var(--ui-row-3)",
+      "description": "Overall height"
     },
     {
       "name": "--ui-topbar-bg",
-      "default": "var(--ui-color-bg)"
+      "default": "var(--ui-color-bg)",
+      "description": "Background color"
     },
     {
       "name": "--ui-topbar-padding-inline",
-      "default": "var(--ui-space-3)"
+      "default": "var(--ui-space-3)",
+      "description": "Horizontal padding"
     },
     {
       "name": "--ui-topbar-border-color",
-      "default": "var(--ui-color-border)"
+      "default": "var(--ui-color-border)",
+      "description": "Border color"
     },
     {
       "name": "--ui-topbar-z",
-      "default": "var(--ui-z-sticky)"
+      "default": "var(--ui-z-sticky)",
+      "description": "Z-index stacking order"
     }
   ]
 }

package/src/testing/api-types.ts

@@ -1,6 +1,6 @@
 export interface ComponentAPI {
   name: string;
-  baseClass: string;
+  baseClass?: string;
   element: string;
   description: string;
   modifiers: Record<

package/src/testing/grid-alignment.spec.ts

@@ -1,92 +1,38 @@
-import { expect, test } from '@playwright/test';
-
-// Skip in CI - needs docs server running
-test.skip(!!process.env.CI, 'Grid alignment test requires docs server');
-
-// Elements that THEMSELVES don't follow grid (fluid page containers only)
-const SKIP_SELF_SELECTORS = [
-  // Page structure - fluid by nature (viewport-dependent)
-  'html',
-  'body',
-  'main',
-  'aside',
-  '.ui-sidebar',
-  '.ui-main',
-  '.ui-app-shell',
+import { readdirSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { test } from '@playwright/test';
+import { generateHtmlFromDocs, loadDocsJson, setupVisualTest, validateGridRhythm } from '.';
+
+const COMPONENTS_DIR = resolve(__dirname, '../components');
+
+// Known grid rhythm issues tracked in separate issues
+const SKIP_COMPONENTS = [
+  'data-list', // 1px borders cause off-grid heights (#179)
+  'spinner', // CSS var resolution issue (#154)
+  'spacer', // no intrinsic height by design
 ];
 
-test('all components should align to vertical grid', async ({ page }) => {
-  await page.goto('/');
-
-  const violations = await page.evaluate((skipSelf: string[]) => {
-    // Get unit from CSS custom property
-    const temp = document.createElement('div');
-    temp.style.cssText = 'position:absolute;visibility:hidden;width:var(--unit,0.5rem)';
-    document.body.appendChild(temp);
-    const unit = temp.getBoundingClientRect().width || 8;
-    document.body.removeChild(temp);
-
-    const INLINE_TAGS = [
-      'STRONG',
-      'B',
-      'EM',
-      'I',
-      'SMALL',
-      'SPAN',
-      'A',
-      'CODE',
-      'ABBR',
-      'CITE',
-      'Q',
-      'SUB',
-      'SUP',
-      'MARK',
-      'BR',
-      'WBR',
-    ];
-
-    const results: Array<{ selector: string; height: number; expected: number; offBy: number }> =
-      [];
-
-    for (const el of document.querySelectorAll('*')) {
-      const tagName = el.tagName;
-
-      // Skip script, style, link, meta, etc.
-      if (['SCRIPT', 'STYLE', 'LINK', 'META', 'TITLE', 'HEAD'].includes(tagName)) continue;
-
-      // Skip inline elements
-      if (INLINE_TAGS.includes(tagName)) continue;
-
-      // Skip elements that are fluid containers (but check their children)
-      if (skipSelf.some((sel) => el.matches(sel))) continue;
-
-      const height = el.getBoundingClientRect().height;
-      if (height === 0) continue;
-
-      const remainder = height % unit;
-      const isAligned = remainder < 0.5 || remainder > unit - 0.5;
-
-      if (!isAligned) {
-        const classes = el.className?.toString?.() || '';
-        const firstClass = classes.split(' ')[0];
-        results.push({
-          selector: `${tagName.toLowerCase()}${firstClass ? `.${firstClass}` : ''}`,
-          height: Math.round(height * 10) / 10,
-          expected: Math.round(height / unit) * unit,
-          offBy: Math.round(remainder * 10) / 10,
-        });
-      }
+function findDocsFiles(dir: string): Array<{ name: string; path: string }> {
+  const results: Array<{ name: string; path: string }> = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      results.push(...findDocsFiles(full));
+    } else if (entry.endsWith('.docs.json')) {
+      results.push({ name: basename(entry, '.docs.json'), path: full });
     }
-
-    return results;
-  }, SKIP_SELF_SELECTORS);
-
-  if (violations.length > 0) {
-    console.log(`Found ${violations.length} grid violations:`);
-    console.table(violations);
   }
-
-  expect(violations, `Grid violations found:\n${JSON.stringify(violations, null, 2)}`).toHaveLength(
-    0,
-  );
-});
+  return results;
+}
+
+const docsFiles = findDocsFiles(COMPONENTS_DIR);
+
+for (const { name, path } of docsFiles) {
+  test(`${name} aligns to vertical grid`, async ({ page }) => {
+    test.skip(SKIP_COMPONENTS.includes(name), `${name} has known grid issues`);
+    const docs = loadDocsJson(path);
+    const html = generateHtmlFromDocs(docs);
+    await setupVisualTest(page, { html });
+    await validateGridRhythm(page, name);
+  });
+}

package/src/testing/html-generator.ts

@@ -30,7 +30,7 @@ function capitalize(s: string): string {
 }
 
 export function generateVariationsHtml(api: ComponentAPI): string {
-  const baseClass = `${PREFIX}${api.baseClass}`;
+  const baseClass = `${PREFIX}${api.baseClass ?? api.name}`;
   const element = api.element;
   const title = capitalize(api.name);
 

package/src/testing/page-setup.ts

@@ -8,7 +8,7 @@ import { generateVariationsHtml } from './html-generator';
 import { scaffoldCss } from './scaffold';
 
 interface DocsItem {
-  tag: string;
+  tag?: string;
   class?: string;
   text?: string;
   attrs?: Record<string, string>;
@@ -43,6 +43,8 @@ export function loadComponentApi(apiPath: string): ComponentAPI {
 }
 
 function renderItem(item: DocsItem): string {
+  if (!item.tag) return item.text ?? '';
+
   const parts: string[] = [];
 
   if (item.class) parts.push(`class="${item.class}"`);
@@ -83,7 +85,7 @@ export function generateHtmlFromDocs(docs: DocsJson): string {
         html = example.html;
       } else if (example.items) {
         const items = example.items.map(renderItem).join('\n');
-        html = example.layout === 'cluster' ? `<div class="ui-cluster">${items}</div>` : items;
+        html = example.layout === 'row' ? `<div class="ui-row">${items}</div>` : items;
       }
 
       if (html) {

package/src/utilities/border/index.scss

@@ -0,0 +1,18 @@
+@layer utilities {
+  // Border
+  .border { border: var(--ui-border-width-sm) solid var(--ui-color-border); }
+  .border-0 { border: none; }
+
+  // Radius
+  .rounded { border-radius: var(--ui-radius-md); }
+  .rounded-none { border-radius: 0; }
+  .rounded-sm { border-radius: var(--ui-radius-sm); }
+  .rounded-lg { border-radius: var(--ui-radius-lg); }
+  .rounded-full { border-radius: var(--ui-radius-full); }
+
+  // Background
+  .bg { background: var(--ui-color-bg); }
+  .bg-subtle { background: var(--ui-color-bg-subtle); }
+  .bg-muted { background: var(--ui-color-bg-muted); }
+  .bg-transparent { background: transparent; }
+}

package/src/{05-utilities → utilities}/display/display.scss

@@ -1,8 +1,8 @@
-/* Display and visibility utilities */
+// Display and visibility utilities
 
-/* Uses logical properties for international/RTL support */
+// Uses logical properties for international/RTL support
 @layer utilities {
-  /* Display */
+  // Display
   .block {
     display: block;
   }
@@ -35,7 +35,7 @@
     display: none;
   }
 
-  /* Flexbox direction */
+  // Flexbox direction
   .flex-row {
     flex-direction: row;
   }
@@ -52,7 +52,7 @@
     flex-direction: column-reverse;
   }
 
-  /* Flexbox wrap */
+  // Flexbox wrap
   .flex-wrap {
     flex-wrap: wrap;
   }
@@ -65,7 +65,7 @@
     flex-wrap: wrap-reverse;
   }
 
-  /* Flexbox grow/shrink */
+  // Flexbox grow/shrink
   .flex-1 {
     flex: 1 1 0%;
   }
@@ -98,7 +98,7 @@
     flex-shrink: 0;
   }
 
-  /* Justify content */
+  // Justify content
   .justify-start {
     justify-content: flex-start;
   }
@@ -123,7 +123,7 @@
     justify-content: space-evenly;
   }
 
-  /* Align items */
+  // Align items
   .items-start {
     align-items: flex-start;
   }
@@ -144,7 +144,7 @@
     align-items: stretch;
   }
 
-  /* Align self */
+  // Align self
   .self-auto {
     align-self: auto;
   }
@@ -165,7 +165,7 @@
     align-self: stretch;
   }
 
-  /* Visibility */
+  // Visibility
   .visible {
     visibility: visible;
   }
@@ -174,7 +174,7 @@
     visibility: hidden;
   }
 
-  /* Screen reader only - visually hidden but accessible */
+  // Screen reader only - visually hidden but accessible
   .sr-only {
     position: absolute;
 

package/src/{05-utilities → utilities}/spacing/spacing.docs.json

@@ -8,7 +8,7 @@
     {
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             {
               "tag": "div",

package/src/{05-utilities → utilities}/spacing/spacing.scss

@@ -1,8 +1,8 @@
-/* Spacing utilities - all values align to 8px grid */
+// Spacing utilities - all values align to 8px grid
 
-/* Uses logical properties for international/RTL support */
+// Uses logical properties for international/RTL support
 @layer utilities {
-  /* Margin utilities */
+  // Margin utilities
   .m-0 {
     margin: 0;
   }
@@ -187,7 +187,7 @@
     margin-block: var(--ui-space-4);
   }
 
-  /* Padding utilities */
+  // Padding utilities
   .p-0 {
     padding: 0;
   }
@@ -368,7 +368,7 @@
     padding-block: var(--ui-space-4);
   }
 
-  /* Gap utilities (for flex/grid) */
+  // Gap utilities (for flex/grid)
   .gap-0 {
     gap: 0;
   }

package/src/{05-utilities → utilities}/text/text.docs.json

@@ -10,7 +10,7 @@
       "description": "Font size utilities with 8px grid-snapped line-heights.",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             { "tag": "p", "class": "ui-text-xs", "text": "text-xs: 12px / 16px line-height" },
             { "tag": "p", "class": "ui-text-sm", "text": "text-sm: 14px / 24px line-height" },
@@ -29,7 +29,7 @@
       "description": "Semantic text styles for specific use cases.",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             {
               "tag": "p",
@@ -55,7 +55,7 @@
       "title": "Weights",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             { "tag": "p", "class": "ui-font-normal", "text": "font-normal (400)" },
             { "tag": "p", "class": "ui-font-medium", "text": "font-medium (500)" },
@@ -69,7 +69,7 @@
       "title": "Letter Spacing",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             {
               "tag": "p",
@@ -91,7 +91,7 @@
       "description": "Constrain text width for optimal readability.",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             { "tag": "p", "class": "ui-prose-sm", "text": "prose-sm: 45ch max-width" },
             { "tag": "p", "class": "ui-prose", "text": "prose: 65ch max-width (recommended)" },
@@ -104,7 +104,7 @@
       "title": "Colors",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             { "tag": "p", "class": "ui-text-primary", "text": "text-primary" },
             { "tag": "p", "class": "ui-text-muted", "text": "text-muted" },
@@ -119,7 +119,7 @@
       "title": "Alignment",
       "examples": [
         {
-          "layout": "stack",
+          "layout": "column",
           "items": [
             { "tag": "p", "class": "ui-text-start", "text": "text-start (default)" },
             { "tag": "p", "class": "ui-text-center", "text": "text-center" },

package/src/{05-utilities → utilities}/visually-hidden/index.scss

@@ -1,7 +1,7 @@
 // Visually Hidden - accessible hiding utility
 // Hides content visually but keeps it accessible to screen readers
 
-@use '../../00-config/tokens/variables' as t;
+@use '../../config/tokens/variables' as t;
 
 @layer utilities {
   .visually-hidden {
@@ -21,7 +21,7 @@
   }
 
   // Focusable variant - becomes visible on focus
-  .visually-hidden--focusable:focus,
+  .visually-hidden--focusable:focus-visible,
   .visually-hidden--focusable:active {
     position: static;
 

package/src/{05-utilities → utilities}/visually-hidden/visually-hidden.docs.json

@@ -10,7 +10,15 @@
       "description": "Content is hidden visually but announced by screen readers",
       "examples": [
         {
-          "html": "<button>Submit<span class=\"ui-visually-hidden\"> form to contact support</span></button>",
+          "items": [
+            {
+              "tag": "button",
+              "children": [
+                { "text": "Submit" },
+                { "tag": "span", "class": "ui-visually-hidden", "text": " form to contact support" }
+              ]
+            }
+          ],
           "code": "<button>\n  Submit\n  <span class=\"ui-visually-hidden\"> form to contact support</span>\n</button>"
         }
       ]
@@ -20,7 +28,14 @@
       "description": "Becomes visible when focused - useful for skip links",
       "examples": [
         {
-          "html": "<a href=\"#main\" class=\"ui-visually-hidden ui-visually-hidden--focusable\" style=\"position: relative;\">Skip to main content</a>",
+          "items": [
+            {
+              "tag": "a",
+              "class": "ui-visually-hidden ui-visually-hidden--focusable",
+              "attrs": { "href": "#main", "style": "position: relative;" },
+              "text": "Skip to main content"
+            }
+          ],
           "code": "<a href=\"#main\" class=\"ui-visually-hidden ui-visually-hidden--focusable\">\n  Skip to main content\n</a>"
         }
       ]

package/src/00-config/mixins/_border.scss

@@ -1,13 +0,0 @@
-// Border and surface mixins - shared by components and utilities
-
-@mixin border($width: var(--ui-border-width-sm), $color: var(--ui-color-border)) {
-  border: $width solid $color;
-}
-
-@mixin rounded($size: var(--ui-radius-md)) {
-  border-radius: $size;
-}
-
-@mixin surface($bg: var(--ui-color-bg)) {
-  background: $bg;
-}

package/src/00-config/mixins/index.scss

@@ -1 +0,0 @@
-@forward './border';

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

@@ -1,6 +0,0 @@
-:root {
-  // Border widths - derived from unit (8px)
-  --ui-border-width-sm: calc(var(--unit) * 0.125); // 1px
-  --ui-border-width-md: calc(var(--unit) * 0.25); // 2px
-  --ui-border-width-lg: calc(var(--unit) * 0.5); // 4px
-}