@baukit/ui-tokens 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baukit/ui-tokens",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Dependency-free design-token schema, validator, accessibility checker, and deterministic compiler for web and React Native.",
   "license": "MIT",
   "author": "Patrick Koss",
@@ -35,6 +35,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

package/src/color-literals.ts

@@ -0,0 +1,196 @@
+/**
+ * CSS color keywords recognized as raw colors. Keywords that double as ordinary
+ * English words in prop values are handled by requiring a style-like context.
+ */
+const CSS_COLOR_KEYWORDS = new Set([
+  'aliceblue',
+  'antiquewhite',
+  'aqua',
+  'aquamarine',
+  'azure',
+  'beige',
+  'bisque',
+  'black',
+  'blanchedalmond',
+  'blue',
+  'blueviolet',
+  'brown',
+  'burlywood',
+  'cadetblue',
+  'chartreuse',
+  'chocolate',
+  'coral',
+  'cornflowerblue',
+  'cornsilk',
+  'crimson',
+  'cyan',
+  'darkblue',
+  'darkcyan',
+  'darkgoldenrod',
+  'darkgray',
+  'darkgreen',
+  'darkgrey',
+  'darkkhaki',
+  'darkmagenta',
+  'darkolivegreen',
+  'darkorange',
+  'darkorchid',
+  'darkred',
+  'darksalmon',
+  'darkseagreen',
+  'darkslateblue',
+  'darkslategray',
+  'darkslategrey',
+  'darkturquoise',
+  'darkviolet',
+  'deeppink',
+  'deepskyblue',
+  'dimgray',
+  'dimgrey',
+  'dodgerblue',
+  'firebrick',
+  'floralwhite',
+  'forestgreen',
+  'fuchsia',
+  'gainsboro',
+  'ghostwhite',
+  'gold',
+  'goldenrod',
+  'gray',
+  'green',
+  'greenyellow',
+  'grey',
+  'honeydew',
+  'hotpink',
+  'indianred',
+  'indigo',
+  'ivory',
+  'khaki',
+  'lavender',
+  'lavenderblush',
+  'lawngreen',
+  'lemonchiffon',
+  'lightblue',
+  'lightcoral',
+  'lightcyan',
+  'lightgoldenrodyellow',
+  'lightgray',
+  'lightgreen',
+  'lightgrey',
+  'lightpink',
+  'lightsalmon',
+  'lightseagreen',
+  'lightskyblue',
+  'lightslategray',
+  'lightslategrey',
+  'lightsteelblue',
+  'lightyellow',
+  'lime',
+  'limegreen',
+  'linen',
+  'magenta',
+  'maroon',
+  'mediumaquamarine',
+  'mediumblue',
+  'mediumorchid',
+  'mediumpurple',
+  'mediumseagreen',
+  'mediumslateblue',
+  'mediumspringgreen',
+  'mediumturquoise',
+  'mediumvioletred',
+  'midnightblue',
+  'mintcream',
+  'mistyrose',
+  'moccasin',
+  'navajowhite',
+  'navy',
+  'oldlace',
+  'olive',
+  'olivedrab',
+  'orange',
+  'orangered',
+  'orchid',
+  'palegoldenrod',
+  'palegreen',
+  'paleturquoise',
+  'palevioletred',
+  'papayawhip',
+  'peachpuff',
+  'peru',
+  'pink',
+  'plum',
+  'powderblue',
+  'purple',
+  'rebeccapurple',
+  'red',
+  'rosybrown',
+  'royalblue',
+  'saddlebrown',
+  'salmon',
+  'sandybrown',
+  'seagreen',
+  'seashell',
+  'sienna',
+  'silver',
+  'skyblue',
+  'slateblue',
+  'slategray',
+  'slategrey',
+  'snow',
+  'springgreen',
+  'steelblue',
+  'tan',
+  'teal',
+  'thistle',
+  'tomato',
+  'turquoise',
+  'violet',
+  'wheat',
+  'white',
+  'whitesmoke',
+  'yellow',
+  'yellowgreen',
+]);
+
+const HEX_PATTERN = /#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})\b/i;
+const FUNCTIONAL_PATTERN = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\s*\(/i;
+const KEYWORD_SPLIT_PATTERN = /[^a-z]+/i;
+
+/** Kind of raw color found in a literal, used to pick the report message. */
+export type RawColorKind = 'hex' | 'function' | 'keyword';
+
+/** A raw color match with the exact text that triggered it. */
+export interface RawColorMatch {
+  readonly kind: RawColorKind;
+  readonly text: string;
+}
+
+function findKeyword(value: string): string | undefined {
+  for (const word of value.split(KEYWORD_SPLIT_PATTERN)) {
+    if (word !== '' && CSS_COLOR_KEYWORDS.has(word.toLowerCase())) return word;
+  }
+  return undefined;
+}
+
+/**
+ * Finds the first raw CSS color in a string. Hex and functional notations are
+ * unambiguous anywhere; keyword matches are only meaningful in a style-like
+ * context, which the caller decides.
+ */
+export function findRawColor(value: string, includeKeywords: boolean): RawColorMatch | undefined {
+  const hex = HEX_PATTERN.exec(value);
+  if (hex) return { kind: 'hex', text: hex[0] };
+
+  const functional = FUNCTIONAL_PATTERN.exec(value);
+  if (functional) return { kind: 'function', text: functional[0].replace(/\s*\($/, '') };
+
+  if (!includeKeywords) return undefined;
+  const keyword = findKeyword(value);
+  return keyword === undefined ? undefined : { kind: 'keyword', text: keyword };
+}
+
+/** True when the value is a CSS color keyword on its own. */
+export function isCssColorKeyword(value: string): boolean {
+  return CSS_COLOR_KEYWORDS.has(value.trim().toLowerCase());
+}

package/src/compiler.ts

@@ -0,0 +1,107 @@
+import type { DesignTokens, ThemeColor } from './schema.js';
+
+interface FlatToken {
+  readonly path: string;
+  readonly value: number | string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isThemeColor(value: unknown): value is ThemeColor {
+  return isRecord(value) && typeof value['light'] === 'string' && typeof value['dark'] === 'string';
+}
+
+function flattenColors(
+  value: unknown,
+  path: readonly string[],
+  theme: 'light' | 'dark',
+  output: FlatToken[],
+): void {
+  if (isThemeColor(value)) {
+    output.push({ path: path.join('-'), value: value[theme] });
+    return;
+  }
+  if (isRecord(value)) {
+    for (const key of Object.keys(value).sort()) {
+      flattenColors(value[key], [...path, key], theme, output);
+    }
+  }
+}
+
+function flattenScalars(value: unknown, path: readonly string[], output: FlatToken[]): void {
+  if (typeof value === 'string' || typeof value === 'number') {
+    output.push({ path: path.join('-'), value });
+    return;
+  }
+  if (isRecord(value)) {
+    for (const key of Object.keys(value).sort()) {
+      flattenScalars(value[key], [...path, key], output);
+    }
+  }
+}
+
+function kebabCase(path: string): string {
+  return path.replaceAll(/([a-z\d])([A-Z])/gu, '$1-$2').toLowerCase();
+}
+
+function declaration(token: FlatToken): string {
+  return `  --bk-${kebabCase(token.path)}: ${String(token.value)};`;
+}
+
+function comparePaths(left: FlatToken, right: FlatToken): number {
+  return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
+}
+
+/** Compiles a deterministic light root and dark-theme override block. */
+export function toCssVariables(tokens: DesignTokens): string {
+  const light: FlatToken[] = [];
+  const dark: FlatToken[] = [];
+  flattenColors(tokens.color, ['color'], 'light', light);
+  flattenColors(tokens.color, ['color'], 'dark', dark);
+  for (const group of ['typography', 'space', 'radius', 'motion', 'elevation'] as const) {
+    flattenScalars(tokens[group], [group], light);
+  }
+  light.sort(comparePaths);
+  dark.sort(comparePaths);
+
+  return [
+    ':root {',
+    ...light.map(declaration),
+    '}',
+    '',
+    '[data-theme="dark"] {',
+    ...dark.map(declaration),
+    '}',
+    '',
+  ].join('\n');
+}
+
+function sortDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item: unknown) => sortDeep(item));
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, sortDeep(value[key])]),
+    );
+  }
+  return value;
+}
+
+/** Compiles deterministic, nested TypeScript constants for React Native. */
+export function toReactNative(tokens: DesignTokens): string {
+  const runtimeTokens = {
+    color: tokens.color,
+    typography: tokens.typography,
+    space: tokens.space,
+    radius: tokens.radius,
+    motion: tokens.motion,
+    elevation: tokens.elevation,
+  };
+  const json = JSON.stringify(sortDeep(runtimeTokens), undefined, 2);
+  return `// Generated by @baukit/ui-tokens. Do not edit.\nexport const tokens = ${json} as const;\n\nexport type Tokens = typeof tokens;\n`;
+}

package/src/contrast.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  blendColors,
+  checkSemanticContrastMatrix,
+  chooseReadableForeground,
+  contrastRatio,
+  DEFAULT_SEMANTIC_CONTRAST_REQUIREMENTS,
+  exampleContrastViolations,
+  exampleTokens,
+  hexToRgb,
+  normalizeHexColor,
+  rgbToHex,
+  type DesignTokens,
+} from './index.js';
+
+describe('normalizeHexColor', () => {
+  it.each([
+    ['#000', '#000000'],
+    ['fff', '#ffffff'],
+    ['#AbC', '#aabbcc'],
+    ['12EfA0', '#12efa0'],
+    ['#ABCDEF', '#abcdef'],
+  ])('normalizes %s to %s', (input, expected) => {
+    expect(normalizeHexColor(input)).toBe(expected);
+  });
+
+  it.each(['', '#12', '#1234', '#12345', '#1234567', 'red', ' #fff', '#ggg'])(
+    'rejects unsupported input %j',
+    (input) => {
+      expect(() => normalizeHexColor(input)).toThrow('expected RGB or RRGGBB with an optional #');
+    },
+  );
+});
+
+describe('hex and RGB conversion', () => {
+  it('converts both directions at channel boundaries', () => {
+    expect(hexToRgb('#00ff7f')).toEqual({ r: 0, g: 255, b: 127 });
+    expect(rgbToHex({ r: 0, g: 255, b: 127 })).toBe('#00ff7f');
+  });
+
+  it('uses the same hexadecimal validation when converting to RGB', () => {
+    expect(() => hexToRgb('#abcd')).toThrow('Unsupported hexadecimal color');
+  });
+
+  it.each([
+    [{ r: -1, g: 0, b: 0 }, 'r'],
+    [{ r: 0, g: 256, b: 0 }, 'g'],
+    [{ r: 0, g: 0.5, b: 0 }, 'g'],
+    [{ r: 0, g: 0, b: Number.NaN }, 'b'],
+    [{ r: 0, g: 0, b: Number.POSITIVE_INFINITY }, 'b'],
+  ] as const)('rejects invalid RGB channels', (color, channel) => {
+    expect(() => rgbToHex(color)).toThrow(`RGB channel ${channel}`);
+  });
+});
+
+describe('blendColors', () => {
+  it('blends opaque colors and rounds channels', () => {
+    expect(blendColors('#ffffff', '#000000', 0.5)).toBe('#808080');
+  });
+
+  it('clamps ratios outside the unit interval', () => {
+    expect(blendColors('#fff', '#000', -0.1)).toBe('#000000');
+    expect(blendColors('#fff', '#000', 1.1)).toBe('#ffffff');
+    expect(blendColors('#fff', '#000', 0)).toBe('#000000');
+    expect(blendColors('#fff', '#000', 1)).toBe('#ffffff');
+  });
+
+  it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
+    'rejects a non-finite ratio %s',
+    (ratio) => {
+      expect(() => blendColors('#fff', '#000', ratio)).toThrow('Blend ratio must be finite');
+    },
+  );
+
+  it('rejects invalid colors', () => {
+    expect(() => blendColors('white', '#000', 0.5)).toThrow('Unsupported hexadecimal color');
+  });
+});
+
+describe('chooseReadableForeground', () => {
+  it('returns the first candidate that meets the requested ratio', () => {
+    const result = chooseReadableForeground('#ffffff', ['#777777', '#000000'], 4.5);
+
+    expect(result.foreground).toBe('#000000');
+    expect(result.ratio).toBe(21);
+    expect(result.meetsThreshold).toBe(true);
+  });
+
+  it('normalizes and returns the first passing candidate', () => {
+    const result = chooseReadableForeground('FFFFFF', ['#000', '#111111'], 4.5);
+
+    expect(result.foreground).toBe('#000000');
+    expect(result.meetsThreshold).toBe(true);
+  });
+
+  it('returns the best candidate and achieved ratio when none meets the threshold', () => {
+    const result = chooseReadableForeground('#777777', ['#888888', '#999999'], 7);
+
+    expect(result.foreground).toBe('#999999');
+    expect(result.ratio).toBeCloseTo(1.5718, 4);
+    expect(result.meetsThreshold).toBe(false);
+  });
+
+  it('accepts the minimum and maximum possible contrast thresholds', () => {
+    expect(chooseReadableForeground('#fff', ['#fff'], 1).meetsThreshold).toBe(true);
+    expect(chooseReadableForeground('#fff', ['#000'], 21).meetsThreshold).toBe(true);
+  });
+
+  it('rejects an empty candidate list', () => {
+    expect(() => chooseReadableForeground('#fff', [], 4.5)).toThrow(
+      'must contain at least one color',
+    );
+  });
+
+  it.each([0.99, 21.01, Number.NaN, Number.POSITIVE_INFINITY])(
+    'rejects an invalid minimum ratio %s',
+    (minimumRatio) => {
+      expect(() => chooseReadableForeground('#fff', ['#000'], minimumRatio)).toThrow(
+        'Minimum contrast ratio must be finite and between 1 and 21',
+      );
+    },
+  );
+
+  it('rejects invalid background and candidate colors', () => {
+    expect(() => chooseReadableForeground('white', ['#000'], 4.5)).toThrow(
+      'Unsupported hexadecimal color',
+    );
+    expect(() => chooseReadableForeground('#fff', ['black'], 4.5)).toThrow(
+      'Unsupported hexadecimal color',
+    );
+    expect(() => chooseReadableForeground('#fff', ['#000', 'black'], 4.5)).toThrow(
+      'Unsupported hexadecimal color',
+    );
+  });
+});
+
+describe('checkSemanticContrastMatrix', () => {
+  it('passes the documented default matrix for the example tokens', () => {
+    expect(DEFAULT_SEMANTIC_CONTRAST_REQUIREMENTS).toHaveLength(13);
+    expect(exampleContrastViolations).toEqual([]);
+  });
+
+  it('reports a failing pair in exactly one theme', () => {
+    const tokens: DesignTokens = {
+      ...exampleTokens,
+      color: {
+        ...exampleTokens.color,
+        text: {
+          ...exampleTokens.color.text,
+          primary: { light: '#777777', dark: '#ffffff' },
+        },
+      },
+    };
+    const requirement = {
+      foregroundRole: 'color.text.primary',
+      backgroundRole: 'color.background.primary',
+      minimumRatio: 4.5,
+    } as const;
+
+    const violations = checkSemanticContrastMatrix(tokens, [requirement]);
+
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toMatchObject({
+      ...requirement,
+      theme: 'light',
+    });
+    expect(violations[0]?.achievedRatio).toBeCloseTo(contrastRatio('#777', '#fff'), 10);
+  });
+
+  it('reports every failing requirement in both themes', () => {
+    const requirements = [
+      {
+        foregroundRole: 'color.text.primary',
+        backgroundRole: 'color.background.primary',
+        minimumRatio: 21,
+      },
+      {
+        foregroundRole: 'color.text.muted',
+        backgroundRole: 'color.background.primary',
+        minimumRatio: 21,
+      },
+    ] as const;
+
+    expect(checkSemanticContrastMatrix(exampleTokens, requirements)).toHaveLength(4);
+  });
+
+  it('accepts an empty matrix and the minimum possible ratio', () => {
+    expect(checkSemanticContrastMatrix(exampleTokens, [])).toEqual([]);
+    expect(
+      checkSemanticContrastMatrix(exampleTokens, [
+        {
+          foregroundRole: 'color.text.primary',
+          backgroundRole: 'color.background.primary',
+          minimumRatio: 1,
+        },
+      ]),
+    ).toEqual([]);
+  });
+
+  it('rejects missing role paths and invalid minimum ratios', () => {
+    expect(() =>
+      checkSemanticContrastMatrix(exampleTokens, [
+        {
+          foregroundRole: 'color.text.missing',
+          backgroundRole: 'color.background.primary',
+          minimumRatio: 4.5,
+        },
+      ]),
+    ).toThrow('does not reference a color token');
+    expect(() =>
+      checkSemanticContrastMatrix(exampleTokens, [
+        {
+          foregroundRole: 'text.primary',
+          backgroundRole: 'color.background.primary',
+          minimumRatio: 4.5,
+        },
+      ]),
+    ).toThrow('must start with "color."');
+    for (const minimumRatio of [0.99, 21.01, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(() =>
+        checkSemanticContrastMatrix(exampleTokens, [
+          {
+            foregroundRole: 'color.text.primary',
+            backgroundRole: 'color.background.primary',
+            minimumRatio,
+          },
+        ]),
+      ).toThrow('Minimum contrast ratio must be finite and between 1 and 21');
+    }
+  });
+});