@evolve.ui/theme-system 1.1.0 → 1.2.0

package/src/effects/brands/EverydayHarbor.ts

@@ -0,0 +1,392 @@
+/**
+ * Everyday Harbor effect layer: glass v2 on the ink canvas.
+ *
+ * `harborGlass` is the one data object. The `--effect-*` token strings are rendered from it by the pure functions
+ * below, and `glassContrast.spec.ts` reads the same object, so the contrast proof measures the values that ship.
+ * Values follow the approved render (.g2 .feat .navglow .dlg2 .btnglow); change them here, not in the tokens.
+ *
+ * Structural hooks (select.menu, toast, dropzone*, dropzoneOverlay*) are bound here and each one has a
+ * `witness('<id>'` call in apps/docs/stories/Brands/EverydayHarbor (scripts/lib/effect-witness.spec.ts enforces it).
+ * `modal.backdrop` is deliberately NOT bound: a filtered backdrop becomes the backdrop root, so the dialog would
+ * blur the scrim instead of the page.
+ *
+ * Pseudo-slot plan: every material edge lands on the first free slot (`::before`, or `::after` on bottomSheet).
+ * The only decorations are the dropzone's inner dashed frame and the drag overlay's frame, both on `::after`.
+ * The validator does not cross-check two hook ids on one element, so the dropzone state rules rely on source order:
+ * disabled, then dragging, then error, each with a `hover` twin because `:hover` out-ranks the state class.
+ */
+import type { BrandEffectRule, EffectLayer } from '../rules';
+
+import { fx, type EffectTokenValues } from '../tokens';
+
+export type Rgb = readonly [number, number, number];
+
+export type GlassTier = {
+    /** Alpha of the tint over the backdrop. */
+    readonly alpha: number;
+    /** Alpha of the white sheen that starts the 160deg gradient. */
+    readonly sheen: number;
+    readonly blur: number;
+};
+
+export type Glow = {
+    readonly rgb: Rgb;
+    readonly alpha: number;
+    readonly at: `${number}% ${number}%`;
+    readonly reach: `${number}%`;
+};
+
+export type Shadow = { readonly alpha: number; readonly blur: number; readonly y: number };
+
+export type Stop = { readonly alpha: number; readonly at: number | null; readonly rgb: Rgb };
+
+/** The whole data object. Every value the tokens render from is typed here, so a typo cannot slip through as `unknown`. */
+export type HarborGlass = {
+    readonly ink: Rgb;
+    readonly solid: Rgb;
+    readonly tint: Rgb;
+    readonly saturate: number;
+    readonly surface: GlassTier;
+    readonly raised: GlassTier;
+    readonly surfaceRadius: number;
+    readonly shine: { readonly raised: number; readonly surface: number };
+    readonly rim: number;
+    readonly raisedHalo: { readonly alpha: number; readonly blur: number; readonly rgb: Rgb };
+    readonly drop: {
+        readonly raised: Shadow;
+        readonly surface: Shadow;
+        /** Hover, selected, success and error cards: the surface drop, lighter. */
+        readonly state: Shadow;
+    };
+    readonly edge: { readonly angle: number; readonly stops: readonly Stop[] };
+    readonly scrim: { readonly alpha: number; readonly blur: number };
+    readonly hoverTint: { readonly alpha: number; readonly rgb: Rgb; readonly sheen: number };
+    readonly featured: {
+        readonly rgb: Rgb;
+        readonly ringAlpha: number;
+        readonly glowAlpha: number;
+        readonly glowBlur: number;
+    };
+    readonly halo: { readonly rgb: Rgb; readonly alpha: number; readonly blur: number };
+    readonly glow: { readonly rgb: Rgb; readonly alpha: number; readonly blur: number };
+    readonly hover: { readonly rgb: Rgb; readonly alpha: number; readonly blur: number; readonly shine: number };
+    readonly selected: {
+        readonly rgb: Rgb;
+        readonly ringAlpha: number;
+        readonly glowAlpha: number;
+        readonly glowBlur: number;
+    };
+    readonly success: { readonly rgb: Rgb; readonly ringAlpha: number };
+    readonly error: { readonly ringAlpha: number };
+    readonly accept: {
+        readonly rgb: Rgb;
+        readonly glowAlpha: number;
+        readonly insetAlpha: number;
+        readonly blur: number;
+        readonly dashAlpha: number;
+    };
+    readonly reject: {
+        readonly glowAlpha: number;
+        readonly insetAlpha: number;
+        readonly blur: number;
+        readonly dashAlpha: number;
+    };
+    readonly dash: {
+        readonly rgb: Rgb;
+        readonly rest: number;
+        readonly strong: number;
+        readonly disabledRgb: Rgb;
+        readonly disabled: number;
+    };
+    readonly cta: {
+        readonly angle: number;
+        readonly stops: readonly [string, string, string];
+        readonly mid: number;
+        readonly hoverAngle: number;
+        readonly hoverMid: number;
+        readonly ink: Rgb;
+    };
+    readonly mutedOnGlass: Rgb;
+    readonly mutedOnSolid: Rgb;
+    readonly criticalOnGlass: Rgb;
+    readonly criticalOnSolid: Rgb;
+    readonly successOnGlass: Rgb;
+    readonly successOnSolid: Rgb;
+    readonly glows: readonly Glow[];
+    readonly serif: string;
+};
+
+export const harborGlass: HarborGlass = {
+    /** #0B1626, the page canvas and the scrim. */
+    ink: [11, 22, 38],
+    /** #12223A, what every translucent fill collapses to in the fallbacks. */
+    solid: [18, 34, 58],
+    /** rgba(14,28,48,a): the glass tint. */
+    tint: [14, 28, 48],
+    saturate: 180,
+    /** .g2 */
+    surface: { alpha: 0.42, blur: 18, sheen: 0.09 },
+    /** .dlg2 */
+    raised: { alpha: 0.58, blur: 26, sheen: 0.1 },
+    surfaceRadius: 18,
+    /** Inner highlight on each tier (.g2 .22, .dlg2 .25). */
+    shine: { raised: 0.25, surface: 0.22 },
+    /** Hairline ring inside .g2. */
+    rim: 0.06,
+    /** .dlg2 halo and drops. */
+    raisedHalo: { alpha: 0.22, blur: 40, rgb: [142, 197, 232] },
+    drop: {
+        raised: { alpha: 0.55, blur: 80, y: 30 },
+        surface: { alpha: 0.45, blur: 60, y: 20 },
+        state: { alpha: 0.4, blur: 60, y: 20 },
+    },
+    /** .g2::before gradient border. */
+    edge: {
+        angle: 135,
+        stops: [
+            { alpha: 0.45, at: null, rgb: [255, 255, 255] },
+            { alpha: 0.06, at: 35, rgb: [255, 255, 255] },
+            { alpha: 0.1, at: 65, rgb: [142, 197, 232] },
+            { alpha: 0.4, at: null, rgb: [142, 197, 232] },
+        ],
+    },
+    /** Scrim tier. Not in the brief's CSS; the fixture values. */
+    scrim: { alpha: 0.45, blur: 10 },
+    hoverTint: { alpha: 0.3, rgb: [46, 107, 166], sheen: 0.12 },
+    /** .feat */
+    featured: { rgb: [227, 179, 65], ringAlpha: 0.45, glowAlpha: 0.28, glowBlur: 36 },
+    /** .navglow */
+    halo: { rgb: [46, 107, 166], alpha: 0.35, blur: 28 },
+    /** .btnglow */
+    glow: { rgb: [46, 107, 166], alpha: 0.55, blur: 24 },
+    hover: { rgb: [46, 107, 166], alpha: 0.4, blur: 28, shine: 0.25 },
+    selected: { rgb: [227, 179, 65], ringAlpha: 0.55, glowAlpha: 0.28, glowBlur: 32 },
+    /** Olive on glass, #B4C15A. */
+    success: { rgb: [180, 193, 90], ringAlpha: 0.35 },
+    /** Error uses the theme's critical border channels, not a literal red. */
+    error: { ringAlpha: 0.45 },
+    accept: { rgb: [227, 179, 65], glowAlpha: 0.3, insetAlpha: 0.12, blur: 36, dashAlpha: 0.9 },
+    reject: { glowAlpha: 0.28, insetAlpha: 0.1, blur: 36, dashAlpha: 0.9 },
+    dash: { rgb: [142, 197, 232], rest: 0.4, strong: 0.85, disabledRgb: [185, 197, 211], disabled: 0.35 },
+    cta: {
+        /** Base angle is not in the brief (only the hover is); 90deg follows the fixture. */
+        angle: 90,
+        stops: ['#f2cf7a', '#e3b341', '#d9963e'],
+        mid: 55,
+        /** Brief: linear-gradient(180deg,#f2cf7a,#e3b341 40%,#d9963e). */
+        hoverAngle: 180,
+        hoverMid: 40,
+        ink: [11, 22, 38],
+    },
+    /** #B9C5D3 on glass, #A9B6C6 on solid. */
+    mutedOnGlass: [185, 197, 211],
+    mutedOnSolid: [169, 182, 198],
+    /** Olive text on glass, #B4C15A (4.03:1 at the shipped #A3B04E against the brightest glow). */
+    successOnGlass: [180, 193, 90],
+    /** #A3B04E, the theme's success-400, on the opaque fallback fill. */
+    successOnSolid: [163, 176, 78],
+    /** Critical text on glass, #F7A29D (theme critical #EA756F is 4.21:1 on the brightest list card). */
+    criticalOnGlass: [247, 162, 157],
+    /** The theme critical, #EA756F, on the opaque fallback fill. */
+    criticalOnSolid: [234, 117, 111],
+    /**
+     * Ambient backdrop: harbor-blue and gold-olive glows over the ink canvas.
+     * The brightest centre is the lightest glow colour at its alpha over #0B1626 (currently the gold glow, #4C452E).
+     * The blue alpha is capped at 0.38: at the 0.45 the fixture uses, gold (4.47) and olive (4.44) on .g2 fall
+     * under 4.5:1 over that centre (glassContrast.spec.ts).
+     */
+    glows: [
+        { alpha: 0.38, at: '18% 12%', reach: '38%', rgb: [91, 155, 216] },
+        { alpha: 0.3, at: '85% 80%', reach: '42%', rgb: [227, 179, 65] },
+        { alpha: 0.18, at: '70% 20%', reach: '36%', rgb: [163, 176, 78] },
+    ],
+    serif: "'Source Serif 4', Georgia, serif",
+};
+
+type Harbor = HarborGlass;
+
+const rgba = ([r, g, b]: Rgb, alpha: number): string => `rgba(${r}, ${g}, ${b}, ${alpha})`;
+const channels = ([r, g, b]: Rgb): string => `${r} ${g} ${b}`;
+const hex = ([r, g, b]: Rgb): string => `#${[r, g, b].map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+const critical = (alpha: number): string => `rgb(var(--color-border-critical) / ${Math.round(alpha * 100)}%)`;
+const WHITE: Rgb = [255, 255, 255];
+
+const highlight = (alpha: number): string => `inset 0 1px 0 ${rgba(WHITE, alpha)}`;
+const drop = (d: { alpha: number; blur: number; y: number }): string =>
+    `0 ${d.y}px ${d.blur}px rgba(0, 0, 0, ${d.alpha})`;
+const ring = (colour: string): string => `0 0 0 1px ${colour}`;
+const bloom = (blur: number, colour: string): string => `0 0 ${blur}px ${colour}`;
+
+export const renderGlassFill = (glass: Harbor, tier: GlassTier): string =>
+    `linear-gradient(160deg, ${rgba(WHITE, tier.sheen)}, rgba(255, 255, 255, 0) 45%), ${rgba(glass.tint, tier.alpha)}`;
+
+export const renderGlassFilter = (glass: Harbor, tier: GlassTier): string =>
+    `blur(${tier.blur}px) saturate(${glass.saturate}%)`;
+
+export const renderEdge = (glass: Harbor): string =>
+    `linear-gradient(${glass.edge.angle}deg, ${glass.edge.stops
+        .map((stop) => `${rgba(stop.rgb, stop.alpha)}${stop.at === null ? '' : ` ${stop.at}%`}`)
+        .join(', ')})`;
+
+export const renderCta = (glass: Harbor, angle: number, mid: number): string => {
+    const [light, base, deep] = glass.cta.stops;
+    return `linear-gradient(${angle}deg, ${light}, ${base} ${mid}%, ${deep})`;
+};
+
+export const renderBackdrop = (glass: Harbor): string =>
+    [
+        ...glass.glows.map(
+            (glow) => `radial-gradient(circle at ${glow.at}, ${rgba(glow.rgb, glow.alpha)}, transparent ${glow.reach})`
+        ),
+        hex(glass.ink),
+    ].join(', ');
+
+export const renderHarborTokens = (glass: Harbor): EffectTokenValues => ({
+    'accept-glow': `${bloom(glass.accept.blur, rgba(glass.accept.rgb, glass.accept.glowAlpha))}, inset 0 0 ${glass.accept.blur}px ${rgba(glass.accept.rgb, glass.accept.insetAlpha)}`,
+    backdrop: renderBackdrop(glass),
+    'cta-fill': renderCta(glass, glass.cta.angle, glass.cta.mid),
+    'cta-fill-hover': renderCta(glass, glass.cta.hoverAngle, glass.cta.hoverMid),
+    'cta-ink-rgb': channels(glass.cta.ink),
+    dash: rgba(glass.dash.rgb, glass.dash.rest),
+    'dash-accept': rgba(glass.accept.rgb, glass.accept.dashAlpha),
+    'dash-disabled': rgba(glass.dash.disabledRgb, glass.dash.disabled),
+    'dash-reject': critical(glass.reject.dashAlpha),
+    'dash-strong': rgba(glass.dash.rgb, glass.dash.strong),
+    edge: renderEdge(glass),
+    error: `${highlight(glass.shine.surface)}, ${ring(critical(glass.error.ringAlpha))}, ${drop(glass.drop.state)}`,
+    featured: `${highlight(glass.shine.surface)}, ${ring(rgba(glass.featured.rgb, glass.featured.ringAlpha))}, ${bloom(glass.featured.glowBlur, rgba(glass.featured.rgb, glass.featured.glowAlpha))}, ${drop(glass.drop.surface)}`,
+    'font-serif': glass.serif,
+    glow: bloom(glass.glow.blur, rgba(glass.glow.rgb, glass.glow.alpha)),
+    halo: `${highlight(glass.shine.surface)}, ${bloom(glass.halo.blur, rgba(glass.halo.rgb, glass.halo.alpha))}, ${drop(glass.drop.surface)}`,
+    hover: `${highlight(glass.hover.shine)}, ${bloom(glass.hover.blur, rgba(glass.hover.rgb, glass.hover.alpha))}, ${drop(glass.drop.state)}`,
+    'hover-fill': `linear-gradient(160deg, ${rgba(WHITE, glass.hoverTint.sheen)}, rgba(255, 255, 255, 0) 45%), ${rgba(glass.hoverTint.rgb, glass.hoverTint.alpha)}`,
+    'raised-fill': renderGlassFill(glass, glass.raised),
+    'raised-filter': renderGlassFilter(glass, glass.raised),
+    'raised-shadow': `${highlight(glass.shine.raised)}, ${bloom(glass.raisedHalo.blur, rgba(glass.raisedHalo.rgb, glass.raisedHalo.alpha))}, ${drop(glass.drop.raised)}`,
+    'reject-glow': `${bloom(glass.reject.blur, critical(glass.reject.glowAlpha))}, inset 0 0 ${glass.reject.blur}px ${critical(glass.reject.insetAlpha)}`,
+    'scrim-fill': rgba(glass.ink, glass.scrim.alpha),
+    'scrim-filter': `blur(${glass.scrim.blur}px) saturate(${glass.saturate}%)`,
+    selected: `${highlight(glass.shine.surface)}, ${ring(rgba(glass.selected.rgb, glass.selected.ringAlpha))}, ${bloom(glass.selected.glowBlur, rgba(glass.selected.rgb, glass.selected.glowAlpha))}, ${drop(glass.drop.state)}`,
+    'solid-fill': hex(glass.solid),
+    success: `${highlight(glass.shine.surface)}, ${ring(rgba(glass.success.rgb, glass.success.ringAlpha))}, ${drop(glass.drop.state)}`,
+    'surface-fill': renderGlassFill(glass, glass.surface),
+    'surface-filter': renderGlassFilter(glass, glass.surface),
+    'surface-radius': `${glass.surfaceRadius}px`,
+    'surface-shadow': `${highlight(glass.shine.surface)}, inset 0 0 0 1px ${rgba(WHITE, glass.rim)}, ${drop(glass.drop.surface)}`,
+    'text-critical-glass-rgb': channels(glass.criticalOnGlass),
+    'text-critical-solid-rgb': channels(glass.criticalOnSolid),
+    'text-muted-rgb': channels(glass.mutedOnGlass),
+    'text-muted-solid-rgb': channels(glass.mutedOnSolid),
+    'text-success-rgb': channels(glass.successOnGlass),
+    'text-success-solid-rgb': channels(glass.successOnSolid),
+});
+
+/** Inside glass, muted and success text move to their glass values. The fallback blocks remap them back to the solid values. */
+const glassText = { '--color-text-secondary': fx.textMutedRgb, '--color-text-success': fx.textSuccessRgb } as const;
+
+/** Errored cards sit on bright glass: critical text moves to the glass value (the fallbacks remap it back). */
+const criticalText = { '--color-text-critical': fx.textCriticalGlassRgb } as const;
+
+const raisedHooks = [
+    'modal',
+    'drawer',
+    'bottomSheet',
+    'menu',
+    'tooltip',
+    'datePicker.popover',
+    'timePicker.popover',
+] as const;
+
+/**
+ * Order matters: state rules come after their root, and error comes last so it wins over selected.
+ * A card's hover fill is covered by the `when: 'hover'` rule; the grid card's focus-within is acknowledged
+ * because the component paints that state itself.
+ */
+export const harborRules: readonly BrandEffectRule[] = [
+    ...raisedHooks.map((on): BrandEffectRule => ({ on, material: 'raised', vars: glassText })),
+    // react-tooltip paints its own text colour (#222 light, #fff dark) and core sets only the background, so the
+    // hooks carry the text colour: pale on the glass tooltip, navy on the pale inverse tooltip.
+    { on: 'tooltip', paint: { color: fx.tooltipText } },
+    { on: 'tooltip.inverse', paint: { color: fx.tooltipTextInverse } },
+
+    { on: 'select.menu', material: 'raised', vars: glassText },
+    { on: 'toast', material: 'surface', vars: glassText },
+
+    {
+        on: 'dropzone',
+        material: 'surface',
+        vars: glassText,
+        after: {
+            borderColor: fx.dash,
+            borderRadius: 'inherit',
+            borderStyle: 'dashed',
+            borderWidth: '1px',
+            inset: '6px',
+        },
+    },
+    {
+        on: 'dropzone',
+        when: 'hover',
+        unless: '[aria-disabled="true"]',
+        paint: { background: fx.hoverFill },
+        after: { borderColor: fx.dashStrong },
+    },
+    {
+        on: 'dropzone',
+        when: 'active',
+        unless: '[aria-disabled="true"]',
+        paint: { background: fx.hoverFill },
+    },
+    { on: 'dropzone.disabled', after: { borderColor: fx.dashDisabled } },
+    { on: 'dropzone.dragging', after: { borderColor: fx.dashAccept, boxShadow: fx.acceptGlow } },
+    { on: 'dropzone.dragging', when: 'hover', after: { borderColor: fx.dashAccept, boxShadow: fx.acceptGlow } },
+    { on: 'dropzone.error', shadow: 'error', after: { borderColor: fx.dashReject, boxShadow: fx.rejectGlow } },
+    { on: 'dropzone.error', when: 'hover', after: { borderColor: fx.dashReject, boxShadow: fx.rejectGlow } },
+
+    {
+        on: 'dropzoneOverlay.accept',
+        material: 'scrim',
+        after: {
+            borderColor: fx.dashAccept,
+            borderRadius: 'inherit',
+            borderStyle: 'dashed',
+            borderWidth: '2px',
+            boxShadow: fx.acceptGlow,
+            inset: '8px',
+        },
+    },
+    {
+        on: 'dropzoneOverlay.reject',
+        material: 'scrim',
+        after: {
+            borderColor: fx.dashReject,
+            borderRadius: 'inherit',
+            borderStyle: 'dashed',
+            borderWidth: '2px',
+            boxShadow: fx.rejectGlow,
+            inset: '8px',
+        },
+    },
+
+    // core hard-codes text-blue-600 for the valid-drag message (near-black on the ink scrim).
+    { on: 'overlayDragText.valid', paint: { color: fx.overlayText } },
+
+    { on: 'listFileCard', material: 'surface', vars: glassText },
+    { on: 'listFileCard', when: 'hover', paint: { background: fx.hoverFill } },
+    { on: 'listFileCard.uploading', shadow: 'glow' },
+    { on: 'listFileCard.complete', shadow: 'success' },
+    { on: 'listFileCard.selected', shadow: 'selected' },
+    { on: 'listFileCard.error', shadow: 'error', vars: criticalText },
+
+    { on: 'gridFileCard', material: 'surface', vars: glassText, acknowledge: ['focus-within'] },
+    { on: 'gridFileCard', when: 'hover', paint: { background: fx.hoverFill } },
+    { on: 'gridFileCard.uploading', shadow: 'glow' },
+    { on: 'gridFileCard.complete', shadow: 'success' },
+    { on: 'gridFileCard.selected', shadow: 'selected' },
+    { on: 'gridFileCard.error', shadow: 'error', vars: criticalText },
+];
+
+export const everydayHarborEffects: EffectLayer = {
+    rules: harborRules,
+    tokens: renderHarborTokens(harborGlass),
+};

package/src/effects/classes.ts

@@ -0,0 +1,19 @@
+/**
+ * Opt-in effect classes. They do nothing unless an effect brand sheet scopes them.
+ * `none` removes one element from every effect selector.
+ * An opt-in edge takes `::before` with `!important`, so `before:` utilities on the same element are overridden.
+ */
+export const effectClasses = {
+    glass: 'hui-fx-glass',
+    glassRaised: 'hui-fx-glass-raised',
+    featured: 'hui-fx-featured',
+    halo: 'hui-fx-halo',
+    glow: 'hui-fx-glow',
+    cta: 'hui-fx-cta',
+    accentFont: 'hui-fx-accent-font',
+    serif: 'hui-fx-serif',
+    backdrop: 'hui-fx-backdrop',
+    none: 'hui-fx-none',
+} as const;
+
+export type EffectClass = (typeof effectClasses)[keyof typeof effectClasses];