@evolve.ui/theme-system 1.1.0 → 1.2.0

package/src/themes/EverydayHarbor.ts

@@ -0,0 +1,147 @@
+import type { ColorAliasesObject, NonColorCSSVariables } from './generateCSSVars';
+
+/**
+ * "Harbor Ink" palette (brief of 2026-10-07), solid tokens only. The effect layer comes later.
+ *
+ * Ink-first: every ramp is reversed (inkRamps.ts) so the shared semantic map keeps working on a navy
+ * canvas. The brand differs from Default's map ONLY in `inkOverrides` and `inkShape`;
+ * EverydayHarbor.spec pins that the diff is exactly those keys.
+ *
+ * Where the approved hexes land (exact, asserted by EverydayHarbor.spec):
+ *   surface-50  #0B1626 canvas (background-primary, text-inverse)   surface-100 #12223A card
+ *   surface-200 #1A2E4A raised                                     surface-300 #56708F border / ring track
+ *   surface-500 #A9B6C6 muted text (solid)                          surface-600 #B9C5D3 muted text (glass)
+ *   surface-900 #EEF2F6 text-primary
+ *   primary-400 #2E6BA6 harbor blue (seed)    primary-500 #70B2EE the on-ink action step (see `harbor`)
+ *   info-400    #8EC5E8 links / info (seed)   info-500    #A5D1ED ring arc (icon-secondary, ring option B)
+ *   tertiary-400 #E3B341 gold focus ring (seed)
+ *   success-400 #A3B04E olive (seed)          warning-400 #D9963E (seed, CTA gradient end)
+ *   critical-400 #E5534B (seed, NOT in the brief: proposed, Dave to confirm)
+ *
+ * Surface ramp: seven steps are approved anchors (50, 100, 200, 300, 500, 600, 900). The other three
+ * are filled monotonically by per-channel sRGB interpolation, rounded to nearest:
+ *   400 = midpoint of 300 and 500;  700 and 800 = one third and two thirds of the way from 600 to 900.
+ * EverydayHarbor.spec recomputes them, so the rule is pinned rather than prose.
+ */
+import {
+    colorInfo400,
+    colorInfo500,
+    colorInfo600,
+    colorSuccess400,
+    colorSurface100,
+    colorSurface50,
+    colorTertiary400,
+    colorWarning100,
+    colorWarning400,
+    colorWarning500,
+} from '../tailwind/cssVars';
+import { wrapVar } from '../utils/wrapVar';
+import { nonColorVariables as sharedSemanticMap } from './Default';
+import { anchoredSteps, inkNormalSteps } from './inkRamps';
+import { hexToChannels } from './wcag';
+
+const harborGenerated = inkNormalSteps('#2E6BA6');
+
+/**
+ * Harbor primary ramp. 50-400 are the generated ink steps (seed #2E6BA6 stays on 400). Two steps are
+ * pinned by hand because the generated 500 (#4489CB) is too dark for the pairs core hard-codes
+ * around it:
+ *  - 500 #70B2EE is "the on-ink action step": navy text-inverse on it (filled button) 8.1:1, it as text
+ *    on the canvas / card / raised panel (outlined, transparent, filledInverse) 8.1 / 7.1 / 6.1:1, and
+ *    as text on the dark status tints (transparent Callout actions) >= 4.9:1 on the tightest, info-light.
+ *    The reference orb blue #5B9BD8 was tried first and only reaches 3.7:1 on info-light.
+ *  - 600 #95C3ED is the midpoint of 500 and the generated 700, so the ramp stays strictly lighter.
+ * 700-900 (hover / active text) are the generated steps.
+ */
+const harbor = {
+    ...harborGenerated,
+    '500': hexToChannels('#70B2EE'),
+    '600': hexToChannels('#95C3ED'),
+};
+
+export const coreColors = {
+    amber: inkNormalSteps('#D9963E'), // CTA gradient end
+    coral: inkNormalSteps('#E5534B'), // proposed critical
+    gold: inkNormalSteps('#E3B341'),
+    harbor,
+    ink: anchoredSteps({
+        '50': '#0B1626',
+        '100': '#12223A',
+        '200': '#1A2E4A',
+        '300': '#56708F',
+        '400': '#8093AB', // interpolated: midpoint of 300 and 500
+        '500': '#A9B6C6',
+        '600': '#B9C5D3',
+        '700': '#CBD4DF', // interpolated: 1/3 from 600 to 900
+        '800': '#DCE3EA', // interpolated: 2/3 from 600 to 900
+        '900': '#EEF2F6',
+    }),
+    olive: inkNormalSteps('#A3B04E'),
+    sky: inkNormalSteps('#8EC5E8'),
+    slate: inkNormalSteps('#56708F'),
+};
+
+export const colorAliases = {
+    critical: coreColors.coral,
+    info: coreColors.sky,
+    primary: coreColors.harbor,
+    secondary: coreColors.slate,
+    success: coreColors.olive,
+    surface: coreColors.ink,
+    tertiary: coreColors.gold,
+    warning: coreColors.amber,
+} satisfies ColorAliasesObject;
+
+const BLACK_SHADOW = (y: number, blur: number, alpha: number) => `0px ${y}px ${blur}px rgb(0 0 0 / ${alpha}%)`;
+
+/**
+ * The only colour bindings that differ from the shared map. Reasons:
+ *  - overlay: the shared map scrims with surface-900, which is now the palest step; use the navy.
+ *  - background-secondary: the card colour (#12223A), not slate-50.
+ *  - status text/icons/strong fills: the shared map picks far-from-canvas steps (700-900) to darken
+ *    on white; on reversed ramps those are near-white and lose hue, so bind the seed (400) or 500.
+ *  - warning-dark: bold Badge / BannerNotification warning put text-primary (pale) and icon-primary on it
+ *    (Badge.tsx 'text-text-primary', BannerIcon color='primary'), so it needs a DEEP amber (warning-100
+ *    #754C17: 6.7:1 text, 3.6:1 icon). critical-dark / info-dark / success-dark carry text-inverse
+ *    (navy) and keep the shared light bindings.
+ *  - focus-primary: gold ring (brief).  link-*: light blue links (brief).
+ *  - icon-secondary: ring arc #A5D1ED (option B). icon-disabled is NOT overridden: the shared
+ *    surface-300 binding already resolves to the ring track colour #56708F.
+ */
+const inkOverrides = {
+    '--color-background-overlay': wrapVar(colorSurface50),
+    '--color-background-secondary': wrapVar(colorSurface100),
+    '--color-background-success-dark': wrapVar(colorSuccess400),
+    '--color-background-warning-dark': wrapVar(colorWarning100),
+    '--color-focus-primary': wrapVar(colorTertiary400),
+    '--color-icon-secondary': wrapVar(colorInfo500),
+    '--color-icon-success': wrapVar(colorSuccess400),
+    '--color-icon-warning': wrapVar(colorWarning400),
+    '--color-link-hover': wrapVar(colorInfo500),
+    '--color-link-pressed': wrapVar(colorInfo600),
+    '--color-link-primary': wrapVar(colorInfo400),
+    '--color-text-info': wrapVar(colorInfo400),
+    '--color-text-success': wrapVar(colorSuccess400),
+    '--color-text-warning': wrapVar(colorWarning500),
+} as const satisfies Partial<Record<NonColorCSSVariables, string>>;
+
+/** Shape tokens: Inter for every heading (h1-h4 read --font-family-secondary), black drop shadows. */
+const inkShape = {
+    '--box-shadow-01': BLACK_SHADOW(4, 4, 45),
+    '--box-shadow-02': `${BLACK_SHADOW(1, 4, 45)}, ${BLACK_SHADOW(1, 8, 35)}`,
+    '--box-shadow-03': `${BLACK_SHADOW(2, 8, 45)}, ${BLACK_SHADOW(4, 16, 35)}`,
+    '--box-shadow-04': `${BLACK_SHADOW(3, 12, 50)}, ${BLACK_SHADOW(6, 24, 40)}`,
+    '--box-shadow-05': BLACK_SHADOW(-4, 4, 45),
+    '--container-border-radius': '12px',
+    '--font-family-secondary': "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+    // --text-transform-button stays 'uppercase' (inherited). OPEN for Dave: the brief is silent.
+} as const satisfies Partial<Record<NonColorCSSVariables, string>>;
+
+export const nonColorVariables = {
+    ...sharedSemanticMap,
+    ...inkOverrides,
+    ...inkShape,
+} satisfies Record<NonColorCSSVariables, string>;
+
+/** Exported for EverydayHarbor.spec ("differs from the shared map exactly here"). */
+export const everydayHarborOverrides = { ...inkOverrides, ...inkShape };

package/src/themes/allThemes.ts

@@ -3,10 +3,12 @@ import type { CleanTheme } from './themeType';
 
 import { basketballTrainingTheme } from './runtime/basketballTraining';
 import { defaultTheme } from './runtime/default';
+import { everydayHarborTheme } from './runtime/everydayHarbor';
 import { professionalBrandTheme } from './runtime/professionalBrand';
 
 export const allThemes = {
     BasketballTraining: basketballTrainingTheme,
     Default: defaultTheme,
+    EverydayHarbor: everydayHarborTheme,
     ProfessionalBrand: professionalBrandTheme,
 } as const satisfies Record<Brands, CleanTheme>;

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

@@ -1,37 +1,63 @@
-export type Brands = 'BasketballTraining' | 'ProfessionalBrand' | 'Default';
+/**
+ * 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';
 
-export const brands: Brands[] = ['BasketballTraining', 'ProfessionalBrand', 'Default'];
-
-export const brandsToCSS: Record<Brands, string> = {
-    BasketballTraining: 'brand-basketball',
-    Default: 'brand-default',
-    ProfessionalBrand: 'brand-professional',
-};
+/**
+ * `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 = {
-    cssClass: string;
-    label: string;
-    storybookKey: Brands;
-    themeKey: Brands;
+    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: {
-        cssClass: brandsToCSS.BasketballTraining,
+        canvas: 'paper',
+        cssClass: 'brand-basketball',
         label: 'Basketball Training',
         storybookKey: 'BasketballTraining',
         themeKey: 'BasketballTraining',
     },
     Default: {
-        cssClass: brandsToCSS.Default,
+        canvas: 'paper',
+        cssClass: 'brand-default',
         label: 'Default (Neutral)',
         storybookKey: 'Default',
         themeKey: 'Default',
     },
     ProfessionalBrand: {
-        cssClass: brandsToCSS.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/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/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/buildTheme.ts

@@ -4,23 +4,8 @@ import type { CleanTheme, Theme, TypographySpec } from '../themeType';
 import { boxShadow } from '../../tailwind/boxShadow';
 import * as cssVars from '../../tailwind/cssVars';
 import { fontFamily } from '../../tailwind/fontFamily';
-import * as BasketballTraining from '../BasketballTraining';
+import { brandSources } from '../brandSources';
 import { breakpoints, radius, spacing, width } from '../common';
-import * as Default from '../Default';
-import * as ProfessionalBrand from '../ProfessionalBrand';
-
-const themeSources = {
-    BasketballTraining,
-    Default,
-    ProfessionalBrand,
-} satisfies Record<
-    Brands,
-    {
-        colorAliases: Record<string, unknown>;
-        coreColors: Record<string, unknown>;
-        nonColorVariables: Record<string, string>;
-    }
->;
 
 const variable = (name: string): string => `var(${name})`;
 
@@ -136,10 +121,12 @@ const buildTypography = (): Theme['typography'] => {
                     spacing: variable(cssVars.letterSpacingH3),
                     weight: variable(cssVars.fontWeightH3),
                 }),
+                // Mirrors `.hui-text-h3`'s mobile block in `tailwind/text.ts` — keep in lockstep
+                // (DS-97 / SA-04; `tailwind/text.spec.ts` binds the two).
                 mobile: textSpec({
                     family: fontFamily.secondary,
-                    height: '24px',
-                    size: '16px',
+                    height: '27px',
+                    size: '18px',
                     spacing: variable(cssVars.letterSpacingH3Mobile),
                     weight: variable(cssVars.fontWeightH3),
                 }),
@@ -184,7 +171,7 @@ const buildTypography = (): Theme['typography'] => {
 };
 
 export const buildRuntimeTheme = (brand: Brands): CleanTheme => {
-    const source = themeSources[brand];
+    const source = brandSources[brand];
     const v = variable;
 
     return {

package/src/themes/runtime/everydayHarbor.ts

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

package/src/themes/semanticColorTokenSteps.ts

@@ -3,8 +3,11 @@ import { nonColorVariables } from './Default';
 /**
  * Maps each semantic color token (e.g. `text-critical`) to the core palette step
  * it resolves to (e.g. `critical-500`), parsed from the Default brand's
- * `nonColorVariables`. The semantic → step mapping is identical across all brands
- * (only the core hex values differ per brand), so Default is canonical.
+ * `nonColorVariables`. The semantic → step mapping is identical across the paper
+ * brands (only the core hex values differ per brand), so Default is canonical.
+ * Ink brands reuse this map on reversed ramps and rebind a handful of tokens
+ * (EverydayHarbor: `everydayHarborOverrides`), so this table describes Default and
+ * is not valid for them.
  *
  * Single source of truth for docs/tooling that need to show which step a semantic
  * token points at — derive from this rather than hand-maintaining a duplicate table.