@teseor/css 1.0.0

package/src/index.scss

@@ -0,0 +1,30 @@
+/**
+ * CSS Library - Main Entry Point
+ *
+ * Import order follows numbered folder structure for cascade control.
+ */
+
+/* 00. Config: Layer definitions + Design tokens */
+@use './00-config/layers/layers' as *;
+@use './00-config/tokens/index' as *;
+
+/* 01. Reset styles */
+@use './01-reset/index' as *;
+
+/* 02. Base styles (typography, etc.) */
+@use './02-base/index' as *;
+
+/* 03. Layout primitives */
+@use './03-layout/index' as *;
+
+/* 04. Components */
+@use './04-components/index' as *;
+
+/* 05. Utilities (high specificity, load last) */
+@use './05-utilities/index' as *;
+
+/* 99. Debug tools (dev only) */
+@use './99-debug/index' as *;
+
+/* Fonts (Google Fonts CDN) */
+@import "https://fonts.googleapis.com/css2?family=Noto+Sans:wght@400;500;700&family=Noto+Sans+Mono:wght@400;500&display=swap";

package/src/testing/api-types.ts

@@ -0,0 +1,20 @@
+export interface ComponentAPI {
+  name: string;
+  baseClass: string;
+  element: string;
+  description: string;
+  modifiers: Record<
+    string,
+    {
+      values?: string[];
+      type?: string;
+      default?: string | null;
+      description: string;
+    }
+  >;
+  states?: string[];
+  combinations?: Array<{
+    modifiers: string[];
+    disabled?: boolean;
+  }>;
+}

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

@@ -0,0 +1,92 @@
+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',
+];
+
+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,
+        });
+      }
+    }
+
+    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,
+  );
+});

package/src/testing/html-generator.ts

@@ -0,0 +1,151 @@
+import type { ComponentAPI } from './api-types';
+
+const PREFIX = 'ui-';
+
+function generateCombinations(
+  api: ComponentAPI,
+): Array<{ modifiers: string[]; disabled?: boolean }> {
+  if (api.combinations) return api.combinations;
+
+  const enumModifiers = Object.entries(api.modifiers)
+    .filter(([, def]) => def.values)
+    .map(([, def]) => def.values!);
+
+  if (enumModifiers.length < 2) return [];
+
+  const [first, second] = enumModifiers;
+  const combos: Array<{ modifiers: string[] }> = [];
+
+  for (const a of first) {
+    for (const b of second) {
+      combos.push({ modifiers: [a, b] });
+    }
+  }
+
+  return combos;
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function generateVariationsHtml(api: ComponentAPI): string {
+  const baseClass = `${PREFIX}${api.baseClass}`;
+  const element = api.element;
+  const title = capitalize(api.name);
+
+  const sections: string[] = [];
+
+  // Default section
+  sections.push(`
+    <div class="test-section">
+      <div class="test-section-title">Default</div>
+      <div class="test-row">
+        <${element} class="${baseClass}">Default</${element}>
+      </div>
+    </div>
+  `);
+
+  // Generate sections for each modifier
+  for (const [modName, modDef] of Object.entries(api.modifiers)) {
+    const sectionTitle = capitalize(modName);
+
+    if (modDef.values) {
+      const buttons: string[] = [];
+
+      if (modName === 'size') {
+        buttons.push(`<${element} class="${baseClass}">Default</${element}>`);
+      }
+      if (modName === 'variant') {
+        buttons.push(`<${element} class="${baseClass}">Primary</${element}>`);
+      }
+
+      for (const value of modDef.values) {
+        const modClass = `${baseClass}--${value}`;
+        const label = capitalize(value);
+        buttons.push(`<${element} class="${baseClass} ${modClass}">${label}</${element}>`);
+      }
+
+      sections.push(`
+    <div class="test-section">
+      <div class="test-section-title">${sectionTitle}</div>
+      <div class="test-row">
+        ${buttons.join('\n        ')}
+      </div>
+    </div>
+  `);
+    } else if (modDef.type === 'boolean') {
+      const modClass = `${baseClass}--${modName}`;
+      const content = modName === 'icon' ? '+' : 'Full Width';
+      const blockClass = modName === 'block' ? ' test-element--block' : '';
+
+      sections.push(`
+    <div class="test-section">
+      <div class="test-section-title">${sectionTitle}</div>
+      <div class="test-row">
+        <div class="${blockClass.trim()}">
+          <${element} class="${baseClass} ${modClass}">${content}</${element}>
+        </div>
+      </div>
+    </div>
+  `);
+    }
+  }
+
+  // States section
+  if (api.states && api.states.length > 0) {
+    const stateButtons: string[] = [];
+    stateButtons.push(`<${element} class="${baseClass}">Normal</${element}>`);
+
+    if (api.states.includes('hover')) {
+      stateButtons.push(`<${element} class="${baseClass} ${baseClass}--hover">Hover</${element}>`);
+    }
+    if (api.states.includes('focus')) {
+      stateButtons.push(`<${element} class="${baseClass} ${baseClass}--focus">Focus</${element}>`);
+    }
+    if (api.states.includes('active')) {
+      stateButtons.push(
+        `<${element} class="${baseClass} ${baseClass}--active">Active</${element}>`,
+      );
+    }
+    if (api.states.includes('disabled')) {
+      stateButtons.push(`<${element} class="${baseClass}" disabled>Disabled</${element}>`);
+    }
+
+    sections.push(`
+    <div class="test-section">
+      <div class="test-section-title">States</div>
+      <div class="test-row">
+        ${stateButtons.join('\n        ')}
+      </div>
+    </div>
+  `);
+  }
+
+  // Combinations section
+  const combos = generateCombinations(api);
+  if (combos.length > 0) {
+    const comboButtons = combos.map((combo) => {
+      const classes = combo.modifiers.map((m) => `${baseClass}--${m}`).join(' ');
+      const label = combo.modifiers.map((m) => capitalize(m)).join(' ');
+      const disabled = combo.disabled ? ' disabled' : '';
+      return `<${element} class="${baseClass} ${classes}"${disabled}>${label}</${element}>`;
+    });
+
+    sections.push(`
+    <div class="test-section">
+      <div class="test-section-title">Combinations</div>
+      <div class="test-grid">
+        ${comboButtons.join('\n        ')}
+      </div>
+    </div>
+  `);
+  }
+
+  return `
+    <div class="test-container">
+      <h1 class="test-title">${title}</h1>
+      ${sections.join('')}
+    </div>
+  `;
+}

package/src/testing/index.ts

@@ -0,0 +1,15 @@
+export type { ComponentAPI } from './api-types';
+export type { RhythmViolation } from './rhythm';
+export { scaffoldCss } from './scaffold';
+export { generateVariationsHtml } from './html-generator';
+export { validateGridRhythm } from './rhythm';
+export {
+  loadCss,
+  loadComponentApi,
+  loadDocsJson,
+  generateHtmlFromDocs,
+  setupVisualTest,
+  setupVisualTestFromApi,
+  setupVisualTestFromDocs,
+  saveForLostPixel,
+} from './page-setup';

package/src/testing/page-setup.ts

@@ -0,0 +1,131 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Page } from '@playwright/test';
+
+const LOSTPIXEL_DIR = resolve(__dirname, '../../.lostpixel');
+import type { ComponentAPI } from './api-types';
+import { generateVariationsHtml } from './html-generator';
+import { scaffoldCss } from './scaffold';
+
+interface DocsItem {
+  tag: string;
+  class: string;
+  text: string;
+  attrs?: Record<string, string>;
+}
+
+interface DocsExample {
+  html?: string;
+  items?: DocsItem[];
+  layout?: string;
+  title?: string;
+}
+
+interface DocsSection {
+  title: string;
+  examples: DocsExample[];
+}
+
+interface DocsJson {
+  sections: DocsSection[];
+}
+
+const DIST_PATH = resolve(__dirname, '../../dist');
+
+export function loadCss(filename = 'index.css'): string {
+  return readFileSync(resolve(DIST_PATH, filename), 'utf-8');
+}
+
+export function loadComponentApi(apiPath: string): ComponentAPI {
+  return JSON.parse(readFileSync(apiPath, 'utf-8'));
+}
+
+function renderItem(item: DocsItem): string {
+  const attrs = item.attrs
+    ? Object.entries(item.attrs)
+        .map(([k, v]) => (v === '' ? k : `${k}="${v}"`))
+        .join(' ')
+    : '';
+  const attrStr = attrs ? ` ${attrs}` : '';
+  return `<${item.tag} class="${item.class}"${attrStr}>${item.text}</${item.tag}>`;
+}
+
+export function loadDocsJson(docsPath: string): DocsJson {
+  return JSON.parse(readFileSync(docsPath, 'utf-8'));
+}
+
+export function generateHtmlFromDocs(docs: DocsJson): string {
+  const sections: string[] = [];
+
+  for (const section of docs.sections) {
+    const examples: string[] = [];
+
+    for (const example of section.examples) {
+      let html = '';
+
+      if (example.html) {
+        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;
+      }
+
+      if (html) {
+        examples.push(`<div class="test-example">${html}</div>`);
+      }
+    }
+
+    sections.push(`
+      <div class="test-section">
+        <div class="test-section-title">${section.title}</div>
+        ${examples.join('\n')}
+      </div>
+    `);
+  }
+
+  return `<div class="test-container">${sections.join('')}</div>`;
+}
+
+export async function setupVisualTest(
+  page: Page,
+  options: {
+    html: string;
+    css?: string;
+    includeTokens?: boolean;
+  },
+): Promise<void> {
+  const { html, css, includeTokens = true } = options;
+  const componentCss = includeTokens ? loadCss() : css || '';
+
+  const fullHtml = `
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <meta charset="utf-8">
+      <style>${scaffoldCss}</style>
+      <style>${componentCss}</style>
+    </head>
+    <body>${html}</body>
+    </html>
+  `;
+
+  await page.setContent(fullHtml);
+}
+
+export async function setupVisualTestFromApi(page: Page, apiPath: string): Promise<void> {
+  const api = loadComponentApi(apiPath);
+  const html = generateVariationsHtml(api);
+  await setupVisualTest(page, { html });
+}
+
+export async function setupVisualTestFromDocs(page: Page, docsPath: string): Promise<void> {
+  const docs = loadDocsJson(docsPath);
+  const html = generateHtmlFromDocs(docs);
+  await setupVisualTest(page, { html });
+}
+
+export async function saveForLostPixel(page: Page, name: string): Promise<void> {
+  mkdirSync(LOSTPIXEL_DIR, { recursive: true });
+  const screenshot = await page.screenshot({ fullPage: true });
+  writeFileSync(resolve(LOSTPIXEL_DIR, `${name}.png`), screenshot);
+}

package/src/testing/rhythm.ts

@@ -0,0 +1,146 @@
+import type { Page } from '@playwright/test';
+
+// Elements that are fluid containers (viewport-dependent)
+const SKIP_SELECTORS = [
+  'html',
+  'body',
+  'main',
+  'aside',
+  '.ui-sidebar',
+  '.ui-main',
+  '.ui-app-shell',
+  '.ui-drawer', // Fluid panel - adapts to container/viewport
+];
+
+// Inline elements that don't follow grid
+const INLINE_TAGS = [
+  'STRONG',
+  'B',
+  'EM',
+  'I',
+  'SMALL',
+  'SPAN',
+  'A',
+  'CODE',
+  'ABBR',
+  'CITE',
+  'Q',
+  'SUB',
+  'SUP',
+  'MARK',
+  'BR',
+  'WBR',
+];
+
+export interface RhythmViolation {
+  selector: string;
+  height: number;
+  expected: number;
+  offBy: number;
+}
+
+/**
+ * Validates that all elements in a component follow the 8px grid rhythm
+ * Throws an error if violations are found
+ */
+export async function validateGridRhythm(
+  page: Page,
+  componentName: string,
+): Promise<RhythmViolation[]> {
+  const violations = await page.evaluate(
+    ({ skipSelectors, inlineTags, component }) => {
+      // Get unit from CSS custom property (default 8px)
+      // Note: PostCSS prefixes --unit to --ui-unit in compiled CSS
+      const temp = document.createElement('div');
+      temp.style.cssText = 'position:absolute;visibility:hidden;width:var(--ui-unit, 8px)';
+      document.body.appendChild(temp);
+      const unit = temp.getBoundingClientRect().width || 8;
+      document.body.removeChild(temp);
+
+      const results: Array<{ selector: string; height: number; expected: number; offBy: number }> =
+        [];
+
+      // Target component elements
+      const selector = `.ui-${component}, .ui-${component} *`;
+      const elements = document.querySelectorAll(selector);
+
+      for (const el of elements) {
+        const tagName = el.tagName;
+
+        // Skip script, style, SVG internals, etc.
+        const upperTag = tagName.toUpperCase();
+        if (
+          [
+            'SCRIPT',
+            'STYLE',
+            'LINK',
+            'META',
+            'TITLE',
+            'HEAD',
+            'SVG',
+            'PATH',
+            'CIRCLE',
+            'RECT',
+            'LINE',
+            'POLYGON',
+            'POLYLINE',
+            'ELLIPSE',
+            'G',
+            'DEFS',
+            'USE',
+            'SYMBOL',
+            'CLIPPATH',
+            'MASK',
+            'PATTERN',
+            'IMAGE',
+            'TEXT',
+            'TSPAN',
+            'TEXTPATH',
+            'FOREIGNOBJECT',
+          ].includes(upperTag)
+        )
+          continue;
+
+        // Skip inline elements
+        if (inlineTags.includes(tagName)) continue;
+
+        // Skip BEM element children (__element) - only check blocks and modifiers
+        const classes = el.className?.toString?.() || '';
+        if (classes.includes('__')) continue;
+
+        // Skip fluid containers
+        if (skipSelectors.some((sel) => el.matches(sel))) continue;
+
+        const height = el.getBoundingClientRect().height;
+        // Skip zero-height and decorative lines (borders, dividers < half unit)
+        if (height === 0 || height < unit / 2) continue;
+
+        const remainder = height % unit;
+        const isAligned = remainder < 0.5 || remainder > unit - 0.5;
+
+        if (!isAligned) {
+          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,
+          });
+        }
+      }
+
+      return results;
+    },
+    { skipSelectors: SKIP_SELECTORS, inlineTags: INLINE_TAGS, component: componentName },
+  );
+
+  if (violations.length > 0) {
+    console.log(`Grid rhythm violations in ${componentName}:`);
+    console.table(violations);
+    throw new Error(
+      `Grid rhythm violations in ${componentName}:\n${JSON.stringify(violations, null, 2)}`,
+    );
+  }
+
+  return violations;
+}

package/src/testing/scaffold.ts

@@ -0,0 +1,50 @@
+export const scaffoldCss = `
+  html {
+    font-size: 16px;
+  }
+  body {
+    background-image:
+      linear-gradient(45deg, #f0f0f0 25%, transparent 25%),
+      linear-gradient(-45deg, #f0f0f0 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, #f0f0f0 75%),
+      linear-gradient(-45deg, transparent 75%, #f0f0f0 75%);
+    background-size: 12px 12px;
+    background-position: 0 0, 0 6px, 6px -6px, -6px 0px;
+    background-color: #fafafa;
+  }
+  .test-container {
+    padding: 1.5rem;
+  }
+  .test-title {
+    font-family: var(--ui-font-sans, system-ui, sans-serif);
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin-block-end: 1.5rem;
+  }
+  .test-section {
+    margin-block-end: 1.5rem;
+  }
+  .test-section-title {
+    font-family: var(--ui-font-sans, system-ui, sans-serif);
+    font-size: 0.75rem;
+    color: #666;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-block-end: 0.5rem;
+  }
+  .test-row {
+    display: flex;
+    gap: 1rem;
+    align-items: center;
+    flex-wrap: wrap;
+  }
+  .test-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(100px, max-content));
+    gap: 1rem;
+    align-items: start;
+  }
+  .test-element--block {
+    width: 200px;
+  }
+`;