@baukit/ui-tokens 0.7.2 → 0.7.3

package/src/eslint.ts

@@ -0,0 +1,283 @@
+import type { Rule } from 'eslint';
+import type { Node } from 'estree';
+
+import { findRawColor, isCssColorKeyword, type RawColorKind } from './color-literals.js';
+
+/** Options accepted by the `no-raw-color` rule. */
+export interface NoRawColorOptions {
+  /**
+   * Glob-like file patterns whose contents may declare raw colors. A token
+   * definition file belongs here. `*` matches within a path segment, `**`
+   * across segments.
+   */
+  readonly allowedFiles?: readonly string[];
+  /** Exact literal values that stay allowed everywhere, such as `transparent`. */
+  readonly allowedValues?: readonly string[];
+  /** Extra property or attribute names treated as style-like. */
+  readonly additionalStyleProperties?: readonly string[];
+  /** Report CSS color keywords such as `red`. Defaults to `true`. */
+  readonly reportKeywords?: boolean;
+}
+
+const DEFAULT_ALLOWED_VALUES = ['transparent', 'currentColor', 'inherit', 'none'];
+
+/**
+ * Property and attribute names whose values are styling input. Keyword matching
+ * is limited to these so that a route name or a test id is never reported.
+ */
+const STYLE_PROPERTY_NAMES = new Set([
+  'backgroundColor',
+  'background',
+  'borderColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'borderRightColor',
+  'borderTopColor',
+  'borderStartColor',
+  'borderEndColor',
+  'color',
+  'fill',
+  'stroke',
+  'shadowColor',
+  'textShadowColor',
+  'textDecorationColor',
+  'tintColor',
+  'placeholderTextColor',
+  'selectionColor',
+  'underlayColor',
+  'outlineColor',
+  'caretColor',
+  'colors',
+  'style',
+  'styles',
+  'theme',
+  'palette',
+  'gradient',
+  'boxShadow',
+  'textShadow',
+  'borderTop',
+  'borderBottom',
+  'borderLeft',
+  'borderRight',
+  'border',
+  'outline',
+]);
+
+/** Tagged-template tags whose contents are CSS. */
+const CSS_TEMPLATE_TAGS = new Set([
+  'css',
+  'styled',
+  'createGlobalStyle',
+  'keyframes',
+  'injectGlobal',
+]);
+
+function globToRegExp(pattern: string): RegExp {
+  let source = '';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === '*') {
+      if (pattern[index + 1] === '*') {
+        source += '.*';
+        index += 1;
+      } else {
+        source += '[^/]*';
+      }
+      continue;
+    }
+    if (character === '?') {
+      source += '[^/]';
+      continue;
+    }
+    source += character?.replace(/[.+^${}()|[\]\\]/g, '\\$&') ?? '';
+  }
+  return new RegExp(`(?:^|/)(?:${source})$`);
+}
+
+function isAllowedFile(filename: string, patterns: readonly string[]): boolean {
+  const normalized = filename.replaceAll('\\', '/');
+  return patterns.some((pattern) => globToRegExp(pattern).test(normalized));
+}
+
+interface EstreeParent {
+  readonly parent?: (Node & EstreeParent) | null;
+}
+
+type WithParent = Node & EstreeParent;
+
+function propertyKeyName(node: WithParent): string | undefined {
+  const parent = node.parent;
+  if (parent === undefined || parent === null) return undefined;
+  if (parent.type === 'Property' && parent.value === (node as Node)) {
+    const key = parent.key as WithParent;
+    if (key.type === 'Identifier') return key.name;
+    if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  }
+  return undefined;
+}
+
+/**
+ * Walks up from a literal to decide whether it lands in a styling position: a
+ * style-named property or JSX attribute, a CSS tagged template, or a nested
+ * object or array under one of those.
+ */
+function isStyleContext(node: WithParent, styleNames: ReadonlySet<string>): boolean {
+  let current: WithParent | null | undefined = node;
+  let child: WithParent | undefined;
+
+  while (current !== undefined && current !== null) {
+    if (current.type === 'TaggedTemplateExpression') {
+      const tag = current.tag as WithParent;
+      if (tag.type === 'Identifier' && CSS_TEMPLATE_TAGS.has(tag.name)) return true;
+      if (
+        tag.type === 'MemberExpression' &&
+        tag.object.type === 'Identifier' &&
+        CSS_TEMPLATE_TAGS.has(tag.object.name)
+      ) {
+        return true;
+      }
+    }
+
+    if (current.type === 'Property' && child !== undefined && current.value === (child as Node)) {
+      const name = propertyKeyName(child);
+      if (name !== undefined && styleNames.has(name)) return true;
+    }
+
+    const jsxName = jsxAttributeName(current);
+    if (jsxName !== undefined && styleNames.has(jsxName)) return true;
+
+    if (current.type === 'VariableDeclarator') {
+      const id = current.id as WithParent;
+      if (id.type === 'Identifier' && looksLikeStyleName(id.name)) return true;
+    }
+
+    if (isStyleSheetCall(current)) return true;
+
+    child = current;
+    current = current.parent;
+  }
+  return false;
+}
+
+interface JsxAttributeLike {
+  readonly type: string;
+  readonly name?: { readonly name?: string };
+}
+
+function jsxAttributeName(current: WithParent): string | undefined {
+  const candidate = current as unknown as JsxAttributeLike;
+  return candidate.type === 'JSXAttribute' ? candidate.name?.name : undefined;
+}
+
+function looksLikeStyleName(name: string): boolean {
+  return /(^|[a-z])(style|styles|theme|palette|colors?)$/i.test(name);
+}
+
+function isStyleSheetCall(node: WithParent): boolean {
+  if (node.type !== 'CallExpression') return false;
+  const callee = node.callee as WithParent;
+  return (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === 'StyleSheet' &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === 'create'
+  );
+}
+
+const MESSAGE_IDS: Record<RawColorKind, 'rawHex' | 'rawFunction' | 'rawKeyword'> = {
+  hex: 'rawHex',
+  function: 'rawFunction',
+  keyword: 'rawKeyword',
+};
+
+/**
+ * Reports CSS colors written directly in application code. Colors belong in the
+ * token definition, which the `allowedFiles` option exempts.
+ */
+export const noRawColor: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow raw CSS colors outside the design-token definition',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowedFiles: { type: 'array', items: { type: 'string' } },
+          allowedValues: { type: 'array', items: { type: 'string' } },
+          additionalStyleProperties: { type: 'array', items: { type: 'string' } },
+          reportKeywords: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      rawHex: 'Raw hex color "{{value}}". Use a design token instead.',
+      rawFunction: 'Raw {{value}}() color. Use a design token instead.',
+      rawKeyword: 'Raw CSS color keyword "{{value}}". Use a design token instead.',
+    },
+  },
+
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    const options = (context.options[0] ?? {}) as NoRawColorOptions;
+    const allowedFiles = options.allowedFiles ?? [];
+    const allowedValues = new Set(
+      [...DEFAULT_ALLOWED_VALUES, ...(options.allowedValues ?? [])].map((value) =>
+        value.toLowerCase(),
+      ),
+    );
+    const styleNames = new Set([
+      ...STYLE_PROPERTY_NAMES,
+      ...(options.additionalStyleProperties ?? []),
+    ]);
+    const reportKeywords = options.reportKeywords ?? true;
+
+    if (isAllowedFile(context.filename, allowedFiles)) return {};
+
+    const check = (node: WithParent, value: string): void => {
+      if (allowedValues.has(value.trim().toLowerCase())) return;
+
+      const styled = isStyleContext(node, styleNames);
+      const keywordsHere = reportKeywords && styled;
+      const match = findRawColor(value, keywordsHere);
+      if (match === undefined) return;
+      if (match.kind === 'keyword' && !isCssColorKeyword(value) && !styled) return;
+
+      context.report({
+        node,
+        messageId: MESSAGE_IDS[match.kind],
+        data: { value: match.text },
+      });
+    };
+
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string') check(node, node.value);
+      },
+      TemplateLiteral(node) {
+        const raw = node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join(' ');
+        check(node, raw);
+      },
+    };
+  },
+};
+
+/** Rules exported by this plugin, keyed by rule name. */
+export const rules = { 'no-raw-color': noRawColor };
+
+const plugin = { rules };
+
+/**
+ * Ready-made flat config. Spread it into a product's `eslint.config.js` and pass
+ * `allowedFiles` so the token definition may keep its color literals.
+ */
+export const configs = {
+  recommended: {
+    plugins: { '@baukit/ui-tokens': plugin },
+    rules: { '@baukit/ui-tokens/no-raw-color': 'error' },
+  },
+} as const;
+
+export default plugin;

package/src/example.ts

@@ -0,0 +1,61 @@
+import type { DesignTokens } from './schema.js';
+import { checkSemanticContrastMatrix, DEFAULT_SEMANTIC_CONTRAST_REQUIREMENTS } from './contrast.js';
+
+/** A deliberately small fixture that demonstrates the pipeline, not a design system. */
+export const exampleTokens = {
+  color: {
+    background: {
+      primary: { light: '#ffffff', dark: '#111111' },
+      elevated: { light: '#f5f5f5', dark: '#222222' },
+      accent: { light: '#005fcc', dark: '#66aaff' },
+    },
+    text: {
+      primary: { light: '#111111', dark: '#ffffff' },
+      muted: { light: '#595959', dark: '#b3b3b3' },
+      onAccent: { light: '#ffffff', dark: '#111111' },
+    },
+    border: {
+      primary: { light: '#767676', dark: '#888888' },
+    },
+    focus: {
+      ring: { light: '#005fcc', dark: '#66aaff' },
+    },
+    action: {
+      primary: { light: '#005fcc', dark: '#66aaff' },
+      onPrimary: { light: '#ffffff', dark: '#111111' },
+      secondary: { light: '#5f3dc4', dark: '#b197fc' },
+      onSecondary: { light: '#ffffff', dark: '#111111' },
+    },
+    status: {
+      success: { light: '#137333', dark: '#65d48b' },
+      onSuccess: { light: '#ffffff', dark: '#111111' },
+      warning: { light: '#8a4b00', dark: '#ffd166' },
+      onWarning: { light: '#ffffff', dark: '#111111' },
+      danger: { light: '#b3261e', dark: '#ff8a80' },
+      onDanger: { light: '#ffffff', dark: '#111111' },
+    },
+  },
+  typography: {
+    family: { body: 'Inter, sans-serif' },
+    size: { body: '1rem', title: '2rem' },
+    weight: { regular: 400, bold: 700 },
+    lineHeight: { body: 1.5, title: 1.2 },
+  },
+  space: { small: 8, medium: 16 },
+  radius: { small: 4, pill: 999 },
+  motion: {
+    duration: { fast: '120ms', normal: '240ms' },
+    easing: { standard: 'cubic-bezier(0.2, 0, 0, 1)' },
+  },
+  elevation: { raised: '0 2px 8px rgb(0 0 0 / 0.2)' },
+  contrastPairs: [
+    { foreground: 'color.text.primary', background: 'color.background.primary' },
+    { foreground: 'color.text.onAccent', background: 'color.background.accent' },
+  ],
+} as const satisfies DesignTokens;
+
+/** Example result for the package's default semantic contrast requirements. */
+export const exampleContrastViolations = checkSemanticContrastMatrix(
+  exampleTokens,
+  DEFAULT_SEMANTIC_CONTRAST_REQUIREMENTS,
+);

package/src/index.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  checkContrast,
+  contrastRatio,
+  exampleTokens,
+  parseTokens,
+  relativeLuminance,
+  toCssVariables,
+  toReactNative,
+  TokenValidationError,
+  validateTokens,
+  type DesignTokens,
+} from './index.js';
+
+const minimalTokens = {
+  color: {
+    background: { primary: { light: '#fff', dark: '#000' } },
+    text: { primary: { light: '#000', dark: '#fff' } },
+  },
+  typography: {
+    family: { body: 'Inter' },
+    size: { body: 16 },
+    weight: { regular: 400 },
+    lineHeight: { body: 1.5 },
+  },
+  space: { small: 8 },
+  radius: { small: 4 },
+  motion: { duration: { fast: 120 }, easing: { standard: 'linear' } },
+  elevation: { raised: 2 },
+  contrastPairs: [{ foreground: 'color.text.primary', background: 'color.background.primary' }],
+} as const satisfies DesignTokens;
+
+describe('token validation', () => {
+  it('accepts the example token set', () => {
+    expect(validateTokens(exampleTokens)).toEqual([]);
+    expect(parseTokens(exampleTokens)).toBe(exampleTokens);
+  });
+
+  it('reports path-qualified structural and scalar errors', () => {
+    const invalid = {
+      ...exampleTokens,
+      typography: {
+        ...exampleTokens.typography,
+        size: { body: -1 },
+      },
+      motion: {
+        ...exampleTokens.motion,
+        easing: { 'Bad Name': '' },
+      },
+    };
+    expect(validateTokens(invalid)).toEqual(
+      expect.arrayContaining([
+        {
+          path: '$.typography.size.body',
+          message: 'must be a valid positive dimension',
+        },
+        {
+          path: '$.motion.easing.Bad Name',
+          message: 'must start with a lowercase letter and contain only letters or digits',
+        },
+        { path: '$.motion.easing.Bad Name', message: 'must be a valid string' },
+      ]),
+    );
+  });
+
+  it('rejects invalid colors and unresolved contrast references with exact paths', () => {
+    const invalid = {
+      ...exampleTokens,
+      color: {
+        ...exampleTokens.color,
+        text: { primary: { light: 'black', dark: '#fff' } },
+      },
+      contrastPairs: [{ foreground: 'color.text.missing', background: 'color.background.primary' }],
+    };
+    expect(validateTokens(invalid)).toEqual(
+      expect.arrayContaining([
+        {
+          path: '$.color.text.primary.light',
+          message: 'must be a #RGB or #RRGGBB hexadecimal color',
+        },
+        {
+          path: '$.contrastPairs[0].foreground',
+          message: 'must reference an existing color token path',
+        },
+      ]),
+    );
+  });
+
+  it('throws an aggregate TokenValidationError from parseTokens', () => {
+    expect(() => parseTokens(null)).toThrow(TokenValidationError);
+    expect(() => parseTokens(null)).toThrow('$: must be an object');
+  });
+});
+
+describe('CSS compiler', () => {
+  it('emits exact deterministic CSS', () => {
+    expect(toCssVariables(minimalTokens)).toBe(`:root {
+  --bk-color-background-primary: #fff;
+  --bk-color-text-primary: #000;
+  --bk-elevation-raised: 2;
+  --bk-motion-duration-fast: 120;
+  --bk-motion-easing-standard: linear;
+  --bk-radius-small: 4;
+  --bk-space-small: 8;
+  --bk-typography-family-body: Inter;
+  --bk-typography-line-height-body: 1.5;
+  --bk-typography-size-body: 16;
+  --bk-typography-weight-regular: 400;
+}
+
+[data-theme="dark"] {
+  --bk-color-background-primary: #000;
+  --bk-color-text-primary: #fff;
+}
+`);
+  });
+
+  it('emits semantic variables and a dark override', () => {
+    const css = toCssVariables(exampleTokens);
+    expect(css).toContain('--bk-color-background-accent: #005fcc;');
+    expect(css).toContain('--bk-typography-line-height-body: 1.5;');
+    expect(css).toContain('--bk-color-background-accent: #66aaff;');
+    expect(css).toContain('[data-theme="dark"] {');
+    expect(css.endsWith('\n')).toBe(true);
+  });
+
+  it('is deterministic regardless of object insertion order', () => {
+    const reordered = {
+      ...exampleTokens,
+      space: { medium: 16, small: 8 },
+      color: {
+        ...exampleTokens.color,
+        text: exampleTokens.color.text,
+        background: exampleTokens.color.background,
+      },
+    } satisfies DesignTokens;
+    expect(toCssVariables(reordered)).toBe(toCssVariables(exampleTokens));
+  });
+});
+
+describe('React Native compiler', () => {
+  it('emits an exact typed constants module', () => {
+    expect(toReactNative(minimalTokens)).toBe(`// Generated by @baukit/ui-tokens. Do not edit.
+export const tokens = {
+  "color": {
+    "background": {
+      "primary": {
+        "dark": "#000",
+        "light": "#fff"
+      }
+    },
+    "text": {
+      "primary": {
+        "dark": "#fff",
+        "light": "#000"
+      }
+    }
+  },
+  "elevation": {
+    "raised": 2
+  },
+  "motion": {
+    "duration": {
+      "fast": 120
+    },
+    "easing": {
+      "standard": "linear"
+    }
+  },
+  "radius": {
+    "small": 4
+  },
+  "space": {
+    "small": 8
+  },
+  "typography": {
+    "family": {
+      "body": "Inter"
+    },
+    "lineHeight": {
+      "body": 1.5
+    },
+    "size": {
+      "body": 16
+    },
+    "weight": {
+      "regular": 400
+    }
+  }
+} as const;
+
+export type Tokens = typeof tokens;
+`);
+  });
+
+  it('emits a typed nested constants module without accessibility metadata', () => {
+    const output = toReactNative(exampleTokens);
+    expect(output).toContain(
+      '// Generated by @baukit/ui-tokens. Do not edit.\nexport const tokens = {',
+    );
+    expect(output).toContain('"primary": {\n        "dark": "#111111",');
+    expect(output).not.toContain('contrastPairs');
+    expect(output).toMatch(/as const;\n\nexport type Tokens = typeof tokens;\n$/u);
+  });
+
+  it('sorts nested objects deterministically', () => {
+    const reordered = {
+      ...exampleTokens,
+      radius: { pill: 999, small: 4 },
+    } satisfies DesignTokens;
+    expect(toReactNative(reordered)).toBe(toReactNative(exampleTokens));
+  });
+});
+
+describe('WCAG contrast', () => {
+  it('calculates the known black/white ratio of 21', () => {
+    expect(relativeLuminance('#000000')).toBe(0);
+    expect(relativeLuminance('#ffffff')).toBe(1);
+    expect(contrastRatio('#000', '#fff')).toBe(21);
+  });
+
+  it('accepts all declared example pairs', () => {
+    expect(checkContrast(exampleTokens)).toEqual([]);
+  });
+
+  it('reports actual ratios and thresholds for each failing theme', () => {
+    const failing: DesignTokens = {
+      ...exampleTokens,
+      color: {
+        ...exampleTokens.color,
+        text: {
+          ...exampleTokens.color.text,
+          weak: { light: '#777777', dark: '#777777' },
+        },
+      },
+      contrastPairs: [{ foreground: 'color.text.weak', background: 'color.background.primary' }],
+    };
+    const violations = checkContrast(failing);
+    expect(violations).toHaveLength(2);
+    expect(violations[0]).toMatchObject({
+      foreground: 'color.text.weak',
+      theme: 'light',
+      requiredRatio: 4.5,
+    });
+    expect(violations[0]?.ratio).toBeCloseTo(4.478, 3);
+    expect(violations[1]).toMatchObject({ theme: 'dark', requiredRatio: 4.5 });
+  });
+
+  it('uses the 3:1 threshold for declared large text', () => {
+    const largeText: DesignTokens = {
+      ...exampleTokens,
+      color: {
+        ...exampleTokens.color,
+        text: {
+          ...exampleTokens.color.text,
+          large: { light: '#767676', dark: '#888888' },
+        },
+      },
+      contrastPairs: [
+        {
+          foreground: 'color.text.large',
+          background: 'color.background.primary',
+          largeText: true,
+        },
+      ],
+    };
+    expect(checkContrast(largeText)).toEqual([]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './compiler.js';
+export * from './contrast.js';
+export * from './example.js';
+export * from './layout.js';
+export * from './schema.js';
+export * from './validation.js';