@skdx/docs-kit 0.35.0

package/dist/themes/SynthwaveDark.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+
+/** Synthwave inspired neon dark theme: deep indigo `#1a103d` background, hot-pink actions. Inspired by daisyUI's "synthwave" theme (saadeghi/daisyui, MIT). @public */
+export const synthwaveDark: Theme = {
+  name: 'synthwave-dark',
+  mode: 'dark',
+  colors: {
+    primary: {
+      50: '#fff7fd',
+      100: '#ffedfa',
+      200: '#ffd8f4',
+      300: '#ffbfed',
+      400: '#ffa7e7',
+      500: '#ff93e1',
+      600: '#ff7edb',
+      700: '#ce67b2',
+      800: '#a75492',
+      900: '#854475',
+      950: '#4f2a48',
+    },
+    neutral: {
+      50: '#f4f2fb',
+      100: '#e7e3f6',
+      200: '#2f2465',
+      300: '#443569',
+      400: '#8b81b5',
+      500: '#6f639c',
+      600: '#55487f',
+      700: '#443569',
+      800: '#322557',
+      900: '#241a47',
+      950: '#170f33',
+    },
+    success: {
+      50: '#f0fdfa',
+      100: '#ccfbf1',
+      200: '#99f6e4',
+      300: '#71ead2',
+      400: '#3ed4bd',
+      500: '#22b8a3',
+      600: '#189485',
+      700: '#17766c',
+      800: '#175e57',
+      900: '#184e49',
+      950: '#082f2c',
+    },
+    warning: {
+      50: '#fefbe8',
+      100: '#fef6c3',
+      200: '#fdec8a',
+      300: '#f3cc30',
+      400: '#eebd20',
+      500: '#dea70f',
+      600: '#c0850a',
+      700: '#99650c',
+      800: '#7e5012',
+      900: '#6b4215',
+      950: '#3e2308',
+    },
+    danger: {
+      50: '#fff1f3',
+      100: '#ffe3e8',
+      200: '#ffccd6',
+      300: '#ffa1b4',
+      400: '#fb7185',
+      500: '#f43f5e',
+      600: '#e11d48',
+      700: '#be123c',
+      800: '#9f1239',
+      900: '#881337',
+      950: '#4c0519',
+    },
+    semantic: {
+      background: '#1a103d',
+      surface: '#251b4f',
+      surfaceHover: '#2f2465',
+      overlay: 'rgb(10 4 32 / 0.7)',
+      text: '#f9f7fd',
+      textMuted: '#a89ed8',
+      textInverted: '#1a103d',
+      border: '#2f2465',
+      borderStrong: '#7660af',
+      focusRing: '#e779c1',
+    },
+  },
+  shadow: { color: '10 4 32', strength: '5.8' },
+};

package/dist/themes/SynthwaveLight.md

@@ -0,0 +1,20 @@
+---
+upstream: daisyUI Synthwave
+deviations:
+  - token: warning-600
+    upstream: #c0850a
+    ours: #bf840a
+    reason: Read 2.96:1 against the theme background, under the 3:1 floor for status
+      ramps. Darkened on lightness alone, hue and saturation kept, to reach 3.00:1
+      contrast against the theme background.
+  - token: text-muted
+    upstream: #6c5f92
+    ours: #665989
+    reason: Read 4.48:1 against hover and 4.13:1 against pressed, under the 4.5:1
+      floor for body text. Darkened on lightness alone, hue and saturation kept,
+      to clear 4.5:1 against both fills.
+---
+
+# themes/synthwave-light.ts
+
+Exports **`synthwaveLight`** — a light theme registered as `data-skdx-theme="synthwave-light"`, the `synthwave` brand's light mode — the neon pink primary darkened to `#b0327f` at 600 so white labels pass AA, on pale lavender surfaces (`background: #faf5ff`) with deep indigo text.

package/dist/themes/SynthwaveLight.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme } from '../utils/theme';
+import { createTheme } from './DefaultTheme';
+import { synthwaveDark } from './SynthwaveDark';
+
+/** Light counterpart of `synthwave-dark` — neon pink primary softened onto pale lavender to survive on paper. @public */
+export const synthwaveLight: Theme = createTheme(
+  'synthwave-light',
+  {
+    mode: 'light',
+    colors: {
+      primary: {
+        50: '#faf3f7',
+        100: '#f4e2ed',
+        200: '#e7c2d9',
+        300: '#d899bf',
+        400: '#c974a8',
+        500: '#bd5393',
+        600: '#b0327f',
+        700: '#8f2a69',
+        800: '#742457',
+        900: '#5d1e47',
+        950: '#38152e',
+      },
+      neutral: { 200: '#e3d7f0', 300: '#cbbde0' },
+      warning: { 600: '#bf840a' },
+      semantic: {
+        background: '#faf5ff',
+        surface: '#f3ebfa',
+        surfaceHover: '#ebe0f5',
+        overlay: 'rgb(26 16 61 / 0.4)',
+        text: '#2b1b50',
+        textMuted: '#665989',
+        textInverted: '#ffffff',
+        border: '#e3d7f0',
+        borderStrong: '#977bc1',
+        focusRing: '#b0327f',
+      },
+    },
+    shadow: { color: '2 6 23', strength: '1' },
+  },
+  synthwaveDark,
+);

package/dist/themes/Themes.test.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import * as themeModules from './index';
+import { themes } from './index';
+
+const exportedThemes = Object.values(themeModules).filter(
+  (value): value is (typeof themes)[number] =>
+    typeof value === 'object' && value !== null && !Array.isArray(value) && 'mode' in value,
+);
+
+const scaleSteps = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+const ramps = ['primary', 'neutral', 'success', 'warning', 'danger'] as const;
+const semanticKeys = [
+  'background',
+  'surface',
+  'surfaceHover',
+  'overlay',
+  'text',
+  'textMuted',
+  'textInverted',
+  'border',
+  'borderStrong',
+  'focusRing',
+] as const;
+
+describe('themes registry', () => {
+  it('registers every exported theme exactly once, and nothing else', () => {
+    expect(new Set(themes)).toEqual(new Set(exportedThemes));
+    expect(themes).toHaveLength(exportedThemes.length);
+  });
+
+  it('gives every theme a unique kebab-case name', () => {
+    const names = themes.map((t) => t.name);
+    expect(new Set(names).size).toBe(names.length);
+    for (const name of names) {
+      expect(name).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    }
+  });
+
+  it('gives every theme an explicit light or dark mode', () => {
+    for (const theme of themes) {
+      expect(['light', 'dark']).toContain(theme.mode);
+    }
+  });
+
+  it.each(themes.map((t) => [t.name, t] as const))(
+    '%s defines a full 50-950 hex scale for every color ramp',
+    (_name, theme) => {
+      for (const ramp of ramps) {
+        for (const step of scaleSteps) {
+          expect(theme.colors[ramp][step]).toMatch(/^#[0-9a-f]{6}$/i);
+        }
+      }
+    },
+  );
+
+  it.each(themes.map((t) => [t.name, t] as const))(
+    '%s defines every semantic color token',
+    (_name, theme) => {
+      for (const key of semanticKeys) {
+        expect(theme.colors.semantic[key]).toBeTruthy();
+      }
+    },
+  );
+
+  it.each(themes.map((t) => [t.name, t] as const))(
+    '%s defines a shadow tint the foundation geometry can substitute',
+    (_name, theme) => {
+      // Must be space-separated channels: a hex string here silently produces no shadow.
+      expect(theme.shadow.color).toMatch(/^\d{1,3} \d{1,3} \d{1,3}$/);
+      expect(Number(theme.shadow.strength)).toBeGreaterThan(0);
+    },
+  );
+
+  it('confines the motion deviation to the three design-language themes', () => {
+    const deviating = themes.filter((t) => t.motion).map((t) => t.name);
+    expect(deviating.sort()).toEqual(
+      [
+        'ant-dark',
+        'ant-daybreak',
+        'fluent',
+        'fluent-dark',
+        'material-you',
+        'material-you-dark',
+      ].sort(),
+    );
+  });
+
+  it('confines the font deviation to the two themes with their own typeface', () => {
+    const deviating = themes.filter((t) => t.typography).map((t) => t.name);
+    expect(deviating.sort()).toEqual(
+      ['fluent', 'fluent-dark', 'material-you', 'material-you-dark'].sort(),
+    );
+  });
+
+  it('lets a deviating theme reach only the two stacks and the four base motion tokens', () => {
+    const allowedFont = new Set(['fontFamily', 'fontFamilyMono']);
+    const allowedMotion = new Set(['durationFast', 'durationNormal', 'durationSlow', 'easing']);
+    for (const theme of themes) {
+      for (const key of Object.keys(theme.typography ?? {})) expect(allowedFont).toContain(key);
+      for (const key of Object.keys(theme.motion ?? {})) expect(allowedMotion).toContain(key);
+    }
+  });
+});

package/dist/themes/brands.test.ts

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { brands, defaultBrand, getBrand, getBrandByThemeName } from './brands';
+import { themes } from './index';
+
+describe('brands registry', () => {
+  it('gives every brand a unique kebab-case name', () => {
+    const names = brands.map((b) => b.name);
+    expect(new Set(names).size).toBe(names.length);
+    for (const name of names) {
+      expect(name).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    }
+  });
+
+  it.each(brands.map((b) => [b.name, b] as const))(
+    '%s provides a complete light and dark theme with matching modes',
+    (_name, brand) => {
+      expect(brand.themes.light.mode).toBe('light');
+      expect(brand.themes.dark.mode).toBe('dark');
+      expect(brand.themes.light.name).not.toBe(brand.themes.dark.name);
+    },
+  );
+
+  it('claims each theme name in exactly one brand-and-mode slot', () => {
+    const claimed = brands.flatMap((b) => [b.themes.light.name, b.themes.dark.name]);
+    expect(new Set(claimed).size).toBe(claimed.length);
+    expect(claimed).toEqual(themes.map((t) => t.name));
+  });
+
+  it.each(brands.map((b) => [b.name, b] as const))(
+    "%s keeps its identity across modes — light and dark share the brand's primary hue family or an intentional inversion",
+    (_name, brand) => {
+      expect(brand.themes.light.colors.semantic.background).not.toBe(
+        brand.themes.dark.colors.semantic.background,
+      );
+      expect(brand.themes.light.colors.semantic.text).not.toBe(
+        brand.themes.dark.colors.semantic.text,
+      );
+    },
+  );
+
+  it('defaults to the skanda brand, whose light theme is skanda-light', () => {
+    expect(defaultBrand.name).toBe('skanda');
+    expect(defaultBrand.themes.light.name).toBe('skanda-light');
+  });
+
+  it('looks up brands by name and returns undefined for unknown names', () => {
+    expect(getBrand('nord')?.themes.dark.name).toBe('nord-dark');
+    expect(getBrand('not-a-brand')).toBeUndefined();
+  });
+
+  it('resolves legacy theme names to their owning brand', () => {
+    expect(getBrandByThemeName('one-dark')?.name).toBe('one');
+    expect(getBrandByThemeName('catppuccin-latte')?.name).toBe('catppuccin');
+    expect(getBrandByThemeName('not-a-theme')).toBeUndefined();
+  });
+});

package/dist/themes/brands.ts

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import type { Theme, ThemeColorMode } from '../utils/theme';
+import { antDark } from './AntDark';
+import { antLight } from './AntLight';
+import { catppuccinLatte } from './CatppuccinLatte';
+import { catppuccinMocha } from './CatppuccinMocha';
+import { chakraDark } from './ChakraDark';
+import { chakraLight } from './ChakraLight';
+import { cupcakeDark } from './CupcakeDark';
+import { cupcakeLight } from './CupcakeLight';
+import { draculaDark } from './DraculaDark';
+import { draculaLight } from './DraculaLight';
+import { emeraldDark } from './EmeraldDark';
+import { emeraldLight } from './EmeraldLight';
+import { everforestDark } from './EverforestDark';
+import { everforestLight } from './EverforestLight';
+import { fluentDark } from './FluentDark';
+import { fluentLight } from './FluentLight';
+import { graphiteDark } from './GraphiteDark';
+import { graphiteLight } from './GraphiteLight';
+import { gruvboxDark } from './GruvboxDark';
+import { gruvboxLight } from './GruvboxLight';
+import { materialDark } from './MaterialDark';
+import { materialLight } from './MaterialLight';
+import { midnightDark } from './MidnightDark';
+import { midnightLight } from './MidnightLight';
+import { nordDark } from './NordDark';
+import { nordLight } from './NordLight';
+import { oneDark } from './OneDark';
+import { oneLight } from './OneLight';
+import { primerDark } from './PrimerDark';
+import { primerLight } from './PrimerLight';
+import { rosePine } from './RosePine';
+import { rosePineDawn } from './RosePineDawn';
+import { skandaDark } from './SkandaDark';
+import { skandaLight } from './SkandaLight';
+import { solarizedDark } from './SolarizedDark';
+import { solarizedLight } from './SolarizedLight';
+import { synthwaveDark } from './SynthwaveDark';
+import { synthwaveLight } from './SynthwaveLight';
+
+/** A visual identity with a complete {@link Theme} for each color mode. @public */
+export interface Brand {
+  /** Stable brand identifier, e.g. `'skanda'` — safe to persist and use as a `data-*` value. */
+  name: string;
+  /** Human-readable brand name, e.g. `'Skanda'`. */
+  displayName: string;
+  /** The brand's complete theme for each resolved color mode. */
+  themes: Record<ThemeColorMode, Theme>;
+}
+
+/** Every bundled brand with its light/dark theme pair, in stable order. @public */
+export const brands: Brand[] = [
+  { name: 'skanda', displayName: 'Skanda', themes: { light: skandaLight, dark: skandaDark } },
+  { name: 'emerald', displayName: 'Emerald', themes: { light: emeraldLight, dark: emeraldDark } },
+  {
+    name: 'midnight',
+    displayName: 'Midnight',
+    themes: { light: midnightLight, dark: midnightDark },
+  },
+  {
+    name: 'graphite',
+    displayName: 'Graphite',
+    themes: { light: graphiteLight, dark: graphiteDark },
+  },
+  {
+    name: 'material',
+    displayName: 'Material',
+    themes: { light: materialLight, dark: materialDark },
+  },
+  { name: 'ant', displayName: 'Ant', themes: { light: antLight, dark: antDark } },
+  { name: 'fluent', displayName: 'Fluent', themes: { light: fluentLight, dark: fluentDark } },
+  { name: 'chakra', displayName: 'Chakra', themes: { light: chakraLight, dark: chakraDark } },
+  { name: 'nord', displayName: 'Nord', themes: { light: nordLight, dark: nordDark } },
+  { name: 'dracula', displayName: 'Dracula', themes: { light: draculaLight, dark: draculaDark } },
+  {
+    name: 'catppuccin',
+    displayName: 'Catppuccin',
+    themes: { light: catppuccinLatte, dark: catppuccinMocha },
+  },
+  {
+    name: 'solarized',
+    displayName: 'Solarized',
+    themes: { light: solarizedLight, dark: solarizedDark },
+  },
+  { name: 'gruvbox', displayName: 'Gruvbox', themes: { light: gruvboxLight, dark: gruvboxDark } },
+  { name: 'rose-pine', displayName: 'Rosé Pine', themes: { light: rosePineDawn, dark: rosePine } },
+  {
+    name: 'everforest',
+    displayName: 'Everforest',
+    themes: { light: everforestLight, dark: everforestDark },
+  },
+  { name: 'one', displayName: 'One', themes: { light: oneLight, dark: oneDark } },
+  { name: 'primer', displayName: 'Primer', themes: { light: primerLight, dark: primerDark } },
+  { name: 'cupcake', displayName: 'Cupcake', themes: { light: cupcakeLight, dark: cupcakeDark } },
+  {
+    name: 'synthwave',
+    displayName: 'Synthwave',
+    themes: { light: synthwaveLight, dark: synthwaveDark },
+  },
+];
+
+/** Default brand (`skanda-light`). @public */
+export const defaultBrand: Brand = brands[0]!;
+
+/** Looks up a brand by its stable identifier; `undefined` if not found. @public */
+export function getBrand(name: string): Brand | undefined {
+  return brands.find((brand) => brand.name === name);
+}
+
+/** Looks up the brand that owns a theme name in either mode. @public */
+export function getBrandByThemeName(themeName: string): Brand | undefined {
+  return brands.find(
+    (brand) => brand.themes.light.name === themeName || brand.themes.dark.name === themeName,
+  );
+}

package/dist/themes/createBrandTheme.test.ts

@@ -0,0 +1,223 @@
+/*
+ * Copyright (c) 2026 SkandaDX
+ * This file is part of the SkandaDX organization.
+ * Licensed under the MIT License. See LICENSE in the repository root.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { contrastRatio } from '../utils/contrast';
+import type { ThemeColorMode } from '../utils/theme';
+import { createBrandTheme } from './createBrandTheme';
+import { defaultTheme } from './DefaultTheme';
+import { midnightDark } from './MidnightDark';
+import { midnightLight } from './MidnightLight';
+
+const STEPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;
+const RAMPS = ['primary', 'neutral', 'success', 'warning', 'danger'] as const;
+const MODES: ThemeColorMode[] = ['light', 'dark'];
+const HUES = [0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330];
+
+describe('createBrandTheme', () => {
+  it('carries the seed name and mode through', () => {
+    const theme = createBrandTheme({ name: 'acme-dark', mode: 'dark', primaryHue: 210 });
+    expect(theme.name).toBe('acme-dark');
+    expect(theme.mode).toBe('dark');
+  });
+
+  it('derives colours only, leaving the shared layer and the shadow tint alone', () => {
+    const theme = createBrandTheme({ name: 'acme', mode: 'light', primaryHue: 210 });
+    expect(theme.shadow).toEqual(defaultTheme.shadow);
+    expect(theme.typography).toBeUndefined();
+    expect(theme.motion).toBeUndefined();
+  });
+
+  it.each(MODES)('emits a full 11-step 6-digit hex ramp for every scale (%s)', (mode) => {
+    const theme = createBrandTheme({ name: 'acme', mode, primaryHue: 271, primaryChroma: 91 });
+    for (const ramp of RAMPS) {
+      for (const step of STEPS) {
+        expect(theme.colors[ramp][step]).toMatch(/^#[0-9a-f]{6}$/);
+      }
+    }
+  });
+
+  it.each(MODES)('produces a monotonically darkening neutral ramp (%s)', (mode) => {
+    const theme = createBrandTheme({ name: 'acme', mode, primaryHue: 271 });
+    const luminances = STEPS.map((step) => contrastRatio(theme.colors.neutral[step], '#000000'));
+    expect(luminances).toEqual([...luminances].sort((a, b) => b - a));
+  });
+
+  describe.each(MODES)('WCAG AA enforcement (%s)', (mode) => {
+    it.each(HUES)('hue %i: body text meets 4.5:1 against the background', (hue) => {
+      const { semantic } = createBrandTheme({ name: 'acme', mode, primaryHue: hue }).colors;
+      expect(contrastRatio(semantic.text, semantic.background)).toBeGreaterThanOrEqual(4.5);
+    });
+
+    it.each(HUES)('hue %i: muted text meets 3:1 against the background', (hue) => {
+      const { semantic } = createBrandTheme({ name: 'acme', mode, primaryHue: hue }).colors;
+      expect(contrastRatio(semantic.textMuted, semantic.background)).toBeGreaterThanOrEqual(3);
+    });
+
+    it.each(HUES)('hue %i: the focus ring meets 3:1 against the background', (hue) => {
+      const { semantic } = createBrandTheme({
+        name: 'acme',
+        mode,
+        primaryHue: hue,
+        primaryChroma: 91,
+      }).colors;
+      expect(contrastRatio(semantic.focusRing, semantic.background)).toBeGreaterThanOrEqual(3);
+    });
+
+    it.each(HUES)('hue %i: inverted text meets 4.5:1 against primary-500 and -600', (hue) => {
+      const colors = createBrandTheme({
+        name: 'acme',
+        mode,
+        primaryHue: hue,
+        primaryChroma: 91,
+      }).colors;
+      expect(
+        contrastRatio(colors.semantic.textInverted, colors.primary[500]),
+      ).toBeGreaterThanOrEqual(4.5);
+      expect(
+        contrastRatio(colors.semantic.textInverted, colors.primary[600]),
+      ).toBeGreaterThanOrEqual(4.5);
+    });
+  });
+
+  it.each([
+    ['violet', 271, 91],
+    ['yellow', 55, 95],
+  ])('keeps one inverted ink per mode and moves the accent to earn it (%s)', (_n, hue, chroma) => {
+    const light = createBrandTheme({
+      name: 'a',
+      mode: 'light',
+      primaryHue: hue,
+      primaryChroma: chroma,
+    });
+    expect(light.colors.semantic.textInverted).toBe('#ffffff');
+    expect(
+      contrastRatio(light.colors.semantic.textInverted, light.colors.primary[500]),
+    ).toBeGreaterThanOrEqual(4.5);
+
+    const dark = createBrandTheme({
+      name: 'b',
+      mode: 'dark',
+      primaryHue: hue,
+      primaryChroma: chroma,
+    });
+    expect(dark.colors.semantic.textInverted).toBe(dark.colors.neutral[950]);
+    expect(
+      contrastRatio(dark.colors.semantic.textInverted, dark.colors.primary[500]),
+    ).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('renders overlay as an alpha rgb() derived from the darkest neutral', () => {
+    const theme = createBrandTheme({ name: 'acme', mode: 'light', primaryHue: 271 });
+    expect(theme.colors.semantic.overlay).toMatch(/^rgb\(\d+ \d+ \d+ \/ 0\.5\)$/);
+    expect(
+      createBrandTheme({ name: 'a', mode: 'dark', primaryHue: 271 }).colors.semantic.overlay,
+    ).toMatch(/\/ 0\.65\)$/);
+  });
+
+  it('gives light and dark seeds genuinely different surfaces and text', () => {
+    const seed = { primaryHue: 271, primaryChroma: 91 } as const;
+    const light = createBrandTheme({ name: 'a-light', mode: 'light', ...seed });
+    const dark = createBrandTheme({ name: 'a-dark', mode: 'dark', ...seed });
+
+    expect(light.colors.semantic.background).not.toBe(dark.colors.semantic.background);
+    expect(light.colors.semantic.text).not.toBe(dark.colors.semantic.text);
+    const enforced = new Set([500, 600]);
+    for (const step of STEPS.filter((s) => !enforced.has(s))) {
+      expect(light.colors.primary[step], `primary-${step} should not vary by mode`).toBe(
+        dark.colors.primary[step],
+      );
+    }
+    expect(light.colors.primary[500]).not.toBe(dark.colors.primary[500]);
+  });
+
+  it('defaults the neutral hue to the primary hue and tints it only faintly', () => {
+    const tinted = createBrandTheme({ name: 'a', mode: 'light', primaryHue: 271 });
+    const explicit = createBrandTheme({
+      name: 'a',
+      mode: 'light',
+      primaryHue: 271,
+      neutralHue: 271,
+    });
+    expect(tinted.colors.neutral).toEqual(explicit.colors.neutral);
+
+    const heavier = createBrandTheme({
+      name: 'a',
+      mode: 'light',
+      primaryHue: 271,
+      neutralChroma: 60,
+    });
+    expect(heavier.colors.neutral[500]).not.toBe(tinted.colors.neutral[500]);
+  });
+
+  it('honours custom intent hues', () => {
+    const custom = createBrandTheme({
+      name: 'a',
+      mode: 'light',
+      primaryHue: 271,
+      intentHues: { success: 160, warning: 25, danger: 350 },
+      intentChroma: 80,
+    });
+    const base = createBrandTheme({ name: 'a', mode: 'light', primaryHue: 271 });
+    expect(custom.colors.success[500]).not.toBe(base.colors.success[500]);
+    expect(custom.colors.warning[500]).not.toBe(base.colors.warning[500]);
+    expect(custom.colors.danger[500]).not.toBe(base.colors.danger[500]);
+  });
+
+  it('applies the seed override last, so a brand can still hand-pick tokens', () => {
+    const theme = createBrandTheme({
+      name: 'acme',
+      mode: 'light',
+      primaryHue: 271,
+      override: { shadow: { strength: '3' }, colors: { semantic: { focusRing: '#123456' } } },
+    });
+    expect(theme.shadow.strength).toBe('3');
+    expect(theme.shadow.color).toBe(defaultTheme.shadow.color);
+    expect(theme.colors.semantic.focusRing).toBe('#123456');
+  });
+});
+
+describe('the generated midnight brand', () => {
+  it('keeps its published theme names and modes', () => {
+    expect(midnightLight.name).toBe('midnight-light');
+    expect(midnightLight.mode).toBe('light');
+    expect(midnightDark.name).toBe('midnight-brand');
+    expect(midnightDark.mode).toBe('dark');
+  });
+
+  it('shares one violet ramp across both modes, apart from the enforced action steps', () => {
+    const enforced = new Set([500, 600]);
+    for (const step of STEPS.filter((s) => !enforced.has(s))) {
+      expect(midnightLight.colors.primary[step]).toBe(midnightDark.colors.primary[step]);
+    }
+  });
+
+  it('clears AA on the painted accent in both modes', () => {
+    for (const theme of [midnightLight, midnightDark]) {
+      expect(
+        contrastRatio(theme.colors.semantic.textInverted, theme.colors.primary[500]),
+        `${theme.name}: textInverted on primary-500`,
+      ).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+
+  it('keeps the hand-tuned dark shadow tint on the dark theme only', () => {
+    expect(midnightDark.shadow).toEqual({ color: '0 0 0', strength: '5.2' });
+    expect(midnightLight.shadow).toEqual(defaultTheme.shadow);
+  });
+
+  it.each([midnightLight, midnightDark])(
+    '$name clears every AA pair without an allowlist entry',
+    (theme) => {
+      const { semantic, primary } = theme.colors;
+      expect(contrastRatio(semantic.text, semantic.background)).toBeGreaterThanOrEqual(4.5);
+      expect(contrastRatio(semantic.textMuted, semantic.background)).toBeGreaterThanOrEqual(3);
+      expect(contrastRatio(semantic.focusRing, semantic.background)).toBeGreaterThanOrEqual(3);
+      expect(contrastRatio(semantic.textInverted, primary[600])).toBeGreaterThanOrEqual(4.5);
+    },
+  );
+});