@evolve.ui/theme-system 1.0.1 → 1.2.0

package/src/themes/brandSources.ts

@@ -0,0 +1,37 @@
+/**
+ * The one build-time table of brand palette modules. Internal: not a tsdown entry and not
+ * re-exported from index.ts (brands.ts stays pure data for the browser). Consumers read this instead
+ * of hand-listing brands: tsdown.config.ts onSuccess, runtime/buildTheme.ts, themeValues.ts,
+ * contrast.spec.ts and tailwind/text.spec.ts. allThemes.ts keeps its explicit map because index.ts
+ * re-exports the per-brand runtime themes; `satisfies Record<Brands, …>` makes a missing brand a compile error.
+ *
+ * Key order is load-bearing: the themeValues snapshot is an ORDERED entry list built by iterating
+ * this object, so keep BasketballTraining, Default, ProfessionalBrand and append new brands (EverydayHarbor).
+ */
+import type { StepObject } from '../utils/color';
+import type { Brands } from './brands';
+
+import * as BasketballTraining from './BasketballTraining';
+import * as Default from './Default';
+import * as EverydayHarbor from './EverydayHarbor';
+import { type ColorAliasesObject, type NonColorCSSVariables, makeColorCSSVarsFromObject } from './generateCSSVars';
+import * as ProfessionalBrand from './ProfessionalBrand';
+
+export type BrandModule = {
+    readonly coreColors: Readonly<Record<string, StepObject>>;
+    readonly colorAliases: ColorAliasesObject;
+    readonly nonColorVariables: Readonly<Record<NonColorCSSVariables, string>>;
+};
+
+export const brandSources = {
+    BasketballTraining,
+    Default,
+    ProfessionalBrand,
+    EverydayHarbor,
+} as const satisfies Record<Brands, BrandModule>;
+
+/** `{ ...nonColorVariables, ...palette vars }` in that order: exactly what the CSS generator receives. */
+export const brandCssVariables = (brand: Brands): Record<string, string> => ({
+    ...brandSources[brand].nonColorVariables,
+    ...makeColorCSSVarsFromObject(brandSources[brand].colorAliases),
+});

package/src/themes/brands.ts

@@ -0,0 +1,63 @@
+/**
+ * The `Brands` union is the ONE authored list of brand names. Every other per-brand table is derived
+ * from `brandRegistry` or checked against this union with `satisfies Record<Brands, …>`, so a missing
+ * entry is a compile error rather than a silent omission.
+ *
+ * Stays pure data: this module is the published `@evolve.ui/theme-system/brands` subpath and is
+ * imported by Storybook in the browser, so it must not import brand palette modules.
+ */
+export type Brands = 'BasketballTraining' | 'Default' | 'EverydayHarbor' | 'ProfessionalBrand';
+
+/**
+ * `paper`: light canvas; the brand renders on `bg-background-primary`.
+ * `ink`: inverted canvas; Storybook frames it separately instead of in the white "All together" grid.
+ */
+export type BrandCanvas = 'ink' | 'paper';
+
+export type BrandRegistryEntry = {
+    readonly canvas: BrandCanvas;
+    readonly cssClass: `brand-${string}`;
+    readonly label: string;
+    /** Kept for API compatibility; always equal to the registry key. */
+    readonly storybookKey: Brands;
+    readonly themeKey: Brands;
+};
+
+export const brandRegistry = {
+    BasketballTraining: {
+        canvas: 'paper',
+        cssClass: 'brand-basketball',
+        label: 'Basketball Training',
+        storybookKey: 'BasketballTraining',
+        themeKey: 'BasketballTraining',
+    },
+    Default: {
+        canvas: 'paper',
+        cssClass: 'brand-default',
+        label: 'Default (Neutral)',
+        storybookKey: 'Default',
+        themeKey: 'Default',
+    },
+    ProfessionalBrand: {
+        canvas: 'paper',
+        cssClass: 'brand-professional',
+        label: 'Professional Brand',
+        storybookKey: 'ProfessionalBrand',
+        themeKey: 'ProfessionalBrand',
+    },
+    // Appended after the paper brands: the themeValues snapshot and `brands` order follow key order.
+    EverydayHarbor: {
+        canvas: 'ink',
+        cssClass: 'brand-harbor',
+        label: 'Everyday Harbor',
+        storybookKey: 'EverydayHarbor',
+        themeKey: 'EverydayHarbor',
+    },
+} as const satisfies Record<Brands, BrandRegistryEntry>;
+
+/** Registry key order (previously a hand list ordered Basketball, Professional, Default). */
+export const brands: Brands[] = Object.keys(brandRegistry) as Brands[];
+
+export const brandsToCSS: Record<Brands, string> = Object.fromEntries(
+    brands.map((brand) => [brand, brandRegistry[brand].cssClass])
+) as Record<Brands, string>;

package/src/themes/common.ts

@@ -0,0 +1,65 @@
+import type { Theme } from './themeType';
+
+import { borderRadius } from '../tailwind/borderRadius';
+import { screens } from '../tailwind/screens';
+import { spacing as tailwindSpacing } from '../tailwind/spacing';
+
+const parsePx = (value: string): number => Number(value.replace('px', ''));
+
+export const spacing = {
+    lg: tailwindSpacing.lg,
+    lgValue: parsePx(tailwindSpacing.lg),
+    md: tailwindSpacing.md,
+    mdValue: parsePx(tailwindSpacing.md),
+    sm: tailwindSpacing.sm,
+    smValue: parsePx(tailwindSpacing.sm),
+    xl: tailwindSpacing.xl,
+    xlValue: parsePx(tailwindSpacing.xl),
+    xs: tailwindSpacing.xs,
+    xsValue: parsePx(tailwindSpacing.xs),
+    xxl: tailwindSpacing['2xl'],
+    xxlValue: parsePx(tailwindSpacing['2xl']),
+    xxs: tailwindSpacing['2xs'],
+    xxsValue: parsePx(tailwindSpacing['2xs']),
+    xxxl: tailwindSpacing['3xl'],
+    xxxlValue: parsePx(tailwindSpacing['3xl']),
+    xxxs: tailwindSpacing['3xs'],
+    xxxsValue: parsePx(tailwindSpacing['3xs']),
+} as const satisfies Theme['spacing'];
+
+export const breakpoints = {
+    lgMax: screens.lgMax.max,
+    lgMaxValue: parsePx(screens.lgMax.max),
+    lgMin: screens.lgMin.min,
+    lgMinValue: parsePx(screens.lgMin.min),
+    mdMax: screens.mdMax.max,
+    mdMaxValue: parsePx(screens.mdMax.max),
+    mdMin: screens.mdMin.min,
+    mdMinValue: parsePx(screens.mdMin.min),
+    smMax: screens.smMax.max,
+    smMaxValue: parsePx(screens.smMax.max),
+    smMin: screens.smMin.min,
+    smMinValue: parsePx(screens.smMin.min),
+    xlMin: screens.xlMin.min,
+    xlMinValue: parsePx(screens.xlMin.min),
+    xsMax: screens.xsMax.max,
+    xsMaxValue: parsePx(screens.xsMax.max),
+} as const satisfies Theme['breakpoints'];
+
+export const radius = {
+    circle: '50%',
+    lg: borderRadius.lg,
+    md: borderRadius.md,
+    sm: borderRadius.sm,
+    xl: borderRadius.xl,
+    xs: borderRadius.xs,
+    zero: borderRadius.none,
+} as const satisfies Theme['border']['radius'];
+
+export const width = {
+    lg: '8px',
+    md: '4px',
+    sm: '2px',
+    xs: '1px',
+    xxs: '0.5px',
+} as const satisfies Theme['border']['width'];

package/src/themes/contrastFloors.ts

@@ -0,0 +1,26 @@
+export const TEXT_AA = 4.5;
+
+export const TEXT_AAA_BODY = 7;
+
+export const UI_AA = 3;
+
+export const TEXT_CONTRAST_TOKENS = [
+    ['--color-link-primary', TEXT_AA],
+    ['--color-text-critical', TEXT_AA],
+    ['--color-text-secondary', TEXT_AA],
+    ['--color-text-info', TEXT_AA],
+    ['--color-text-warning', TEXT_AA],
+    ['--color-text-success', TEXT_AA],
+] as const;
+
+export const UI_CONTRAST_TOKENS = [
+    '--color-focus-primary',
+    '--color-icon-critical',
+    '--color-icon-info',
+    '--color-icon-warning',
+    '--color-icon-success',
+] as const;
+
+export const FILLED_BUTTON_FAMILIES = ['primary', 'critical', 'surface'] as const;
+
+export const FILLED_BUTTON_STEPS = ['500', '700', '900'] as const;

package/src/themes/generateCSSVars.ts

@@ -0,0 +1,123 @@
+import type * as CSSVars from '../tailwind/cssVars';
+
+import { StepObject, steps } from '../utils/color';
+
+export type CSSVariables = (typeof CSSVars)[keyof typeof CSSVars];
+export type NonColorCSSVariables = Exclude<
+    CSSVariables,
+    | '--color-primary-50'
+    | '--color-primary-100'
+    | '--color-primary-200'
+    | '--color-primary-300'
+    | '--color-primary-400'
+    | '--color-primary-500'
+    | '--color-primary-600'
+    | '--color-primary-700'
+    | '--color-primary-800'
+    | '--color-primary-900'
+    | '--color-secondary-50'
+    | '--color-secondary-100'
+    | '--color-secondary-200'
+    | '--color-secondary-300'
+    | '--color-secondary-400'
+    | '--color-secondary-500'
+    | '--color-secondary-600'
+    | '--color-secondary-700'
+    | '--color-secondary-800'
+    | '--color-secondary-900'
+    | '--color-tertiary-50'
+    | '--color-tertiary-100'
+    | '--color-tertiary-200'
+    | '--color-tertiary-300'
+    | '--color-tertiary-400'
+    | '--color-tertiary-500'
+    | '--color-tertiary-600'
+    | '--color-tertiary-700'
+    | '--color-tertiary-800'
+    | '--color-tertiary-900'
+    | '--color-info-50'
+    | '--color-info-100'
+    | '--color-info-200'
+    | '--color-info-300'
+    | '--color-info-400'
+    | '--color-info-500'
+    | '--color-info-600'
+    | '--color-info-700'
+    | '--color-info-800'
+    | '--color-info-900'
+    | '--color-success-50'
+    | '--color-success-100'
+    | '--color-success-200'
+    | '--color-success-300'
+    | '--color-success-400'
+    | '--color-success-500'
+    | '--color-success-600'
+    | '--color-success-700'
+    | '--color-success-800'
+    | '--color-success-900'
+    | '--color-critical-50'
+    | '--color-critical-100'
+    | '--color-critical-200'
+    | '--color-critical-300'
+    | '--color-critical-400'
+    | '--color-critical-500'
+    | '--color-critical-600'
+    | '--color-critical-700'
+    | '--color-critical-800'
+    | '--color-critical-900'
+    | '--color-warning-50'
+    | '--color-warning-100'
+    | '--color-warning-200'
+    | '--color-warning-300'
+    | '--color-warning-400'
+    | '--color-warning-500'
+    | '--color-warning-600'
+    | '--color-warning-700'
+    | '--color-warning-800'
+    | '--color-warning-900'
+    | '--color-surface-50'
+    | '--color-surface-100'
+    | '--color-surface-200'
+    | '--color-surface-300'
+    | '--color-surface-400'
+    | '--color-surface-500'
+    | '--color-surface-600'
+    | '--color-surface-700'
+    | '--color-surface-800'
+    | '--color-surface-900'
+>;
+
+export type ColorAliases =
+    | 'primary'
+    | 'secondary'
+    | 'tertiary'
+    | 'info'
+    | 'success'
+    | 'warning'
+    | 'critical'
+    | 'surface';
+export type ColorAliasesObject = Record<ColorAliases, StepObject>;
+
+export const makeColorCSSVarsFromObject = (colors: ColorAliasesObject): Record<string, string> => {
+    const colorVars: Record<string, string> = {};
+    for (const [key, value] of Object.entries(colors)) {
+        for (const shade of steps) {
+            const varName = `--color-${key}-${shade}`;
+            colorVars[varName] = `${value[shade]}`;
+        }
+    }
+
+    return colorVars;
+};
+
+export const generateCSSVars = (vars: Record<string, string>, className: string): string => {
+    const classBlock = `.${className} {\n${Object.entries(vars)
+        .map(([key, value]) => `    ${key}: ${value};`)
+        .join('\n')}\n}`;
+
+    const rootBlock = `:root {\n${Object.entries(vars)
+        .map(([key, value]) => `    ${key}: ${value};`)
+        .join('\n')}\n}`;
+
+    return `${classBlock}\n\n${rootBlock}`;
+};

package/src/themes/inkRamps.ts

@@ -0,0 +1,43 @@
+/**
+ * Ramp builders for canvas-dark ("ink") brands. Deliberately NOT in utils/color.ts: the Ground
+ * baseline records that file's export list, and the themeValues snapshot pins its generators.
+ * These builders only rearrange generator output or parse approved hexes; they never change
+ * what generateNormalColorSteps returns.
+ *
+ * Why invert: core-components hard-code palette steps relative to a light canvas
+ * (`bg-primary-500 text-text-inverse` filled, `text-primary-500` on `bg-background-primary`
+ * outlined, `hover:bg-primary-100 hover:text-primary-700`, ...). Those pairs only keep their
+ * contrast when step 50 sits next to the canvas, 900 sits far from it, and text-inverse equals the
+ * canvas. Reversing every ramp keeps that geometry on an ink canvas, so the brand can reuse the
+ * shared semantic map almost unchanged (see EverydayHarbor.ts).
+ */
+import { type StepObject, type Steps, colorStepArrayToObject, generateNormalColorSteps, steps } from '../utils/color';
+import { hexToChannels, luminance, parseChannels } from './wcag';
+
+/** A `#RRGGBB` literal. Validated when the theme module loads; a bad literal throws there. */
+export type Hex = `#${string}`;
+
+/**
+ * generateNormalColorSteps(seed), reversed: 50 is the deepest shade, 900 the palest tint.
+ * The seed lands on step 400 (the generator's 500), and the generator's 400 tint lands on 500.
+ * Example: seed #8EC5E8 -> 400 '142 197 232' (#8EC5E8), 500 '165 209 237' (#A5D1ED).
+ */
+export const inkNormalSteps = (seed: Hex): StepObject =>
+    colorStepArrayToObject([...generateNormalColorSteps(seed)].reverse());
+
+/**
+ * A hand-authored ramp from approved hexes, for families no seed reproduces (the ink surface ramp
+ * has seven approved anchors). Every step is required; output is the generator's channel format.
+ * Throws at load when a literal is malformed or the ramp is not strictly lighter at each step, so a
+ * swapped anchor fails immediately instead of in review.
+ */
+export const anchoredSteps = (hexes: Readonly<Record<Steps, Hex>>): StepObject => {
+    const ramp = Object.fromEntries(steps.map((step) => [step, hexToChannels(hexes[step])])) as StepObject;
+    steps.slice(1).forEach((step, index) => {
+        const previous = steps[index];
+        if (luminance(parseChannels(ramp[step])) <= luminance(parseChannels(ramp[previous]))) {
+            throw new Error(`anchoredSteps: step ${step} (${hexes[step]}) is not lighter than step ${previous}`);
+        }
+    });
+    return ramp;
+};

package/src/themes/runtime/basketballTraining.ts

@@ -0,0 +1,3 @@
+import { buildRuntimeTheme } from './buildTheme';
+
+export const basketballTrainingTheme = buildRuntimeTheme('BasketballTraining');