@evolve.ui/theme-system 1.1.0 → 1.2.0

package/src/tailwind/reducedMotion.ts

@@ -0,0 +1,164 @@
+/**
+ * Reduced-motion policy for the animation registry (DS-95 / audit findings SA-02 + SA-03).
+ *
+ * Every animation Tailwind resolves for this library — the local `theme.extend.animation`
+ * entries *and* Tailwind's own defaults — gets exactly one entry here. `reducedMotion.spec.ts`
+ * fails if the two key sets ever diverge, so a new animation cannot ship untriaged.
+ *
+ * ## Why duration-collapse rather than `animation: none`
+ *
+ * `animation: none` fires no `animationend`. `Modal/ComposableModal` and
+ * `Modal/hooks/useCloseModal` both depend on that event to finish closing — `useCloseModal`
+ * clears a 450ms watchdog there that otherwise logs an error and rejects an awaited promise. A
+ * naive `none` gate would strand the modal open *for reduced-motion users only*, which is worse
+ * than the gap it fixes. Collapsing the duration keeps the event, and keeps `forwards`/`both`
+ * fill end-states intact (`slideUp`, `slideDown`, `progress-completion`).
+ *
+ * ## Why the doubled class selector
+ *
+ * Tailwind emits `base` before `utilities`. A consumer building with `important: true` gets
+ * `!important` utilities too, and two equal-specificity `!important` rules resolve by source
+ * order — the utility would win. `.animate-x.animate-x` (0-2-0) beats it on specificity instead,
+ * and is inert for everyone else.
+ *
+ * Two known limitations, both external-consumer only:
+ * - `prefix` renames the utility classes (`.tw-animate-*`), which these selectors will not match.
+ * - `important: '#selector'` (the selector strategy, not `important: true`) emits
+ *   `#selector .animate-x` at specificity 0-1-0 *plus* an id — which outranks 0-2-0 regardless
+ *   of `!important`. The doubled class only defends against `important: true`.
+ *
+ * Components in this repo hardcode unprefixed class strings and no in-repo config sets either
+ * option, so neither affects this monorepo.
+ */
+export type ReducedMotionTier =
+    /** Collapse to ~1ms under reduce. The animation still runs, so `animationend` still fires. */
+    | 'instant'
+    /** Left alone — infinite indeterminate status indicators, where stopping removes feedback. */
+    | 'retain'
+    /** Not an animation (`animate-none` is the absence utility). */
+    | 'n/a';
+
+/**
+ * `selectors` is only meaningful on `instant` entries — nothing is emitted for `retain`/`n/a`,
+ * so allowing it there would let a future entry declare a selector that silently does nothing.
+ * The union makes that a type error rather than a quiet no-op.
+ */
+export type ReducedMotionPolicyEntry =
+    | {
+          /** Why this tier was chosen. Asserted non-empty, so every entry carries a justification. */
+          reason: string;
+          /**
+           * Extra selectors for animations applied through a component class rather than an
+           * `animate-*` utility. Emitted verbatim, so they are written at full specificity.
+           */
+          selectors?: readonly string[];
+          tier: 'instant';
+      }
+    | { reason: string; selectors?: never; tier: 'n/a' | 'retain' };
+
+export const REDUCED_MOTION_POLICY: Record<string, ReducedMotionPolicyEntry> = {
+    // --- Local registry (theme.extend.animation) ---
+    fadeIn: {
+        reason: 'Opacity only, but collapsed alongside fadeInScaled so a modal opens the same way in both variants (ComposableModal picks between them on hasContentPager).',
+        tier: 'instant',
+    },
+    fadeInOpacity: {
+        reason: 'Opacity and visibility only; collapsing a fade is not a motion regression.',
+        tier: 'instant',
+    },
+    fadeInScaled: { reason: 'Scales 0.7 to 1.', tier: 'instant' },
+    fadeOut: {
+        reason: 'Scales 1 to 0.7. Modal close depends on its animationend, so it is collapsed rather than removed.',
+        tier: 'instant',
+    },
+    loading: {
+        reason: 'Infinite indeterminate loading indicator (LoadingDot). Collapsing it removes the only signal that work is in progress.',
+        tier: 'retain',
+    },
+    'progress-completion': {
+        reason: 'Scales. Zeroing the delay matters here: the composite is "shrink 0.15s both, grow 0.15s ease-in-out 0.15s both", so a duration-only collapse would hold the ring at scale(0.5) for 150ms and then snap.',
+        tier: 'instant',
+    },
+    'progress-icon-fade-in': {
+        reason: 'Opacity only, but its 0.15s delay sequences it after progress-completion. Retaining it would leave a completed ProgressCircle ring with an empty centre for 150ms.',
+        tier: 'instant',
+    },
+    'progress-wave': {
+        reason: 'Infinite indeterminate progress indicator (ProgressCircle). Same essential-feedback rationale as loading.',
+        tier: 'retain',
+    },
+    saveButtonPulse: { reason: 'Scales.', tier: 'instant' },
+    saveButtonWiggle: { reason: 'Rotates and scales.', tier: 'instant' },
+    saveHeartColorFlash: {
+        reason: 'Animates fill only, but it was already gated before DS-95 and must stay gated. Shipped via .hui-fb-color-flash, not the animate-* utility (which has no call sites), so it needs the explicit selector below.',
+        selectors: ['.hui-fb-color-flash .hui-fb-icon-frame svg path'],
+        tier: 'instant',
+    },
+    saveHeartPop: { reason: 'Scales.', tier: 'instant' },
+    saveHeartTwirlBloom: { reason: 'Rotates 180 degrees at 1.15x scale.', tier: 'instant' },
+    saveLabelShimmer: {
+        reason: 'Animates background-position. The .hui-fb-shimmer paint block in plugin.ts separately drops the gradient under reduce so the label stays legible.',
+        tier: 'instant',
+    },
+    slideDown: {
+        reason: 'Translates on Y. Collapsed rather than removed so CookieConsent still receives animationend.',
+        tier: 'instant',
+    },
+    slideUp: { reason: 'Translates on Y. Same animationend rationale as slideDown.', tier: 'instant' },
+
+    // --- Tailwind defaults, which survive theme.extend and are reachable by consumers ---
+    bounce: { reason: 'Translates on Y.', tier: 'instant' },
+    none: { reason: 'Not an animation — animate-none is the absence utility.', tier: 'n/a' },
+    ping: { reason: 'Scales and fades. No in-repo call site, but consumers can use it.', tier: 'instant' },
+    pulse: {
+        reason: 'Infinite, but opacity only — the conventional skeleton-loading indicator. Retained as essential feedback with no motion component.',
+        tier: 'retain',
+    },
+    spin: {
+        reason: 'Infinite indeterminate spinner (LoadingSpinner, ProgressCircle). A Tailwind default rather than a local entry, which is exactly why the policy is keyed on the resolved registry.',
+        tier: 'retain',
+    },
+};
+
+const REDUCE_QUERY = '@media (prefers-reduced-motion: reduce)';
+
+const COLLAPSED_DECLARATIONS = {
+    'animation-delay': '0ms !important',
+    'animation-duration': '1ms !important',
+    'animation-iteration-count': '1 !important',
+};
+
+/**
+ * Builds the `@media (prefers-reduced-motion: reduce)` block for `addBase`.
+ *
+ * Emitted from `addBase` rather than `addComponents` deliberately: `addComponents` is subject to
+ * caching discrepancies in this monorepo's Storybook build that stop newly added rules landing.
+ */
+export const buildReducedMotionBase = () => {
+    const rules: Record<string, typeof COLLAPSED_DECLARATIONS> = {};
+
+    const addRule = (selector: string) => {
+        if (rules[selector]) {
+            // Two policy entries claiming one selector would silently overwrite each other.
+            // Every rule emits identical declarations today, so this can only fire on a
+            // genuine authoring mistake — fail loudly rather than ship half a gate.
+            throw new Error(`Duplicate reduced-motion selector: ${selector}`);
+        }
+
+        rules[selector] = { ...COLLAPSED_DECLARATIONS };
+    };
+
+    Object.entries(REDUCED_MOTION_POLICY).forEach(([key, entry]) => {
+        if (entry.tier !== 'instant') {
+            return;
+        }
+
+        // Doubled class (0-2-0) so an `important: true` consumer's utility cannot win on
+        // source order — Tailwind emits `base` before `utilities`.
+        addRule(`.animate-${key}.animate-${key}`);
+
+        entry.selectors?.forEach(addRule);
+    });
+
+    return { [REDUCE_QUERY]: rules };
+};

package/src/tailwind/text.ts

@@ -117,9 +117,11 @@ export const textComponents = {
         letterSpacing: wrapVar(letterSpacingH3),
         lineHeight: '30px',
         [`@media (width < ${screens.smMax.max})`]: {
-            fontSize: '16px',
+            // 18px/27px, not 16px/24px: at 16px this rule rendered identically to `.hui-text-h4`
+            // below the breakpoint, collapsing two adjacent heading levels (DS-97 / SA-04).
+            fontSize: '18px',
             letterSpacing: wrapVar(letterSpacingH3Mobile),
-            lineHeight: '24px',
+            lineHeight: '27px',
         },
     },
     '.hui-text-h4': {