Skip to content

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

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

import {createHash} from 'node:crypto';
import {describe, expect, it} from 'vitest';
import {
  COMPACT_11_STOPS,
  DEFAULT_21_STOPS,
  PALETTE_RECIPE,
  generatePaletteSet,
  generateTonalPalette,
  perceptualDelta,
  validateStops,
} from './generator.mjs';
import {hexToOklch} from './color.mjs';

const families = [
  {id: 'neutral', name: 'Neutral', seed: '#777777', kind: 'neutral'},
  {id: 'blue', name: 'Blue', seed: '#0074e2'},
  {id: 'orange', name: 'Orange', seed: '#d57113'},
];

function candidateDigest(request) {
  const candidate = generateTonalPalette(request);
  return createHash('sha256')
    .update(`${JSON.stringify(candidate, null, 2)}\n`)
    .digest('hex');
}

describe('astryx-oklch-v1 palette generator', () => {
  it('returns directly usable candidate data without filesystem work', () => {
    const candidate = generateTonalPalette({
      families: [families[1]],
      stops: [40],
    });

    expect(candidate).toMatchObject({
      schemaVersion: 1,
      status: 'candidate',
      recipe: 'astryx-oklch-v1',
    });
    expect(candidate.palette.blue.light[40]).toMatch(/^#[0-9a-f]{6}$/);
    expect(candidate.palette.blue.dark[40]).toMatch(/^#[0-9a-f]{6}$/);
    expect(candidate.black).toBe('#000000');
    expect(candidate.white).toBe('#ffffff');
    expect(candidate.stops).toEqual([40]);
  });

  it('locks the normative recipe fixtures', () => {
    expect(candidateDigest({families})).toBe(
      '11c40191d508274d89d631bb4e1cb662f70ff0dce6c0dec101c317f9f69d3e25',
    );
    expect(
      candidateDigest({
        modeStrategy: 'light-only',
        stops: [20, 50, 80],
        families: [
          {
            id: 'blue',
            name: 'Blue',
            seed: '#0074e2',
            anchors: [
              {
                mode: 'light',
                stop: 50,
                color: '#1682d5',
                policy: 'exact',
              },
            ],
          },
        ],
      }),
    ).toBe('c42929be3c4b5cb857cada078f62bb5a2242c1a22cfa4ae7546a18592540f7f3');
    expect(
      candidateDigest({
        modeStrategy: 'dark-only',
        stops: [40],
        families: [{id: 'red', name: 'Red', seed: '#d62830'}],
      }),
    ).toBe('88d3d69865c74c7fb14347b9967575285a7d44ab893087a08bc842bb66b29bbb');
    expect(
      candidateDigest({
        stops: [60, 80, 95],
        families: [
          {id: 'green', name: 'Green', seed: '#358a3a'},
          {id: 'teal', name: 'Teal', seed: '#0c7365'},
          {id: 'cyan', name: 'Cyan', seed: '#0c6f82'},
        ],
      }),
    ).toBe('873821574fdbe3357304dbc06986bd2e5ec88af80d0f36305626fd826c3cf07b');
  });

  it('defaults to 21 stops while allowing authors to omit endpoints', () => {
    expect(generatePaletteSet({families: [families[1]]}).request.stops).toEqual(
      DEFAULT_21_STOPS,
    );
    expect(DEFAULT_21_STOPS).toHaveLength(21);
    expect(DEFAULT_21_STOPS[0]).toBe(0);
    expect(DEFAULT_21_STOPS.at(-1)).toBe(100);
    expect(
      generatePaletteSet({families: [families[1]], stops: [15, 40, 72]}).request
        .stops,
    ).toEqual([15, 40, 72]);
    expect(
      generatePaletteSet({families: [families[1]], stops: [40]}).families[0]
        .light.colors,
    ).toEqual({40: expect.stringMatching(/^#[0-9a-f]{6}$/)});
  });

  it('keeps shared stop values stable across full, compact, and custom layouts', () => {
    const family = {id: 'blue', name: 'Blue', seed: '#0074e2'};
    const full = generateTonalPalette({
      stops: [...DEFAULT_21_STOPS],
      families: [family],
    });
    const compact = generateTonalPalette({
      stops: [...COMPACT_11_STOPS],
      families: [family],
    });
    const custom = generateTonalPalette({
      stops: [12.5, 50, 80],
      families: [family],
    });

    expect(custom.stops).toEqual([12.5, 50, 80]);
    expect(custom.stops.map(stop => custom.palette.blue.light[stop])).toEqual([
      custom.palette.blue.light[12.5],
      custom.palette.blue.light[50],
      custom.palette.blue.light[80],
    ]);

    for (const mode of ['light', 'dark']) {
      for (const stop of COMPACT_11_STOPS) {
        expect(compact.palette.blue[mode][stop]).toBe(
          full.palette.blue[mode][stop],
        );
      }
      expect(custom.palette.blue[mode][50]).toBe(full.palette.blue[mode][50]);
      expect(custom.palette.blue[mode][80]).toBe(full.palette.blue[mode][80]);
      expect(custom.palette.blue[mode][12.5]).toMatch(/^#[0-9a-f]{6}$/);
    }
  });

  it('keeps default endpoints black and white and rejects tinted endpoint anchors', () => {
    const candidate = generateTonalPalette({families: [families[1]]});
    for (const mode of ['light', 'dark']) {
      expect(candidate.palette.blue[mode][0]).toBe('#000000');
      expect(candidate.palette.blue[mode][100]).toBe('#ffffff');
    }
    expect(() =>
      generateTonalPalette({
        families: [
          {
            ...families[1],
            anchors: [
              {
                mode: 'light',
                stop: 0,
                color: '#001122',
                policy: 'exact',
              },
            ],
          },
        ],
      }),
    ).toThrow('reserved for exact black');
  });

  it('rejects invalid stop layouts without prescribing a count', () => {
    expect(() => validateStops([])).toThrow('at least one stop');
    expect(() => validateStops([0, 40, 40, 100])).toThrow(
      'unique and strictly increasing',
    );
    expect(() => validateStops([-1, 50])).toThrow('from 0 to 100');
    expect(() => validateStops([0, Number.NaN, 100])).toThrow('finite number');
    expect(validateStops([0.5, 37.25, 99.75])).toEqual([0.5, 37.25, 99.75]);
  });

  it('uses literal stop tones in dark mode', () => {
    const candidate = generateTonalPalette({
      modeStrategy: 'light-and-dark',
      stops: [0, 5, 100],
      families: [families[1]],
    });

    expect(candidate.palette.blue.light[0]).toBe('#000000');
    expect(candidate.palette.blue.dark[0]).toBe('#000000');
    expect(candidate.palette.blue.dark[5]).toBe('#000f30');
    expect(candidate.palette.blue.light[100]).toBe('#ffffff');
    expect(candidate.palette.blue.dark[100]).toBe('#ffffff');
  });

  it('preserves exact anchors and rejects anchors outside the stop layout', () => {
    const result = generatePaletteSet({
      modeStrategy: 'light-only',
      stops: [20, 50, 80],
      families: [
        {
          id: 'blue',
          name: 'Blue',
          seed: '#0074e2',
          anchors: [
            {
              mode: 'light',
              stop: 50,
              color: '#1682d5',
              policy: 'exact',
            },
          ],
        },
      ],
    });

    expect(result.families[0].light.colors[50]).toBe('#1682d5');
    expect(() =>
      generatePaletteSet({
        modeStrategy: 'light-only',
        stops: [20, 50, 80],
        families: [
          {
            id: 'broken',
            name: 'Broken',
            seed: '#ff0000',
            anchors: [
              {
                mode: 'light',
                stop: 30,
                color: '#ff0000',
                policy: 'exact',
              },
            ],
          },
        ],
      }),
    ).toThrow('Anchor stop 30 is not present in the requested stop layout.');
  });

  it('distinguishes exact, bounded, and flexible authoring policies', () => {
    const target = '#1682d5';
    const generate = (policy, maxDeltaE) =>
      generateTonalPalette({
        modeStrategy: 'light-only',
        stops: [50],
        families: [
          {
            id: 'blue',
            name: 'Blue',
            seed: '#0074e2',
            anchors: [
              {
                mode: 'light',
                stop: 50,
                color: target,
                policy,
                ...(maxDeltaE == null ? {} : {maxDeltaE}),
              },
            ],
          },
        ],
      }).palette.blue.light[50];

    const exact = generate('exact');
    const bounded = generate('bounded', 2);
    const flexible = generate('flexible');

    expect(exact).toBe(target);
    expect(perceptualDelta(bounded, target)).toBeLessThanOrEqual(2.01);
    expect(flexible).not.toBe(target);
    expect(new Set([exact, bounded, flexible]).size).toBe(3);
  });

  it('rejects malformed anchors instead of silently dropping author intent', () => {
    expect(() =>
      generateTonalPalette({
        modeStrategy: 'light-only',
        stops: [50],
        families: [{...families[1], anchors: {}}],
      }),
    ).toThrow('anchors must be an array');

    expect(() =>
      generateTonalPalette({
        modeStrategy: 'light-only',
        stops: [50],
        families: [
          {
            ...families[1],
            anchors: [
              {mode: 'dark', stop: 50, color: '#1682d5', policy: 'exact'},
            ],
          },
        ],
      }),
    ).toThrow('Anchor mode dark is not generated by mode strategy light-only');
  });

  it('rejects an unknown neutral profile even without a neutral family', () => {
    expect(() =>
      generatePaletteSet({neutralProfile: 'warm-v2', families: [families[1]]}),
    ).toThrow('Unknown neutral profile: warm-v2');
    expect(
      generatePaletteSet({neutralProfile: 'warm-v1', families: [families[1]]})
        .request.neutralProfile,
    ).toBe('warm-v1');
  });

  it('normalizes anchor colors in the generation receipt', () => {
    const result = generatePaletteSet({
      modeStrategy: 'light-only',
      stops: [50],
      families: [
        {
          ...families[1],
          anchors: [
            {mode: 'light', stop: 50, color: '#AABBCC', policy: 'exact'},
          ],
        },
      ],
    });

    expect(result.request.families[0].anchors[0].color).toBe('#aabbcc');
  });

  it('requires bounded anchor tolerance to be a number', () => {
    for (const maxDeltaE of [null, '2']) {
      expect(() =>
        generateTonalPalette({
          modeStrategy: 'light-only',
          stops: [50],
          families: [
            {
              ...families[1],
              anchors: [
                {
                  mode: 'light',
                  stop: 50,
                  color: '#aabbcc',
                  policy: 'bounded',
                  maxDeltaE,
                },
              ],
            },
          ],
        }),
      ).toThrow('requires a non-negative maxDeltaE');
    }
  });

  it('generates an accent family only when the author declares one', () => {
    const withoutAccent = generateTonalPalette({
      stops: [50],
      families: [families[1]],
    });
    const withAccent = generateTonalPalette({
      stops: [50],
      families: [{id: 'accent', name: 'Accent', seed: '#ff4db8'}],
    });

    expect(withoutAccent.palette).not.toHaveProperty('accent');
    expect(withAccent.palette.accent.light[50]).toMatch(/^#[0-9a-f]{6}$/);
    expect(withAccent.palette.accent.dark[50]).toMatch(/^#[0-9a-f]{6}$/);
  });

  it('reserves black and white for the standalone palette values', () => {
    for (const id of ['black', 'white']) {
      expect(() =>
        generateTonalPalette({
          families: [{id, name: id, seed: '#777777'}],
        }),
      ).toThrow(
        `Family id ${id} is reserved for the standalone ${id} palette value.`,
      );
    }
  });

  it('uses vibrancy to make the generated families more muted or vivid', () => {
    const generate = vibrancy =>
      generateTonalPalette({
        vibrancy,
        stops: [50],
        families: [families[1]],
      }).palette.blue.light[50];

    expect(hexToOklch(generate(25)).C).toBeLessThan(hexToOklch(generate(75)).C);
  });
});