Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
14.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

import {describe, expect, it} from 'vitest';
import {defineTheme, generateThemeRules} from './defineTheme';
import {
  resolveThemeToken,
  resolveThemeTokens,
  tokenVar,
  tokenVars,
} from './tokens';
import {colorDefaults} from './tokens.stylex';
import {domainTokenDefaults} from './domainTokens';

const testTheme = defineTheme({
  name: 'test',
  tokens: {
    '--color-accent': ['#AA0000', '#FF5555'],
    '--color-neutral': ['rgba(5, 54, 89, 0.1)', 'rgba(223, 226, 229, 0.2)'],
    '--spacing-4': '20px',
  },
});

describe('tokenVar', () => {
  it('returns a CSS var() reference for known token names', () => {
    expect(tokenVar('--color-text-primary')).toBe('var(--color-text-primary)');
  });

  it('returns a CSS var() reference for custom token names', () => {
    expect(tokenVar('--app-custom-token')).toBe('var(--app-custom-token)');
  });
});

describe('tokenVars', () => {
  it('contains var() references for known tokens', () => {
    expect(tokenVars['--color-text-primary']).toBe('var(--color-text-primary)');
    expect(tokenVars['--spacing-4']).toBe('var(--spacing-4)');
  });
});

describe('resolveThemeTokens', () => {
  it('resolves defaults when no theme is provided', () => {
    const tokens = resolveThemeTokens(null, {mode: 'light'});
    expect(tokens['--color-text-primary']).toBe('#0A1317');
    expect(tokens['--spacing-1']).toBe('0.25rem');
    expect(tokens['--border-width']).toBe('1px');
  });

  it('resolves --border-width when overridden in defineTheme', () => {
    const arcadeTheme = defineTheme({
      name: 'arcade',
      tokens: {
        '--border-width': '2px',
      },
    });
    const tokens = resolveThemeTokens(arcadeTheme, {mode: 'light'});
    expect(tokens['--border-width']).toBe('2px');
  });

  it('resolves tuple overrides using original input tokens', () => {
    const light = resolveThemeTokens(testTheme, {mode: 'light'});
    const dark = resolveThemeTokens(testTheme, {mode: 'dark'});

    expect(light['--color-accent']).toBe('#AA0000');
    expect(dark['--color-accent']).toBe('#FF5555');
  });

  it('resolves tuple overrides with nested comma values', () => {
    const light = resolveThemeTokens(testTheme, {mode: 'light'});
    const dark = resolveThemeTokens(testTheme, {mode: 'dark'});

    expect(light['--color-neutral']).toBe('rgba(5, 54, 89, 0.1)');
    expect(dark['--color-neutral']).toBe('rgba(223, 226, 229, 0.2)');
  });

  it('resolves built theme light-dark() strings without __inputTokens', () => {
    const builtTheme = {
      name: 'built',
      __built: true,
      tokens: {
        '--color-neutral':
          'light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))',
      },
    } as const;

    const light = resolveThemeTokens(builtTheme, {mode: 'light'});
    const dark = resolveThemeTokens(builtTheme, {mode: 'dark'});

    expect(light['--color-neutral']).toBe('rgba(5, 54, 89, 0.1)');
    expect(dark['--color-neutral']).toBe('rgba(223, 226, 229, 0.2)');
  });

  it('resolves single-value overrides unchanged', () => {
    const tokens = resolveThemeTokens(testTheme, {mode: 'light'});
    expect(tokens['--spacing-4']).toBe('20px');
  });
});

describe('resolveThemeToken', () => {
  it('resolves one token', () => {
    expect(resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'})).toBe(
      '#FF5555',
    );
  });

  it('resolves the exit curve to its accelerating default and to an override', () => {
    // No rise at the start (y1 = 0): an exit moves off from rest and leaves
    // fast, so its travel stays visible for the whole duration.
    expect(resolveThemeToken(null, '--ease-exit', {mode: 'light'})).toBe(
      'cubic-bezier(0.3, 0, 0.6, 0.6)',
    );
    const snappyExit = defineTheme({
      name: 'snappy-exit',
      tokens: {'--ease-exit': 'ease-in'},
    });
    expect(resolveThemeToken(snappyExit, '--ease-exit', {mode: 'dark'})).toBe(
      'ease-in',
    );
  });

  it('returns fallback for unknown token names', () => {
    expect(
      resolveThemeToken(testTheme, '--missing-token', {
        mode: 'dark',
        fallback: 'fallback',
      }),
    ).toBe('fallback');
  });

  it('returns empty string for unknown token names without fallback', () => {
    expect(
      resolveThemeToken(testTheme, '--missing-token', {mode: 'dark'}),
    ).toBe('');
  });
});

describe('resolveThemeTokens — reference resolution', () => {
  it('resolves a token that references another token to a raw value', () => {
    const theme = defineTheme({
      name: 'ref',
      tokens: {
        '--color-accent': ['#0058D2', '#BBC2FF'],
        '--color-text-accent': 'var(--color-accent)',
      },
    });

    const light = resolveThemeTokens(theme, {mode: 'light'});
    const dark = resolveThemeTokens(theme, {mode: 'dark'});

    expect(light['--color-text-accent']).toBe('#0058D2');
    expect(dark['--color-text-accent']).toBe('#BBC2FF');
  });

  it('resolves reference chains iteratively', () => {
    const theme = defineTheme({
      name: 'chain',
      tokens: {
        '--color-accent': ['#112233', '#445566'],
        '--color-icon-accent': 'var(--color-accent)',
        '--color-text-accent': 'var(--color-icon-accent)',
      },
    });

    const light = resolveThemeTokens(theme, {mode: 'light'});
    expect(light['--color-icon-accent']).toBe('#112233');
    expect(light['--color-text-accent']).toBe('#112233');
  });

  it('uses the var() fallback when the referenced token is unknown', () => {
    const theme = defineTheme({
      name: 'fallback',
      tokens: {
        '--color-text-accent': 'var(--not-a-token, #ABCDEF)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    expect(tokens['--color-text-accent']).toBe('#ABCDEF');
  });

  it('leaves an unresolvable reference as a literal var()', () => {
    const theme = defineTheme({
      name: 'unresolvable',
      tokens: {
        '--color-text-accent': 'var(--not-a-token)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    expect(tokens['--color-text-accent']).toBe('var(--not-a-token)');
  });

  it('does not loop forever on a reference cycle', () => {
    const theme = defineTheme({
      name: 'cycle',
      tokens: {
        '--color-text-accent': 'var(--color-icon-accent)',
        '--color-icon-accent': 'var(--color-text-accent)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    // The cycle collapses to a literal reference rather than hanging.
    expect(tokens['--color-text-accent']).toContain('var(');
    expect(tokens['--color-icon-accent']).toContain('var(');
  });
});

describe('resolveThemeTokens — CSS color functions', () => {
  it('evaluates color-mix with transparent to an rgba() value', () => {
    const theme = defineTheme({
      name: 'mix',
      tokens: {
        '--color-accent': ['#0058D2', '#BBC2FF'],
        '--color-accent-muted':
          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
      },
    });

    const light = resolveThemeTokens(theme, {mode: 'light'});
    const dark = resolveThemeTokens(theme, {mode: 'dark'});

    expect(light['--color-accent-muted']).toBe('rgba(0, 88, 210, 0.2)');
    expect(dark['--color-accent-muted']).toBe('rgba(187, 194, 255, 0.2)');
  });

  it('resolves the muted token inside a light-dark() tuple per mode', () => {
    const theme = defineTheme({
      name: 'ld-mix',
      tokens: {
        '--color-accent': ['#FF0000', '#00FF00'],
        '--color-accent-muted': [
          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
          'color-mix(in srgb, var(--color-accent) 25%, transparent)',
        ],
      },
    });

    const light = resolveThemeTokens(theme, {mode: 'light'});
    const dark = resolveThemeTokens(theme, {mode: 'dark'});

    expect(light['--color-accent-muted']).toBe('rgba(255, 0, 0, 0.2)');
    expect(dark['--color-accent-muted']).toBe('rgba(0, 255, 0, 0.25)');
  });

  it('mixes two opaque colors by weight', () => {
    const theme = defineTheme({
      name: 'two-color',
      tokens: {
        '--color-neutral': 'color-mix(in srgb, #000000, #FFFFFF)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    expect(tokens['--color-neutral']).toBe('#808080');
  });

  it('mixes two opaque colors with an explicit percentage', () => {
    const theme = defineTheme({
      name: 'weighted',
      tokens: {
        '--color-neutral': 'color-mix(in srgb, #000000 25%, #FFFFFF)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    expect(tokens['--color-neutral']).toBe('#BFBFBF');
  });

  it('preserves an unsupported color space rather than guessing', () => {
    const theme = defineTheme({
      name: 'oklab',
      tokens: {
        '--color-accent': ['#0058D2', '#BBC2FF'],
        '--color-neutral':
          'color-mix(in oklab, var(--color-accent), black 15%)',
      },
    });

    const tokens = resolveThemeTokens(theme, {mode: 'light'});
    // var() still resolves; the unsupported mix stays as a color-mix() expression.
    expect(tokens['--color-neutral']).toContain('color-mix(in oklab');
    expect(tokens['--color-neutral']).toContain('#0058D2');
  });
});

describe('resolveThemeTokens — generated themes end to end', () => {
  it('resolves derived accent tokens from defineTheme({color}) to raw values', () => {
    const theme = defineTheme({name: 'brand', color: {accent: '#0064E0'}});

    const light = resolveThemeTokens(theme, {mode: 'light'});
    const dark = resolveThemeTokens(theme, {mode: 'dark'});

    const isConcreteColor = (value: string): boolean => /^(#|rgb)/.test(value);

    for (const key of [
      '--color-accent',
      '--color-text-accent',
      '--color-icon-accent',
      '--color-accent-muted',
    ]) {
      expect(isConcreteColor(light[key])).toBe(true);
      expect(isConcreteColor(dark[key])).toBe(true);
      expect(light[key]).not.toContain('var(');
      expect(light[key]).not.toContain('color-mix');
    }

    // The derived accent tokens resolve to the base accent.
    expect(light['--color-text-accent']).toBe(light['--color-accent']);
    expect(light['--color-icon-accent']).toBe(light['--color-accent']);
  });
});

describe('focus outline tokens', () => {
  it('default to the accent ring from Design Conventions', () => {
    const tokens = resolveThemeTokens(null, {mode: 'light'});

    expect(tokens['--focus-outline-width']).toBe('2px');
    expect(tokens['--focus-outline-style']).toBe('solid');
    expect(tokens['--focus-outline-offset']).toBe('3px');
    // Tracks the theme's accent unless a theme says otherwise.
    expect(tokens['--focus-outline-color']).toBe(tokens['--color-accent']);
  });

  it('follows a theme accent without an explicit focus override', () => {
    const theme = defineTheme({name: 'brand', color: {accent: '#AA0000'}});
    const tokens = resolveThemeTokens(theme, {mode: 'light'});

    expect(tokens['--focus-outline-color']).toBe(tokens['--color-accent']);
    expect(tokens['--focus-outline-color']).not.toContain('var(');
  });

  it('takes an explicit ring over the accent', () => {
    const theme = defineTheme({
      name: 'brand',
      color: {accent: '#AA0000'},
      tokens: {
        '--focus-outline-color': '#00FF00',
        '--focus-outline-width': '4px',
        '--focus-outline-offset': '0px',
      },
    });
    const tokens = resolveThemeTokens(theme, {mode: 'light'});

    expect(tokens['--focus-outline-color']).toBe('#00FF00');
    expect(tokens['--focus-outline-width']).toBe('4px');
    expect(tokens['--focus-outline-offset']).toBe('0px');
  });
});

describe('resolveThemeTokens and derived status roles', () => {
  it('resolves an unset status role to the value the theme CSS derives (INV17)', () => {
    const theme = defineTheme({
      name: 'derived-status',
      tokens: {'--color-success': '#3FB950'},
    });
    const css = generateThemeRules(theme).join('\n');
    const emitted =
      /--color-text-success: light-dark\((#[0-9A-F]{6}), (#[0-9A-F]{6})\)/.exec(
        css,
      );
    expect(emitted).not.toBeNull();
    expect(
      resolveThemeToken(theme, '--color-text-success', {mode: 'light'}),
    ).toBe(emitted![1]);
    expect(
      resolveThemeToken(theme, '--color-text-success', {mode: 'dark'}),
    ).toBe(emitted![2]);
    // Icon and border follow the derived text role.
    expect(
      resolveThemeToken(theme, '--color-icon-success', {mode: 'light'}),
    ).toBe(emitted![1]);
  });

  it('keeps a status role the theme sets', () => {
    const theme = defineTheme({
      name: 'set-status',
      tokens: {'--color-success': '#3FB950', '--color-text-success': '#123456'},
    });
    expect(
      resolveThemeToken(theme, '--color-text-success', {mode: 'light'}),
    ).toBe('#123456');
  });
});

// INV10 governs only the colour tokens Astryx defines. The check reads Astryx's
// own defaults, never consumer, application, or theme-author variables.
describe('colour token name grammar (architecture:theme-tokens INV10)', () => {
  const property = '(?:text|icon|background|border)';
  const intent = '(?:accent|neutral|info|success|warning|error)';
  const hue = '(?:blue|cyan|gray|green|orange|pink|purple|red|teal|yellow)';
  const emphasis = '(?:primary|secondary|disabled|emphasized)';
  const surface = '(?:surface|body|card|popover|muted|inverted)';
  const variant = '(?:-(?:muted|emphasized|hover|pressed|inverted))?';
  const shapes = [
    // 1 and 3: property first, then role, then an optional variant.
    `^--color-${property}-(?:${emphasis}|${intent}|${surface}|${hue})${variant}$`,
    // 2 and 3: the intent's own colour, then an optional variant.
    `^--color-${intent}${variant}$`,
    // 4: content on a fill.
    `^--color-on-(?:${intent}${variant}|dark|light)$`,
    // 5: domain layers.
    '^--color-(?:data|syntax)-[a-z0-9-]+$',
  ].map(source => new RegExp(source));
  const utilityNames = new Set([
    '--color-border',
    '--color-overlay',
    '--color-overlay-hover',
    '--color-overlay-pressed',
    '--color-shadow',
    '--color-skeleton',
    '--color-track',
    '--color-tint-hover',
  ]);
  const colourNames = [
    ...Object.keys(colorDefaults),
    ...Object.keys(domainTokenDefaults),
  ].filter(name => name.startsWith('--color-'));

  it('checks a non-empty colour vocabulary', () => {
    expect(colourNames.length).toBeGreaterThan(50);
  });

  it('gives every colour token Astryx defines one of the five shapes', () => {
    const misfits = colourNames.filter(
      name =>
        !utilityNames.has(name) && !shapes.some(shape => shape.test(name)),
    );
    expect(misfits).toEqual([]);
  });

  it('rejects names outside the grammar', () => {
    for (const name of [
      '--color-status-foreground-success',
      '--color-success-text',
      '--color-foreground-error',
      '--color-success-on',
    ]) {
      expect(shapes.some(shape => shape.test(name))).toBe(false);
    }
  });
});