@halogen-ui/tokens 0.1.0

package/src/semantic/index.ts

@@ -0,0 +1,415 @@
+/**
+ * Halogen — semantic tokens (layer 2 of 2).
+ *
+ * Aliases only. Every value here is a reference to a primitive; not one raw
+ * color, size or duration is permitted. That constraint is what makes the two
+ * layers actually two layers rather than one layer with a naming convention,
+ * and it is asserted by a test.
+ *
+ * Light and dark are authored independently rather than by inverting the ramp.
+ * They are not mirrors: dark-mode secondary text sits at `neutral-300` and
+ * light-mode secondary at `neutral-700`, because contrast against a near-black
+ * ground and contrast against an off-white ground are different problems with
+ * different answers.
+ */
+
+export type Ref = string;
+
+export interface SemanticTheme {
+  surface: Record<string, Ref>;
+  /** Foreground colors. Named `ink` so the Tailwind utility reads `text-ink-secondary`, not `text-text-secondary`. */
+  ink: Record<string, Ref>;
+  /** Border colors. Named `line` so the utility reads `border-line-control`, not `border-border-control`. */
+  line: Record<string, Ref>;
+  status: Record<string, Ref>;
+  viz: Record<string, Ref>;
+  gradient: Record<string, Ref>;
+  elevation: Record<string, Ref>;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dark — the default theme                                                    */
+/* -------------------------------------------------------------------------- */
+
+export const dark: SemanticTheme = {
+  surface: {
+    /** elev-0. The page. */
+    ground: '{color.neutral.1000}',
+    /** elev-1. Cards. */
+    raised: '{color.neutral.950}',
+    /** elev-2. Nested panels, raised cards. */
+    overlay: '{color.neutral.900}',
+    /** elev-3. Popovers, menus, tooltips. */
+    floating: '{color.neutral.900}',
+    /** elev-4. Dialogs and sheets. */
+    modal: '{color.neutral.900}',
+    /** Secondary button and inert chip — a surface you press. */
+    subtle: '{color.neutral.900}',
+    /**
+     * An input — a surface you write into, which is a different job from one
+     * you press. Sharing a token forced one value to read as both raised and
+     * recessed, and in the light theme it made the field a gray box.
+     */
+    field: '{color.neutral.900}',
+    'subtle-hover': '{color.neutral.850}',
+    'subtle-active': '{color.neutral.800}',
+    /** Translucent washes. These work on any surface, including inside an overlay. */
+    'state-hover': '{color.state.hover-dark}',
+    'state-active': '{color.state.active-dark}',
+    selection: '{color.state.selection-dark}',
+    /**
+     * A control knob — the switch thumb.
+     *
+     * Light in BOTH themes, which is why it needs its own token: it has to read
+     * against a dark off-track, a light off-track and an orange on-track, and no
+     * existing surface token is light in both. Pointing it at
+     * `surface-floating` made it exactly the color of the disabled track it sat
+     * on, so a disabled switch showed no thumb at all.
+     */
+    knob: '{color.neutral.50}',
+    /** An intentionally inverted card, in the opposite theme's ground. */
+    inverse: '{color.neutral.50}',
+    /** The primary action. Brightens on hover — the label is near-black. */
+    accent: '{color.orange.base}',
+    'accent-hover': '{color.orange.bright}',
+    'accent-active': '{color.orange.dim}',
+    /** A quiet accent-tinted surface: selected row, highlighted panel. */
+    'accent-subtle': '{color.orange.surface-dark}',
+    'accent-subtle-hover': '{color.orange.surface-dark-hover}',
+    disabled: '{color.neutral.900}',
+    /** Flat tint. No backdrop-filter, ever. */
+    scrim: '{color.neutral.1000}',
+  },
+  ink: {
+    primary: '{color.neutral.50}',
+    secondary: '{color.neutral.300}',
+    tertiary: '{color.neutral.450}',
+    placeholder: '{color.neutral.450}',
+    /** Exempt from 1.4.3, but still perceivable. */
+    disabled: '{color.neutral.600}',
+    /** The one brand accent legal as text. */
+    accent: '{color.orange.base}',
+    /**
+     * Accent text on the quiet accent surface — an accent badge or a selected
+     * row. A separate token because the accent chip is darker than the page
+     * ground in the light theme, so the general `ink-accent` step (solved
+     * against the page) fails inside the very component it is for. Same shape
+     * as the status chips.
+     */
+    'on-accent-subtle': '{color.orange.base}',
+    /** On any warm fill or gradient. Never white. */
+    'on-accent': '{color.neutral.1000}',
+    /** Text on any warm gradient. Measured at the gradient's worst stop. */
+    'on-gradient': '{color.neutral.1000}',
+    /**
+     * Text on a scrimmed surface. Light in BOTH themes, which is why it needs
+     * its own token.
+     *
+     * A scrim is near-black whatever the theme, so a light-theme caller reaching
+     * for `ink-primary` gets near-black text on a near-black surface. That is
+     * exactly what happened, and it is invisible until someone looks at the
+     * light theme.
+     *
+     * Both steps are measured against the WORST scrimmed result, which is not a
+     * gradient stop at all: `glow` fades to transparent, so the scrim can end up
+     * over the light theme's white page. Over that blend (#595856) the primary
+     * step reads 6.18:1 and the secondary 4.67:1. Every real gradient is darker
+     * than the worst case, so these are floors.
+     */
+    'on-scrim': '{color.neutral.50}',
+    'on-scrim-secondary': '{color.neutral.200}',
+    inverse: '{color.neutral.1000}',
+    link: '{color.orange.base}',
+    'link-hover': '{color.orange.bright}',
+  },
+  /**
+   * Border names encode the WCAG 1.4.11 requirement rather than a visual weight.
+   *
+   * `border-default` used to sit here at neutral-800 and read 1.29:1 against the
+   * page ground — an input border a sighted user could barely find. Naming a
+   * token by how heavy it looks invites exactly that: a developer reaches for
+   * "default" on a text field and silently ships a 1.4.11 failure. Naming it by
+   * what it must do makes the correct choice the obvious one.
+   */
+  line: {
+    /** Dividers and decorative card hairlines. Exempt from 1.4.11 — and barred
+     *  from interactive controls by lint, because that exemption is the whole
+     *  reason it is allowed to be this quiet. */
+    subtle: '{color.neutral.850}',
+    /**
+     * Structural separation: a footer bar, a toolbar edge, a section rule.
+     *
+     * The scale was missing a middle step. `subtle` is a hairline meant to
+     * disappear and `strong` is emphasis — a divider that has to actually read
+     * as a division sits between them, and pressing either into service made
+     * the barred dialog footer either invisible or shouty.
+     */
+    divider: '{color.neutral.800}',
+    /**
+     * Matches `surface-subtle-active` (neutral-800) by explicit product
+     * decision, for a border that sits almost on the fill.
+     *
+     * This is BELOW the WCAG 1.4.11 floor: 1.29:1 against the field, where 3:1
+     * is required for a boundary that identifies a control. Nothing else
+     * identifies a dark input — the fill is 1.28:1 from the page — so in the
+     * dark theme a field is found by its placeholder and its label rather than
+     * by its edge.
+     *
+     * Recorded as a declared waiver in CONTRAST_WAIVERS, not as an oversight,
+     * so the accessibility statement can report it honestly.
+     */
+    control: '{color.neutral.800}',
+    /** Emphasis, selection, structural separation that carries meaning. >= 3:1. */
+    strong: '{color.neutral.450}',
+    focus: '{color.orange.base}',
+    /** The halo behind a focused field. Accent at low alpha. */
+    'focus-glow': '{color.state.focus-glow}',
+    accent: '{color.orange.border-dark}',
+    /** Disabled controls are exempt from contrast minimums (WCAG 1.4.3/1.4.11). */
+    disabled: '{color.neutral.850}',
+    /** Replaces a shadow at elev-3/4 — a shadow is invisible on near-black. */
+    'edge-highlight': '{color.neutral.700}',
+  },
+  status: {
+    'success-solid': '{color.success.solid}',
+    'success-on-solid': '{color.success.on-solid}',
+    'success-ink': '{color.success.text-dark}',
+    'success-surface': '{color.success.surface-dark}',
+    'success-line': '{color.success.border-dark}',
+    'warning-solid': '{color.warning.solid}',
+    'warning-on-solid': '{color.warning.on-solid}',
+    'warning-ink': '{color.warning.text-dark}',
+    'warning-surface': '{color.warning.surface-dark}',
+    'warning-line': '{color.warning.border-dark}',
+    'error-solid': '{color.error.solid}',
+    'error-on-solid': '{color.error.on-solid}',
+    'error-ink': '{color.error.text-dark}',
+    'error-surface': '{color.error.surface-dark}',
+    'error-line': '{color.error.border-dark}',
+    // The one declared brand alias: info IS teal. See STATUS_ALIAS_EXCEPTIONS.
+    'info-solid': '{color.teal.base}',
+    'info-on-solid': '{color.neutral.1000}',
+    'info-ink': '{color.teal.base}',
+    'info-surface': '{color.teal.surface-dark}',
+    'info-line': '{color.teal.border-dark}',
+  },
+  viz: {
+    // Ordered by maximum hue separation first. Beyond series 4, change the
+    // encoding rather than reaching for series 5.
+    1: '{color.orange.base}',
+    2: '{color.teal.base}',
+    3: '{color.yellow.base}',
+    4: '{color.pink.base}',
+    5: '{color.coral.base}',
+    6: '{color.peach.base}',
+    7: '{color.neutral.300}',
+    grid: '{color.neutral.850}',
+    axis: '{color.neutral.450}',
+    // The "heat" ramp — generated with even lightness steps, not assembled
+    // from brand anchors. See heatRamp() in scripts/derive-tokens.ts.
+    'sequential-0': '{color.heat.dark.0}',
+    'sequential-1': '{color.heat.dark.1}',
+    'sequential-2': '{color.heat.dark.2}',
+    'sequential-3': '{color.heat.dark.3}',
+    'sequential-4': '{color.heat.dark.4}',
+    'diverging-neg-2': '{color.teal.dim}',
+    'diverging-neg-1': '{color.teal.bright}',
+    'diverging-0': '{color.neutral.500}',
+    'diverging-pos-1': '{color.orange.bright}',
+    'diverging-pos-2': '{color.orange.dim}',
+  },
+  gradient: {
+    ember: 'linear-gradient(135deg, {color.orange.base} 0%, {color.coral.base} 100%)',
+    solar:
+      'linear-gradient(135deg, {color.orange.base} 0%, {color.amber.base} 50%, {color.yellow.base} 100%)',
+    dusk: 'linear-gradient(135deg, {color.coral.base} 0%, {color.pink.base} 100%)',
+    glow: 'radial-gradient(circle at 50% 0%, {color.orange.surface-dark} 0%, transparent 70%)',
+    ground: 'linear-gradient(180deg, {color.neutral.1000} 0%, {color.neutral.950} 100%)',
+  },
+  elevation: {
+    /**
+     * elev-1: a card on the page. No shadow — the fill delta carries it
+     * (ground -> raised is 0.099 L here).
+     */
+    1: '{shadow.none}',
+    /**
+     * elev-2: a panel nested inside a card. Still no shadow in this theme,
+     * because raised -> overlay is 0.046 L and clears the separation floor on
+     * fill alone. The light theme cannot do that and takes a shadow instead —
+     * which is the point of expressing elevation per theme rather than per
+     * component.
+     */
+    2: '{shadow.none}',
+    3: '{shadow.md}',
+    4: '{shadow.lg}',
+  },
+};
+
+/* -------------------------------------------------------------------------- */
+/* Light — a peer, not an inversion                                            */
+/* -------------------------------------------------------------------------- */
+
+export const light: SemanticTheme = {
+  surface: {
+    // White page. The card therefore steps DOWN rather than up — with a white
+    // ground there is nowhere lighter to go, and the aesthetic direction wants
+    // depth from surface contrast rather than from an outline on every card.
+    ground: '{color.neutral.0}',
+    /**
+     * A near-white card, not a gray one.
+     *
+     * That leaves only 0.022 L between card and page — below the 0.04
+     * adjacent-surface rule — so the card's hairline border carries the
+     * separation instead. This is the one place the "a surface change and a
+     * border are alternatives" principle is relaxed, and it is relaxed because
+     * with a white ground there is no lighter step to move to.
+     */
+    raised: '{color.neutral.25}',
+    // Floating surfaces return to white and rely on their shadow, so a popover
+    // still reads as above the page rather than sunk into it.
+    overlay: '{color.neutral.0}',
+    floating: '{color.neutral.0}',
+    modal: '{color.neutral.0}',
+    subtle: '{color.neutral.100}',
+    // Near-white: a field you write into should read as paper, not as a button.
+    field: '{color.neutral.25}',
+    'subtle-hover': '{color.neutral.200}',
+    'subtle-active': '{color.neutral.300}',
+    'state-hover': '{color.state.hover-light}',
+    'state-active': '{color.state.active-light}',
+    selection: '{color.state.selection-light}',
+    knob: '{color.neutral.0}',
+    inverse: '{color.neutral.1000}',
+    accent: '{color.orange.base}',
+    'accent-hover': '{color.orange.bright}',
+    'accent-active': '{color.orange.dim}',
+    'accent-subtle': '{color.orange.surface-light}',
+    'accent-subtle-hover': '{color.orange.surface-light-hover}',
+    disabled: '{color.neutral.100}',
+    scrim: '{color.neutral.1000}',
+  },
+  ink: {
+    primary: '{color.neutral.1000}',
+    secondary: '{color.neutral.700}',
+    tertiary: '{color.neutral.600}',
+    // A shade darker than tertiary: placeholders sit inside surface-subtle
+    // (neutral-100), which is darker than the page ground. neutral-600 reads
+    // 4.05:1 there — a placeholder that fails AA in the one place it appears.
+    placeholder: '{color.neutral.700}',
+    disabled: '{color.neutral.400}',
+    // NOT the brand orange: #FF641F reads 2.96:1 on white. This is the solved
+    // darkened step — the lightest orange that can legally carry text.
+    accent: '{color.orange.text-light}',
+    // Solved against the accent chip, not the page ground — the chip is darker.
+    'on-accent-subtle': '{color.orange.text-on-chip-light}',
+    'on-accent': '{color.neutral.1000}',
+    'on-gradient': '{color.neutral.1000}',
+    'on-scrim': '{color.neutral.50}',
+    'on-scrim-secondary': '{color.neutral.200}',
+    inverse: '{color.neutral.0}',
+    link: '{color.orange.text-light}',
+    // NOT orange.dim: that is a full-saturation step and reads 2.8:1 on white.
+    // Light-theme hover goes deeper, not brighter.
+    'link-hover': '{color.orange.text-light-strong}',
+  },
+  line: {
+    subtle: '{color.neutral.100}',
+    divider: '{color.neutral.200}',
+    /**
+     * Matches `surface-subtle` (neutral-100) by explicit product decision — the
+     * light-theme counterpart to the dark border sitting on its fill.
+     *
+     * BELOW the WCAG 1.4.11 floor: about 1.21:1 against the field where 3:1 is
+     * required. Declared in CONTRAST_WAIVERS rather than un-asserted.
+     */
+    control: '{color.neutral.100}',
+    strong: '{color.neutral.700}',
+    /**
+     * The brand orange, identical to the dark theme, so the accent does not
+     * shift between themes. Product decision.
+     *
+     * It reads 2.96:1 against a white page where 1.4.11 wants 3:1 — a shortfall
+     * of about 1%, as opposed to the border's 60%. Declared as a waiver so the
+     * difference in severity is visible rather than lumped together.
+     */
+    focus: '{color.orange.base}',
+    'focus-glow': '{color.state.focus-glow}',
+    accent: '{color.orange.border-light}',
+    disabled: '{color.neutral.200}',
+    'edge-highlight': '{color.neutral.100}',
+  },
+  status: {
+    'success-solid': '{color.success.solid}',
+    'success-on-solid': '{color.success.on-solid}',
+    'success-ink': '{color.success.text-light}',
+    'success-surface': '{color.success.surface-light}',
+    'success-line': '{color.success.border-light}',
+    'warning-solid': '{color.warning.solid}',
+    'warning-on-solid': '{color.warning.on-solid}',
+    'warning-ink': '{color.warning.text-light}',
+    'warning-surface': '{color.warning.surface-light}',
+    'warning-line': '{color.warning.border-light}',
+    'error-solid': '{color.error.solid}',
+    'error-on-solid': '{color.error.on-solid}',
+    'error-ink': '{color.error.text-light}',
+    'error-surface': '{color.error.surface-light}',
+    'error-line': '{color.error.border-light}',
+    'info-solid': '{color.teal.base}',
+    'info-on-solid': '{color.neutral.1000}',
+    // Solved against the info chip specifically — the chip is darker than the
+    // page ground, so the page-ground solve failed inside the component itself.
+    'info-ink': '{color.teal.text-on-chip-light}',
+    'info-surface': '{color.teal.surface-light}',
+    'info-line': '{color.teal.border-light}',
+  },
+  viz: {
+    // Light-theme chart marks use the solved 3:1 steps: every brand accent at
+    // full saturation is invisible-adjacent on white.
+    1: '{color.orange.mark-light}',
+    2: '{color.teal.mark-light}',
+    3: '{color.yellow.mark-light}',
+    4: '{color.pink.mark-light}',
+    5: '{color.coral.mark-light}',
+    6: '{color.peach.mark-light}',
+    7: '{color.neutral.600}',
+    grid: '{color.neutral.100}',
+    axis: '{color.neutral.600}',
+    'sequential-0': '{color.heat.light.0}',
+    'sequential-1': '{color.heat.light.1}',
+    'sequential-2': '{color.heat.light.2}',
+    'sequential-3': '{color.heat.light.3}',
+    'sequential-4': '{color.heat.light.4}',
+    'diverging-neg-2': '{color.teal.text-light}',
+    'diverging-neg-1': '{color.teal.mark-light}',
+    'diverging-0': '{color.neutral.300}',
+    'diverging-pos-1': '{color.orange.mark-light}',
+    'diverging-pos-2': '{color.orange.text-light}',
+  },
+  gradient: {
+    ember: 'linear-gradient(135deg, {color.orange.base} 0%, {color.coral.base} 100%)',
+    solar:
+      'linear-gradient(135deg, {color.orange.base} 0%, {color.amber.base} 50%, {color.yellow.base} 100%)',
+    dusk: 'linear-gradient(135deg, {color.coral.base} 0%, {color.pink.base} 100%)',
+    glow: 'radial-gradient(circle at 50% 0%, {color.orange.surface-light} 0%, transparent 70%)',
+    ground: 'linear-gradient(180deg, {color.neutral.50} 0%, {color.neutral.100} 100%)',
+  },
+  elevation: {
+    /** elev-1: a card on the page. The hairline border carries it (see `raised`). */
+    1: '{shadow.none}',
+    /**
+     * elev-2: a panel nested inside a card. **This theme needs a shadow.**
+     *
+     * A white page means the elevation ramp runs out immediately: `raised` is
+     * neutral-25 and `overlay` returns to pure white, so a nested panel has the
+     * same fill as the page (0.000 L apart) and read as a hole punched in the
+     * card rather than a panel sitting on it. Fill cannot express this step
+     * here, so the shadow does.
+     */
+    2: '{shadow.sm}',
+    3: '{shadow.md}',
+    4: '{shadow.lg}',
+  },
+};
+
+export const themes = { dark, light } as const;
+export type ThemeName = keyof typeof themes;