@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 5.0.0-alpha.0

package/src/components/CodeTabs/CodeTabs.contrast.test.tsx

@@ -0,0 +1,109 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '@/theme';
+import { ROLE_TOKEN_PATHS } from '@/theme/colors';
+import { SCHEMES } from '@/theme/palette.generated';
+
+import { CodeTabs } from './CodeTabs';
+import { CODE_CHROME } from './CodeTabs.styles';
+
+/**
+ * The tab bar sits on Shiki `github-dark`, which is dark in both app modes, so
+ * the chrome has to be too. It read `bg.inverse` (= `tooltip.bg`: near-black in
+ * light, light sand in dark) with flipping `fg.muted` labels — ~1.4:1 in light
+ * and ~1.1:1 in dark.
+ *
+ * jsdom cannot resolve a `_dark` conditional into a colour, so the palette is
+ * measured from the generated scheme table for the token names the component
+ * reads, and a render check pins that the component reads them.
+ */
+type Mode = 'light' | 'dark' | 'hcLight' | 'hcDark';
+const MODES: Mode[] = ['light', 'dark', 'hcLight', 'hcDark'];
+type Scheme = keyof typeof SCHEMES;
+
+const BY_PATH = Object.fromEntries(
+  Object.entries(ROLE_TOKEN_PATHS).map(([flat, path]) => [path, flat])
+) as Record<string, keyof (typeof SCHEMES)['ink']['light']>;
+
+const rgb = (hex: string) =>
+  [0, 2, 4].map((i) => parseInt(hex.replace('#', '').slice(i, i + 2), 16));
+
+const luminance = ([r, g, b]: number[]) => {
+  const [R, G, B] = [r, g, b].map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+};
+
+const contrast = (a: number[], b: number[]) => {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+};
+
+/** Token (optionally `token/NN` alpha) → rgb, composited over `under`. */
+const resolve = (
+  scheme: Scheme,
+  mode: Mode,
+  token: string,
+  under?: number[]
+) => {
+  const [path, alpha] = token.split('/');
+  const flat = BY_PATH[path];
+  if (!flat) throw new Error(`no scheme entry for ${path}`);
+  const value = rgb(SCHEMES[scheme][mode][flat]);
+  if (!alpha) return value;
+  const t = Number(alpha) / 100;
+  return value.map((v, i) => v * t + under![i] * (1 - t));
+};
+
+const WHITE = [255, 255, 255];
+
+describe('CodeTabs chrome palette', () => {
+  for (const scheme of Object.keys(SCHEMES) as Scheme[]) {
+    for (const mode of MODES) {
+      it(`${scheme} ${mode}: dark surface, labels ≥ 4.5:1`, () => {
+        const bg = resolve(scheme, mode, CODE_CHROME.bg);
+        const hover = resolve(scheme, mode, CODE_CHROME.bgHover);
+        // Dark in every mode: light text on it, like github-dark's own ground.
+        expect(contrast(bg, WHITE)).toBeGreaterThan(7);
+
+        const fg = resolve(scheme, mode, CODE_CHROME.fg);
+        expect(contrast(fg, bg)).toBeGreaterThanOrEqual(4.5);
+        expect(contrast(fg, hover)).toBeGreaterThanOrEqual(4.5);
+
+        const muted = resolve(scheme, mode, CODE_CHROME.fgMuted, bg);
+        expect(contrast(muted, bg)).toBeGreaterThanOrEqual(4.5);
+      });
+    }
+
+    it(`${scheme}: same surface family in light and dark`, () => {
+      // Not the same hex (BAZE dark is a warmer ink), but never flipped.
+      const light = luminance(resolve(scheme, 'light', CODE_CHROME.bg));
+      const dark = luminance(resolve(scheme, 'dark', CODE_CHROME.bg));
+      expect(Math.abs(light - dark)).toBeLessThan(0.05);
+    });
+  }
+});
+
+describe('CodeTabs reads the chrome tokens', () => {
+  it('tab bar and labels use CODE_CHROME', () => {
+    render(
+      <ChakraProvider value={system}>
+        <CodeTabs code={{ js: 'a', py: 'b' }} onCopy={() => {}} />
+      </ChakraProvider>
+    );
+    const selected = screen.getByRole('tab', { name: 'js' });
+    const root = selected.closest<HTMLElement>(
+      '[data-scope="tabs"][data-part="root"]'
+    )!;
+    expect(getComputedStyle(root).backgroundColor).toContain(
+      '--chakra-colors-action-bg'
+    );
+    expect(getComputedStyle(selected).color).toContain(
+      '--chakra-colors-action-fg'
+    );
+  });
+});

package/src/components/CodeTabs/CodeTabs.styles.ts

@@ -0,0 +1,26 @@
+/**
+ * The CodeTabs chrome (tab bar, copy button) and the code body under it.
+ *
+ * The code is highlighted with Shiki's `github-dark`, whose token colours are
+ * written for a dark ground in BOTH app modes, so the surface must stay dark in
+ * both too. `bg.inverse` does not: it is `tooltip.bg`, near-black in light but
+ * light sand in dark, and the `fg.muted` text on it flipped as well (~1.4:1 in
+ * light, ~1.1:1 in dark).
+ *
+ * `action.*` is the one role pair that is dark in every mode (BAZE ink:
+ * #252525 light / #38332E dark, `action.fg` 12.5–13.2:1 on it, high contrast
+ * included), so the chrome reads it. The unselected label is `action.fg` at
+ * 70% — ≥ 7.0:1 on `action.bg` and ≥ 5.6:1 on `action.bgHover`, both schemes,
+ * all four modes.
+ *
+ * Borrowed rather than owned: `action.*` is the Run button's role. A dedicated
+ * `code.*` role family (bg / fg / fgMuted / bgHover) would be the clean home.
+ */
+export const CODE_CHROME = {
+  bg: 'action.bg',
+  bgHover: 'action.bgHover',
+  bgActive: 'action.bgActive',
+  fg: 'action.fg',
+  fgMuted: 'action.fg/70',
+  divider: 'action.fg/15',
+} as const;

package/src/components/CodeTabs/CodeTabs.tsx

@@ -4,6 +4,7 @@ import { Box, Flex } from '@chakra-ui/react';
 import { Code } from '@/components/Code';
 import { Tab, TabList, Tabs } from '@/components/Tabs';
 
+import { CODE_CHROME } from './CodeTabs.styles';
 import { CodeTabsProps } from './CodeTabs.types';
 import { CopyButton } from './CopyButton';
 
@@ -19,13 +20,14 @@ export const CodeTabs = ({ code, onCopy, ...rest }: CodeTabsProps) => {
 
   return (
     <Tabs
-      bgColor="gray.1500"
+      // Fixed dark chrome in both modes — see `CODE_CHROME`.
+      bgColor={CODE_CHROME.bg}
       borderRadius="md"
       value={selectedValue}
       onValueChange={(details) => setSelectedValue(details.value)}
       {...rest}
     >
-      <TabList px={2} alignItems="center">
+      <TabList px={2} alignItems="center" borderColor={CODE_CHROME.divider}>
         <Flex w="100%" flex={1}>
           {languages.map((language) => (
             <Tab
@@ -39,9 +41,11 @@ export const CodeTabs = ({ code, onCopy, ...rest }: CodeTabsProps) => {
               textTransform="uppercase"
               fontWeight="bold"
               textStyle="subtext"
-              _selected={{ color: 'white' }}
+              color={CODE_CHROME.fgMuted}
+              _selected={{ color: CODE_CHROME.fg }}
               _hover={{
-                bgColor: 'whiteAlpha.500',
+                bgColor: CODE_CHROME.bgHover,
+                color: CODE_CHROME.fg,
               }}
             >
               {language}
@@ -60,6 +64,14 @@ export const CodeTabs = ({ code, onCopy, ...rest }: CodeTabsProps) => {
               hideHeader
               aria-hidden={!isSelected}
               containerProps={{
+                // The body sits on the same fixed-dark surface: Chakra's Shiki
+                // adapter strips the `<pre>` that carries github-dark's own
+                // background, so the block would otherwise paint `bg`
+                // (= `bg.canvas`, white in light mode) under light token colours.
+                bg: CODE_CHROME.bg,
+                // Before Shiki loads, the text is plain `color`.
+                color: CODE_CHROME.fg,
+                borderColor: CODE_CHROME.bg,
                 borderRadius: 'none',
                 borderBottomRadius: 'md',
                 gridArea: '1 / 1',

package/src/components/CodeTabs/CopyButton.tsx

@@ -5,6 +5,7 @@ import { useTranslate } from '@/hooks/useTranslate';
 import { FaRegCopy } from '../Icon';
 import { IconButton } from '../IconButton';
 import { Tooltip } from '../Tooltip';
+import { CODE_CHROME } from './CodeTabs.styles';
 
 export interface CopyButtonProps {
   onCopy: (code: string) => void;
@@ -47,14 +48,15 @@ export const CopyButton = ({ onCopy, code }: CopyButtonProps) => {
         aria-label="Copy"
         borderRadius="full"
         size="sm"
-        colorPalette="neutral"
         variant="ghost"
-        color="fg.muted"
+        color={CODE_CHROME.fgMuted}
         _hover={{
-          bgColor: 'whiteAlpha.400',
+          bgColor: CODE_CHROME.bgHover,
+          color: CODE_CHROME.fg,
         }}
         _active={{
-          bgColor: 'whiteAlpha.400',
+          bgColor: CODE_CHROME.bgActive,
+          color: CODE_CHROME.fg,
         }}
         onClick={handleCopyClick}
       >

package/src/components/Collapsible/Collapsible.presence.test.tsx

@@ -0,0 +1,83 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { system } from '../../theme';
+import { CollapsibleContent } from './CollapsibleContent';
+import { CollapsibleRoot } from './CollapsibleRoot';
+
+/**
+ * `presence` declares a clock and no `animation-name`, which is the one thing
+ * that lets a single preset sit on six unrelated parts. Collapsible is where
+ * that would break first and most visibly: it does not fade or scale, it
+ * interpolates the `--height` Ark measures, so a preset that also named an
+ * animation would silently turn its expansion into a fade.
+ *
+ * Asserting on the emitted rules rather than on computed style because jsdom
+ * does not run animations — what is being checked is which declarations reach
+ * the element, which is exactly where this can go wrong.
+ */
+const setup = () =>
+  render(
+    <ChakraProvider value={system}>
+      <CollapsibleRoot defaultOpen>
+        <CollapsibleContent>content</CollapsibleContent>
+      </CollapsibleRoot>
+    </ChakraProvider>
+  );
+
+const rulesFor = (el: Element) => {
+  const css = Array.from(document.querySelectorAll('style'))
+    .map((s) => s.textContent ?? '')
+    .join('\n');
+  return (
+    el.className
+      .split(' ')
+      .filter((c) => c.startsWith('css-'))
+      // `[^{]*` rather than a bare `{`: these declarations live behind the
+      // `_open` / `_closed` conditions, so the class never ends the selector.
+      .flatMap((c) => [
+        ...css.matchAll(new RegExp(`\\.${c}[^{]*\\{([^}]*)\\}`, 'g')),
+      ])
+      .map((m) => m[1])
+      .join('\n')
+  );
+};
+
+describe('Collapsible presence timing', () => {
+  it('runs the enter on the house clock, not the recipe 200ms', () => {
+    const { container } = setup();
+    const rules = rulesFor(container.querySelector('[data-part="content"]')!);
+
+    expect(rules).toContain(
+      'animation-duration:var(--chakra-durations-motion-base)'
+    );
+    expect(rules).toContain(
+      'animation-timing-function:var(--chakra-easings-emphasized)'
+    );
+  });
+
+  it('leaves in half that, on the same ease-out', () => {
+    const { container } = setup();
+    const rules = rulesFor(container.querySelector('[data-part="content"]')!);
+
+    expect(rules).toContain('animation-duration:var(--chakra-durations-fast)');
+    expect(rules).toContain(
+      'animation-timing-function:var(--chakra-easings-emphasized)'
+    );
+  });
+
+  it('never names an animation, so the height keyframes survive', () => {
+    // The failing version of this change reads identically at the call site:
+    // `animationStyle="presence"` either way, and the panel still opens — just
+    // by fading, with no height to interpolate, which is the bug.
+    const applied = system.css({ animationStyle: 'presence' });
+    const declarations = JSON.stringify(applied);
+
+    expect(declarations).not.toContain('expand-height');
+    expect(declarations.match(/"animationName"/g) ?? []).toHaveLength(
+      // Only the two under reduced motion, where losing the height is the point.
+      2
+    );
+  });
+});

package/src/components/Collapsible/CollapsibleContent.tsx

@@ -7,6 +7,18 @@ export const CollapsibleContent = forwardRef<
   HTMLDivElement,
   CollapsibleContentProps
 >((props, ref) => {
-  return <ChakraCollapsible.Content ref={ref} px={4} py={3} {...props} />;
+  // The one presence part that does not fade or scale: it interpolates the
+  // `--height` Ark measures. That is exactly why `presence` declares no
+  // `animation-name` — the recipe's `expand-height` / `collapse-height` survive
+  // and only the clock changes.
+  return (
+    <ChakraCollapsible.Content
+      ref={ref}
+      px={4}
+      py={3}
+      animationStyle="presence"
+      {...props}
+    />
+  );
 });
 CollapsibleContent.displayName = 'CollapsibleContent';

package/src/components/ColorMode/ColorModeToggle.tsx

@@ -1,7 +1,8 @@
 'use client';
 import React, { useEffect, useState } from 'react';
-import { LuMoon, LuSun } from 'react-icons/lu';
+import { Box } from '@chakra-ui/react';
 
+import { MoonIcon, SunIcon } from '@/components/Icon';
 import { IconButton } from '@/components/IconButton';
 import type { IconButtonProps } from '@/components/IconButton/IconButton.types';
 
@@ -35,9 +36,39 @@ export const ColorModeToggle: React.FC<ColorModeToggleProps> = ({
     setMounted(true);
   }, []);
 
+  const isDark = mounted && colorMode === 'dark';
+
   return (
     <IconButton aria-label={ariaLabel} onClick={toggleColorMode} {...rest}>
-      {mounted && colorMode === 'dark' ? <LuSun /> : <LuMoon />}
+      {/* Both icons share one grid cell and cross by rotating out and in, so the
+          toggle reads as one object turning rather than two icons swapping. The
+          page-wide colour flip stays instant on purpose — `ColorModeProvider`
+          sets `disableTransitionOnChange` so the whole UI doesn't wash through
+          an intermediate state — this animates the control only. */}
+      <Box display="grid" placeItems="center">
+        <Box
+          gridArea="1 / 1"
+          display="grid"
+          placeItems="center"
+          opacity={isDark ? 1 : 0}
+          transform={isDark ? undefined : 'rotate(-90deg) scale(0.5)'}
+          animationStyle="spring"
+          transitionProperty="opacity, transform"
+        >
+          <SunIcon />
+        </Box>
+        <Box
+          gridArea="1 / 1"
+          display="grid"
+          placeItems="center"
+          opacity={isDark ? 0 : 1}
+          transform={isDark ? 'rotate(90deg) scale(0.5)' : undefined}
+          animationStyle="spring"
+          transitionProperty="opacity, transform"
+        >
+          <MoonIcon />
+        </Box>
+      </Box>
     </IconButton>
   );
 };

package/src/components/Confetti/Confetti.stories.tsx

@@ -0,0 +1,88 @@
+import { Box, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+
+import { Button } from '../Button';
+import { Subtext, Text } from '../Typography';
+import { Confetti } from '.';
+
+/**
+ * A one-shot celebratory burst. One class and one keyframe for every piece —
+ * only the custom properties differ.
+ *
+ * Needs a positioned, clipped parent: it fills its container and measures the
+ * fall against it.
+ */
+const meta = {
+  title: 'Components/Motion/Confetti',
+  component: Confetti,
+} satisfies Meta<typeof Confetti>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const Stage = ({ children }: { children: React.ReactNode }) => (
+  <Box
+    position="relative"
+    overflow="hidden"
+    w="100%"
+    maxW="420px"
+    h="240px"
+    borderRadius="lg"
+    border="1px solid"
+    borderColor="border.subtle"
+    bg="bg.surface"
+    display="grid"
+    placeItems="center"
+  >
+    {children}
+  </Box>
+);
+
+export const Default: Story = {
+  render: () => {
+    const [run, setRun] = useState(0);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button size="sm" onClick={() => setRun((r) => r + 1)}>
+          재생
+        </Button>
+        <Stage>
+          {run > 0 && <Confetti key={run} seed={run} />}
+          <Text fontWeight="700" mb={0}>
+            축하합니다
+          </Text>
+        </Stage>
+      </Stack>
+    );
+  },
+};
+
+
+/** `seed` re-scatters. The generator is seeded so one burst holds still across re-renders. */
+export const Seeded: Story = {
+  render: () => {
+    const [seed, setSeed] = useState(1);
+
+    return (
+      <Stack gap={4} align="flex-start">
+        <Button
+          size="sm"
+          variant="secondary"
+          onClick={() => setSeed((s) => s + 1)}
+        >
+          다시 뿌리기 (seed {seed})
+        </Button>
+        <Stage>
+          <Confetti key={seed} seed={seed} pieceCount={30} />
+        </Stage>
+        <Subtext color="fg.muted" mb={0}>
+          <code>Math.random()</code>이었다면 부모가 리렌더할 때마다 조각이 다시
+          흩어집니다 — 그리고 축하를 띄운 부모는 대개 리렌더 중입니다.
+        </Subtext>
+      </Stack>
+    );
+  },
+};

package/src/components/Confetti/Confetti.styles.ts

@@ -0,0 +1,57 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+/**
+ * One falling piece.
+ *
+ * ## Why the duration is a token *times a factor*
+ *
+ * The first pass of this pinned every piece to `motion.celebrate.fall` exactly,
+ * on the reasoning that randomising a clock leaves a burst with no known
+ * length. That reasoning was right about sequencing and wrong about confetti:
+ * fifty pieces falling at *identical* speed do not read as fifty pieces. They
+ * read as one sheet, because equal speed is the one thing debris never has —
+ * real pieces differ in mass and in how much air they catch, and that
+ * difference is most of what makes a burst look like a burst.
+ *
+ * So the rate varies, but as a bounded multiple of the token rather than an
+ * open `2 + Math.random()`. The scale still sets the pace, the burst still has
+ * a computable ceiling (`fall × 1.3`, plus the delay spread), and the pieces
+ * still fall at different speeds. What the original had that mattered is kept;
+ * what it had that made the burst unschedulable is not.
+ *
+ * `linear`, and this is one of two places in the library where the curve is not
+ * a preference. The other is the spinner, where easing would put a seam in a
+ * loop; here it is gravity — a piece that decelerates on the way down reads as
+ * being lowered rather than dropped. None of the three house curves is right,
+ * and inventing a fourth for confetti alone would be a preset with one call
+ * site.
+ *
+ * `forwards`, so a piece stays gone. Without it every piece snaps back to the
+ * top of the container on the final frame.
+ */
+export const confettiPiece: SystemStyleObject = {
+  position: 'absolute',
+  top: '0',
+  // No radius, and not a token. `radii.xs` is 4px in this theme — a value
+  // chosen for buttons and cards, which is most of the width of a 10px piece.
+  // The radius scale exists for things a finger touches; a fragment is not one,
+  // and a corner is what makes it read as torn paper rather than a pill.
+  borderRadius: '0',
+  animationName: 'confetti-fall',
+  animationDuration:
+    'calc(var(--chakra-durations-motion-celebrate-fall) * var(--confetti-rate, 1))',
+  animationTimingFunction: 'linear',
+  // `both`, not `forwards`. Each piece waits out a delay of up to
+  // `motion.base`, and with `forwards` alone the element renders in its *own*
+  // CSS state during that wait — parked at `top: 0`, which is the top edge of
+  // the container and fully visible. Forty pieces then sit in a row along the
+  // rim and drop when their delay expires: hanging, not falling. The backwards
+  // half of `both` applies the 0% frame during the delay instead, which is
+  // above the edge and clipped away.
+  animationFillMode: 'both',
+  // Nothing to soften: a burst carries no information, so under reduced motion
+  // the pieces stay where they are and invisible. Done in CSS rather than by
+  // branching in JS so the decision sits on the same media query as every
+  // preset, instead of on a hook that has to guess before hydration.
+  _motionReduce: { animationName: 'none', opacity: 0 },
+};

package/src/components/Confetti/Confetti.tsx

@@ -0,0 +1,147 @@
+import { ForwardedRef, forwardRef, useMemo } from 'react';
+import { Box } from '@chakra-ui/react';
+
+import { MOTION_DURATION_MS } from '../../theme/motion';
+import { confettiPiece } from './Confetti.styles';
+import { ConfettiProps } from './Confetti.types';
+import { DEFAULT_CONFETTI_COLORS } from './confettiColors';
+
+/**
+ * A seeded generator, so one burst is stable across re-renders.
+ *
+ * `Math.random()` per render would re-scatter every piece whenever the parent
+ * updated — and a parent that is showing a celebration is usually updating,
+ * because something just finished.
+ */
+const scatter = (seed: number) => {
+  let s = seed || 1;
+  return () => {
+    s = (s * 1664525 + 1013904223) % 4294967296;
+    return s / 4294967296;
+  };
+};
+
+/**
+ * A one-shot celebratory burst — the thing that plays when a reward lands or a
+ * purchase completes.
+ *
+ * Pure CSS, one class, one keyframe. Fifty pieces share `confetti-fall` and
+ * differ only in the three custom properties it reads, so the burst costs one
+ * style rule rather than fifty.
+ *
+ * **The token sets the pace; each piece scales it.** Where a piece starts, how
+ * far it drifts, which way it tumbles, what colour it is and *how fast it
+ * falls* are all per-piece — equal fall speed is the one thing debris never
+ * has, and fifty pieces at an identical rate read as one sheet. But the rate is
+ * a bounded multiple of `motion.celebrate.fall` rather than an open interval,
+ * so the burst still has a computable end. FactChat's version uses
+ * `2 + Math.random()` seconds with no ceiling, which is the part that makes a
+ * burst impossible to schedule anything after.
+ *
+ * The delay is random too, not indexed. An earlier pass here reused the
+ * `stagger` step, which was a mistake worth naming: a list has an order the eye
+ * follows, and a delay that grows with the index is a *rhythm*. Confetti has no
+ * order, so the same delay reads as a wave sweeping across the container —
+ * fifty pieces queueing rather than bursting.
+ *
+ * Under reduced motion the pieces mount and stay invisible rather than being
+ * branched away in JS — a burst carries no information, so removing it removes
+ * nothing, and doing it in CSS keeps the decision on the same media query as
+ * every other preset instead of on a hook that has to guess before hydration.
+ *
+ * **The default colours are decorative only** (`confettiColors.ts`): coral,
+ * beige and the system hues that mean nothing — red, yellow, green and blue are
+ * left out because they are the danger, warning, success and info colours, and
+ * raining error red over "payment complete" says something the screen does not.
+ * They are light-mode hex and do not flip for dark mode. `colors` is a prop for
+ * an app that needs its own.
+ *
+ * **Takes no children — it is an overlay, not a wrapper.** It renders absolutely
+ * against the nearest positioned ancestor, which is therefore the stage: give
+ * that element `position: relative`, or the burst resolves against the page and
+ * rains over everything.
+ *
+ * ```tsx
+ * {justPurchased && <Confetti />}
+ * ```
+ */
+export const Confetti = forwardRef(
+  (
+    {
+      pieceCount = 50,
+      colors = DEFAULT_CONFETTI_COLORS,
+      seed = 1,
+      ...rest
+    }: ConfettiProps,
+    ref?: ForwardedRef<HTMLDivElement>
+  ) => {
+    const pieces = useMemo(() => {
+      const next = scatter(seed);
+      return Array.from({ length: pieceCount }, (_, i) => ({
+        id: i,
+        left: `${next() * 100}%`,
+        color: colors[Math.floor(next() * colors.length)],
+        // ± half a container width of lateral travel.
+        drift: `${Math.round(next() * 100 - 50)}px`,
+        // Two full turns, and only the direction is random. A magnitude that
+        // varies down to near zero gives some pieces no tumble at all, which is
+        // the difference between debris and a falling rectangle.
+        spin: next() < 0.5 ? '-720deg' : '720deg',
+        // Square, near enough. The first version varied width 6–10 and height
+        // 8–14 independently, which produced pieces 2.3× taller than wide —
+        // and with `radii.xs` on top of that (4px, because this theme
+        // overrides Chakra's 2px for buttons and cards) a 6px-wide piece is
+        // two-thirds round. A rounded oblong tumbling end over end is not a
+        // fragment of paper; the team's word for it was 애벌레, caterpillar.
+        width: `${8 + Math.round(next() * 4)}px`,
+        height: `${8 + Math.round(next() * 5)}px`,
+        // 0.85–1.3× the token. Anchored to the scale, and with a ceiling: the
+        // whole burst is over by `fall × 1.3 + base`, which is knowable without
+        // running it.
+        rate: (0.85 + next() * 0.45).toFixed(2),
+        // Random within `motion.base`, not stepped by index — see the note
+        // above about why a stagger is wrong here. 300ms is wide enough that no
+        // two pieces launch together and narrow enough that the burst still
+        // reads as one event.
+        delay: `${Math.round(next() * MOTION_DURATION_MS.base)}ms`,
+      }));
+    }, [pieceCount, colors, seed]);
+
+    return (
+      <Box
+        ref={ref}
+        position="absolute"
+        inset="0"
+        overflow="hidden"
+        pointerEvents="none"
+        aria-hidden
+        // Establishes the containing block the keyframe's `cqh` resolves
+        // against. Without it `110cqh` falls back to the small viewport and
+        // every piece leaves the screen in the first few frames.
+        containerType="size"
+        {...rest}
+      >
+        {pieces.map((p) => (
+          <Box
+            key={p.id}
+            css={confettiPiece}
+            bg={p.color}
+            left={p.left}
+            w={p.width}
+            h={p.height}
+            style={
+              {
+                '--confetti-drift': p.drift,
+                '--confetti-spin': p.spin,
+                '--confetti-rate': p.rate,
+                animationDelay: p.delay,
+              } as React.CSSProperties
+            }
+          />
+        ))}
+      </Box>
+    );
+  }
+);
+
+Confetti.displayName = 'Confetti';