@evolve.ui/theme-system 1.0.1 → 1.2.0

package/src/effects/tokens.ts

@@ -0,0 +1,148 @@
+/**
+ * Effect tokens live in their own `--effect-*` namespace.
+ * A name added to `CSSVariables` would have to be declared by every locked brand and would change dist CSS.
+ * Literal colours are allowed in token values. Rules may only carry `fx` references.
+ * `opaque` is what a token becomes when backdrop-filter is missing or transparency is unwanted.
+ */
+
+export type EffectTokenKind = 'paint' | 'filter' | 'shadow' | 'channels' | 'length' | 'font';
+
+export type EffectTokenSpec = {
+    readonly kind: EffectTokenKind;
+    readonly opaque?: string;
+    readonly default?: string;
+    readonly doc: string;
+};
+
+export const effectTokens = {
+    'solid-fill': { kind: 'paint', doc: 'Opaque colour every translucent fill collapses to in the fallbacks.' },
+    edge: { kind: 'paint', opaque: 'none', doc: 'Gradient painted through the 1px masked edge pseudo-element.' },
+
+    'surface-fill': { kind: 'paint', opaque: 'solid-fill', doc: 'Glass surface background (cards, panels).' },
+    'surface-filter': { kind: 'filter', opaque: 'none', doc: 'backdrop-filter for the surface tier.' },
+    'surface-shadow': { kind: 'shadow', doc: 'Full box-shadow list for the surface tier (inner highlight + drop).' },
+    'surface-radius': {
+        kind: 'length',
+        default: 'var(--container-border-radius)',
+        doc: 'Default-strength radius for opt-in glass; any radius utility on the element wins.',
+    },
+
+    'raised-fill': { kind: 'paint', opaque: 'solid-fill', doc: 'Raised tier background (dialogs, sheets, popovers).' },
+    'raised-filter': { kind: 'filter', opaque: 'none', doc: 'backdrop-filter for the raised tier.' },
+    'raised-shadow': { kind: 'shadow', doc: 'Full box-shadow list for the raised tier (highlight + halo + drop).' },
+
+    'scrim-fill': { kind: 'paint', opaque: 'solid-fill', doc: 'Scrim background (drag overlays). No edge, no shadow.' },
+    'scrim-filter': { kind: 'filter', opaque: 'none', doc: 'backdrop-filter for the scrim tier.' },
+
+    'tooltip-text': {
+        kind: 'paint',
+        default: 'rgb(var(--color-text-primary))',
+        doc: 'Text colour of the default tooltip (the semantic colour vars hold bare channels, hence rgb()). react-tooltip paints its own text colour (#222) and core only sets the background, so a dark-canvas brand must set it.',
+    },
+    'tooltip-text-inverse': {
+        kind: 'paint',
+        default: 'rgb(var(--color-text-inverse))',
+        doc: 'Text colour of the inverse tooltip (react-tooltip dark variant paints #fff on the inverse background).',
+    },
+
+    'overlay-text': {
+        kind: 'paint',
+        default: 'rgb(var(--color-text-primary))',
+        doc: 'Text colour of the valid-drag message in the drop overlay. Core hard-codes text-blue-600 there, which is unreadable on a dark scrim.',
+    },
+
+    'hover-fill': { kind: 'paint', opaque: 'solid-fill', doc: 'Surface background while hovered.' },
+
+    featured: { kind: 'shadow', doc: 'Gold featured card.' },
+    halo: { kind: 'shadow', doc: 'Blue navigation halo.' },
+    glow: { kind: 'shadow', doc: 'Primary glow.' },
+    hover: { kind: 'shadow', doc: 'Hovered drop target.' },
+    selected: { kind: 'shadow', doc: 'Selected file card.' },
+    success: { kind: 'shadow', doc: 'Completed file card.' },
+    error: { kind: 'shadow', doc: 'Errored file card.' },
+    'accept-glow': { kind: 'shadow', doc: 'Drag-accept frame glow (decoration).' },
+    'reject-glow': { kind: 'shadow', doc: 'Drag-reject frame glow (decoration).' },
+
+    dash: { kind: 'paint', doc: 'Drop zone frame at rest.' },
+    'dash-strong': { kind: 'paint', doc: 'Drop zone frame while hovered.' },
+    'dash-disabled': { kind: 'paint', doc: 'Drop zone frame while disabled.' },
+    'dash-accept': { kind: 'paint', doc: 'Overlay frame while a valid drag is over the zone.' },
+    'dash-reject': { kind: 'paint', doc: 'Overlay frame while an invalid drag is over the zone.' },
+
+    'cta-fill': { kind: 'paint', doc: 'Gold CTA background.' },
+    'cta-fill-hover': { kind: 'paint', doc: 'Gold CTA background while hovered.' },
+    'cta-ink-rgb': {
+        kind: 'channels',
+        doc: 'Ink channels remapped onto --color-text-inverse / --color-icon-inverse.',
+    },
+
+    'text-muted-rgb': {
+        kind: 'channels',
+        opaque: 'text-muted-solid-rgb',
+        doc: 'Muted text channels on translucent glass.',
+    },
+    'text-muted-solid-rgb': { kind: 'channels', doc: 'Muted text channels on the opaque fallback fill.' },
+
+    'text-success-rgb': {
+        kind: 'channels',
+        opaque: 'text-success-solid-rgb',
+        doc: 'Success (olive) text channels on translucent glass.',
+    },
+    'text-success-solid-rgb': { kind: 'channels', doc: 'Success text channels on the opaque fallback fill.' },
+    'text-critical-glass-rgb': {
+        kind: 'channels',
+        opaque: 'text-critical-solid-rgb',
+        doc: 'Critical text channels on translucent glass (lighter than the theme critical so it holds 4.5:1 over the brightest backdrop).',
+    },
+    'text-critical-solid-rgb': { kind: 'channels', doc: 'Critical text channels on the opaque fallback fill.' },
+
+    'font-accent': {
+        kind: 'font',
+        default: 'var(--font-family-primary)',
+        doc: 'Display font for hui-fx-accent-font. Serif stays off until hui-fx-serif remaps this token.',
+    },
+    'font-serif': { kind: 'font', doc: 'Serif stack assigned to --effect-font-accent by hui-fx-serif.' },
+    backdrop: { kind: 'paint', doc: 'Page backdrop layers for hui-fx-backdrop.' },
+} as const satisfies Record<string, EffectTokenSpec>;
+
+export type EffectTokenName = keyof typeof effectTokens;
+
+type TokensWithDefault = {
+    [K in EffectTokenName]: (typeof effectTokens)[K] extends { default: string } ? K : never;
+}[EffectTokenName];
+
+/** What an effect brand must provide. Tokens with a registry default may be omitted. */
+export type EffectTokenValues = { readonly [K in Exclude<EffectTokenName, TokensWithDefault>]: string } & {
+    readonly [K in TokensWithDefault]?: string;
+};
+
+export type EffectTokenRef<K extends EffectTokenName = EffectTokenName> = `var(--effect-${K})`;
+
+export type TokensOfKind<Kind extends EffectTokenKind> = {
+    [K in EffectTokenName]: (typeof effectTokens)[K]['kind'] extends Kind ? K : never;
+}[EffectTokenName];
+
+type Camel<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<Camel<Tail>>}` : S;
+
+/** Typed token references: `fx.surfaceFill === 'var(--effect-surface-fill)'`. */
+export type Fx = { readonly [K in EffectTokenName as Camel<K>]: EffectTokenRef<K> };
+
+const camelKey = (key: string): string => key.replace(/-([a-z0-9])/g, (_match, char: string) => char.toUpperCase());
+
+const buildFx = (): Fx =>
+    Object.fromEntries(
+        (Object.keys(effectTokens) as EffectTokenName[]).map((key) => [camelKey(key), `var(--effect-${key})`])
+    ) as Fx;
+
+export const fx: Fx = buildFx();
+
+const TOKEN_REF = /^var\(--effect-([a-z0-9-]+)\)$/;
+
+/** `'var(--effect-surface-fill)'` -> `'surface-fill'`. Anything else is undefined. */
+export const tokenOf = (ref: string): EffectTokenName | undefined => {
+    const name = TOKEN_REF.exec(ref)?.[1];
+    if (name === undefined || !Object.prototype.hasOwnProperty.call(effectTokens, name)) {
+        return undefined;
+    }
+    return name as EffectTokenName;
+};