@once-ui-system/core 1.8.4 → 2.0.0-alpha.0

package/ai/gotchas.json

@@ -1,86 +1,143 @@
 {
   "Background.gradient.width": {
     "rule": "Quarter-percent units: 400 = 100% of container. Soft glows use width 100–200, not 500.",
-    "components": ["Background"]
+    "components": [
+      "Background"
+    ]
   },
   "Background.gradient.x": {
     "rule": "x/y are percent positions of the container (50/50 = center).",
-    "components": ["Background"]
+    "components": [
+      "Background"
+    ]
   },
   "Background.absolute": {
     "rule": "Every absolute decorative layer needs top=\"0\" left=\"0\" or it offsets by parent padding.",
-    "components": ["Background", "MatrixFx", "BlobFx"]
+    "components": [
+      "Background",
+      "MatrixFx",
+      "BlobFx"
+    ]
   },
   "Card.interactive": {
     "rule": "Card is for interactive surfaces only (href or onClick). Static panels use Column + background=\"surface\" border=\"neutral-alpha-weak\" radius=\"l\".",
-    "components": ["Card"]
+    "components": [
+      "Card"
+    ]
   },
   "Fade.edge": {
     "rule": "Fade is an edge overlay strip on scroll containers, not a content wrapper.",
-    "components": ["Fade"]
+    "components": [
+      "Fade"
+    ]
   },
   "RevealFx.delay": {
-    "rule": "delay is in seconds — stagger with delay={index * 0.1}, never index * 80.",
-    "components": ["RevealFx"]
+    "rule": "delay is in milliseconds — stagger with delay={index * 100}, never index * 0.1 (that was 1.8.x; 2.0 reads 0.1 as a tenth of a millisecond, i.e. no stagger).",
+    "components": [
+      "RevealFx",
+      "ShineFx"
+    ]
   },
   "RevealFx.translateY": {
     "rule": "translateY as a number is in rem. Use translateY={1} or token \"16\" (1rem); 16 means 16rem.",
-    "components": ["RevealFx"]
+    "components": [
+      "RevealFx"
+    ]
   },
   "LogoCloud.columns": {
     "rule": "LogoCloud extends Grid — always set columns and responsive overrides or logos stack in one column.",
-    "components": ["LogoCloud"]
+    "components": [
+      "LogoCloud"
+    ]
   },
   "StatusIndicator.color": {
     "rule": "StatusIndicator uses color=\"green\" | \"red\" | \"orange\" | \"gray\" etc. — not variant or semantic scheme names.",
-    "components": ["StatusIndicator"]
+    "components": [
+      "StatusIndicator"
+    ]
   },
   "Icon.names": {
-    "rule": "Icon names must come from IconName in spec.json — never invent names like more, bell, arrowRight.",
-    "components": ["Icon", "Button", "IconButton"]
+    "rule": "Icon names must come from iconNames in spec.json, which is a real union in 2.0 (an unregistered name is a type error, not a blank space). Do not guess a plausible name, and do not cast one with `as IconName` to silence the check. Brand marks are not in the set — an app registers those itself by augmenting IconLibraryOverrides.",
+    "components": [
+      "Icon",
+      "Button",
+      "IconButton"
+    ]
   },
   "Badge.duplicate": {
     "rule": "Do not pass the same text as both title prop and children — it renders twice.",
-    "components": ["Badge"]
+    "components": [
+      "Badge"
+    ]
   },
   "Tag.duplicate": {
     "rule": "Do not pass the same text as both label prop and children — it renders twice.",
-    "components": ["Tag"]
+    "components": [
+      "Tag"
+    ]
   },
   "color.tokens": {
     "rule": "Colors are semantic tokens ({scheme}-{weight}), never hex/rgb. background also accepts surface | overlay | page | transparent.",
-    "components": ["Column", "Row", "Text", "Button"]
+    "components": [
+      "Column",
+      "Row",
+      "Text",
+      "Button"
+    ]
   },
   "color.background-weak": {
     "rule": "*-background-weak is nearly the page color — invisible as accent. Use alpha tokens (brand-alpha-medium) for glows.",
-    "components": ["Background"]
+    "components": [
+      "Background"
+    ]
   },
   "layout.shorthands": {
     "rule": "Use fill not fillWidth fillHeight; center not horizontal=\"center\" vertical=\"center\"; Row/Column not Flex direction=.",
-    "components": ["Row", "Column", "Flex", "Grid"]
+    "components": [
+      "Row",
+      "Column",
+      "Flex",
+      "Grid"
+    ]
   },
   "layout.defaults": {
     "rule": "Never write props equal to defaults: position=\"relative\", direction on Row/Column, variant=\"primary\" on Button.",
-    "components": ["Row", "Column", "Button"]
+    "components": [
+      "Row",
+      "Column",
+      "Button"
+    ]
   },
   "section.gaps": {
     "rule": "Gap between page sections: 80–160 (typical 104). Inside sections: 24–40.",
-    "components": ["Column"]
+    "components": [
+      "Column"
+    ]
   },
   "heading.scale": {
     "rule": "Hero = display-strong-l/xl; section titles = display-strong-xs/s — never heading-* for section titles.",
-    "components": ["Heading"]
+    "components": [
+      "Heading"
+    ]
   },
   "animation.budget": {
     "rule": "Entry animation budget: hero + at most 1–2 key moments. Animate coherent blocks all-or-none within a sibling set.",
-    "components": ["RevealFx", "CountFx"]
+    "components": [
+      "RevealFx",
+      "CountFx"
+    ]
   },
   "CountFx.trigger": {
     "rule": "CountFx has no trigger prop — drive value from useInViewport latch instead.",
-    "components": ["CountFx"]
+    "components": [
+      "CountFx"
+    ]
   },
   "overflow.hero": {
     "rule": "overflow=\"hidden\" on full-bleed sections clips glows into hard bands — only use when parent has radius.",
-    "components": ["Column", "Background"]
+    "components": [
+      "Column",
+      "Background"
+    ]
   }
 }

package/ai/layouts.md

@@ -0,0 +1,154 @@
+# Once UI — application layouts
+
+Recipes for the shells a product sits inside, as opposed to the decoration in
+`recipes.md`. Each is the shape a working product converged on, not a sketch.
+
+Use them verbatim, then adjust. The values that look arbitrary usually are not —
+the notes say which ones matter and why.
+
+All three compile: they are also `ai/examples/app-shell.tsx`, which `pnpm
+typecheck` covers, so a renamed prop breaks the recipe rather than leaving it
+quietly wrong.
+
+## 1. App shell with a sidebar
+
+The one agents get wrong most often. A dashboard built without this scrolls the
+whole document, so the header and sidebar slide away and the nav has to be
+scrolled back to.
+
+```tsx
+<Column fill horizontal="center" flex={1}>
+  <Header />                                       {/* 56px tall */}
+  <Row fill paddingX="8">
+    <Sidebar s={{ hide: true }} maxWidth={18} fitHeight position="sticky" top="56" />
+    <Row fill horizontal="center" topRadius="l" overflow="hidden">
+      <Row
+        height="calc(100dvh - var(--static-space-56))"
+        overflowY="auto"
+        topRadius="l"
+        horizontal="center"
+        fillWidth
+        background="surface">
+        <Column maxWidth="xl" gap="m" paddingY="32" fitHeight>
+          {children}
+        </Column>
+      </Row>
+    </Row>
+  </Row>
+</Column>
+```
+
+What each part is doing:
+
+- **The pane scrolls, not the page.** `height: calc(100dvh - <header>)` plus
+  `overflowY="auto"` is what keeps the header and sidebar in place. `dvh`, not
+  `vh` — on mobile `vh` ignores the browser chrome and the pane runs off-screen.
+- **`position="sticky" top="56"`** on the sidebar, matching the header height.
+  `fitHeight` so it does not stretch and fight the sticky.
+- **`topRadius="l"` + `background="surface"`** is what makes the content read as
+  a panel sitting on the page rather than the page itself. The radius is on the
+  top only, since the bottom is off-screen.
+- **`s={{ hide: true }}`** rather than a media query. The mobile nav is a
+  separate surface, not this one reflowed.
+- **`maxWidth="xl"`** inside the pane. A dashboard is wider than a document;
+  `"m"` is for reading.
+
+## 2. Data-driven navigation
+
+```tsx
+import { NavGroup, NavItem, selectNavHref } from "@once-ui-system/core";
+
+const current = selectNavHref(pathname, nav.flatMap((i) =>
+  i.items ? i.items.map((s) => s.href) : [i.href],
+));
+
+<Column fill gap="4" paddingX="8">
+  {nav.map((item) =>
+    item.items ? (
+      <NavGroup
+        key={item.key}
+        label={item.label}
+        icon={item.icon}
+        defaultOpen={item.items.some((s) => s.href === current)}>
+        {item.items.map((sub) => (
+          <NavItem
+            key={sub.href}
+            href={sub.href}
+            label={sub.label}
+            badge={sub.badge}
+            selected={sub.href === current}
+          />
+        ))}
+      </NavGroup>
+    ) : (
+      <NavItem
+        key={item.href}
+        href={item.href}
+        icon={item.icon}
+        label={item.label}
+        selected={item.href === current}
+      />
+    ),
+  )}
+</Column>
+```
+
+- **`selectNavHref` over `===` or `startsWith`.** An equality check leaves a
+  nested route (`/settings/billing/invoices/42`) with nothing highlighted; a
+  prefix check lights the parent up alongside its child. It returns the longest
+  href that matches, which is the right one.
+- **Compute `current` once** for the whole tree, not per item — a child needs to
+  know about its siblings to know it is the deepest match.
+- **`defaultOpen` from the match**, so the group holding the current page is open
+  on arrival.
+- Child items take **no icon**. The rail inside `NavGroup` carries the hierarchy;
+  a second column of icons competes with it.
+
+## 3. Editor shell
+
+Two panes and a timeline — the shape of a video editor, a page builder, a
+diff view.
+
+```tsx
+<Column fill>
+  <SplitView
+    fill
+    leftPanel={<Column fill overflowY="auto">{/* layers, blocks, files */}</Column>}
+    rightPanel={<Column fill overflowY="auto">{/* canvas, preview */}</Column>}
+    defaultSplit={0.28}
+    minSplit={0.2}
+    maxSplit={0.6}
+    collapseBelow="s"
+    labels={{ left: "Layers", right: "Canvas" }}
+  />
+  <Scrubber
+    duration={duration}
+    value={time}
+    onChange={setTime}
+    tracks={tracks}
+    onGestureStart={pause}
+  />
+</Column>
+```
+
+- **`overflowY="auto"` on each panel, not on the SplitView.** The divider needs
+  the container to stay put while the panes scroll independently.
+- **`collapseBelow` + `labels`.** Below the breakpoint the split becomes tabs, and
+  `labels` is what they say. Without it the tabs are unlabelled.
+- **`onGestureStart` pauses playback.** Scrubbing while playing fights the
+  playhead — the drag sets a time, playback immediately moves it.
+- **The timeline is a sibling of the split, not inside it.** It spans both panes,
+  and putting it in one makes the divider drag it.
+
+## Anti-patterns
+
+- A dashboard with no scrolling pane — the whole document scrolls and the nav
+  leaves with it.
+- `100vh` in an app shell. Use `100dvh`; `vh` is wrong on mobile the moment the
+  browser chrome shows or hides.
+- A sticky sidebar without `fitHeight` — it stretches to the row and the sticky
+  never engages.
+- `pathname === href` or `startsWith` for nav selection. Use `selectNavHref`.
+- Icons on both a NavGroup and its children — two columns of icons, no hierarchy.
+- `overflow` on the SplitView instead of on its panels — the divider stops
+  tracking the pointer.

package/ai/manifest.json

@@ -1,12 +1,13 @@
 {
- "version": "1.8.4",
- "generated": "2026-08-28",
+ "version": "2.0.0-alpha.0",
+ "generated": "2026-09-16",
  "files": {
   "spec": "spec.json",
   "catalog": "catalog.json",
   "rules": "rules.compact.md",
   "rulesFull": "rules.md",
   "recipes": "recipes.md",
+  "layouts": "layouts.md",
   "gotchas": "gotchas.json",
   "tasks": "tasks/index.json",
   "examples": "examples/",

package/ai/recipes.md

@@ -1,7 +1,8 @@
-# Once UI — decoration recipes
+# Once UI — decoration and restraint recipes
 
-Curated decorative patterns that keep pages premium without going over the top.
-Use them verbatim, then adjust values. All units follow rules.md #21–24.
+Curated patterns that keep pages premium without going over the top: decorative
+layers that carry a section, and controls that earn their room back. Use them
+verbatim, then adjust values. All units follow rules.md #21–24.
 
 ## Budget (hard limits)
 
@@ -129,7 +130,7 @@ useEffect(() => {
 
 <Grid ref={ref} columns="3" gap="16" s={{ columns: 1 }}>
   {items.map((item, index) => (
-    <RevealFx key={item.id} trigger={seen} translateY="8" delay={index * 0.1}>
+    <RevealFx key={item.id} revealed={seen} translateY="8" delay={index * 100}>
       <Card ... />
     </RevealFx>
   ))}
@@ -138,8 +139,52 @@ useEffect(() => {
 
 For stats, drive `CountFx` value from the same latch: `<CountFx value={seen ? 2400 : 0} separator="," />`.
 
+## 8. Reveal on hover (controls that earn their room back)
+
+A control that must be reachable from every page but is used once a session does
+not need permanent width. Show its current state; reveal the options on hover or
+focus.
+
+`ThemeSwitcher` ships this as a prop:
+
+```tsx
+<ThemeSwitcher collapsed />
+```
+
+For any other toggle group, the pattern is the same three rules — and all three
+are load-bearing, because hover-to-reveal is one of the easiest ways to ship an
+inaccessible control:
+
+- **Open on `:focus-within` as well as `:hover`,** and keep the hidden options
+  focusable. Collapse them with `max-width: 0` and `overflow: hidden`, never
+  `display: none` or `visibility: hidden` — those remove the tab stops, and then
+  the only way to reach the options is with a mouse.
+- **Stay open under `@media (hover: none)`.** On a touch device the first tap
+  lands on the visible control, which means the tap that was meant to open the
+  group has already committed to an option.
+- **Animate width only, and drop it under `prefers-reduced-motion`.** The
+  control must do exactly the same thing with the transition off.
+
+```scss
+.group { overflow: hidden; }
+.group .option { overflow: hidden; max-width: var(--static-space-40); transition: max-width var(--transition-duration-micro-medium) ease; }
+.group .option.inactive { max-width: 0; opacity: 0; }
+.group:hover .option.inactive,
+.group:focus-within .option.inactive { max-width: var(--static-space-40); opacity: 1; }
+
+@media (hover: none) { .group .option.inactive { max-width: var(--static-space-40); opacity: 1; } }
+@media (prefers-reduced-motion: reduce) { .group .option { transition: none; } }
+```
+
+Use it for theme, density, or view-mode switchers in a header or a footer. Do
+not use it for anything a visitor needs to *see* the state of at a glance across
+options, for primary navigation, or for a destructive action — a control that
+hides until pointed at is a control nobody finds.
+
 ## Anti-patterns
 
+- **Hover-only reveals.** A group that opens on `:hover` but not `:focus-within`, or that collapses with `display: none`, is unreachable by keyboard and unusable by touch. See #8.
+
 - Glow with `colorStart: "brand-background-weak"` — invisible against the page; use alpha tokens.
 - `width: 500` gradients — that's 125% of the container blown past its edges; stay ≤ 200 for glows.
 - Background layers without `top="0" left="0"` inside padded parents — misaligned.

package/ai/rules.compact.md

@@ -1,6 +1,6 @@
 # Once UI — compact codegen rules
 
-Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For production-quality composition, read matching Pro blocks from `examples/blocks/manifest.json`. Fetch component slices on demand.
+Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For an app shell, a sidebar nav or an editor, read `ai/layouts.md` first — those are the shapes that are hard to get right from props alone. For production-quality composition, read matching Pro blocks from `examples/blocks/manifest.json`. Fetch component slices on demand.
 
 ## Layout
 
@@ -47,9 +47,9 @@ Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents
 
 ## Motion
 
-- `RevealFx delay` in **seconds**: `delay={index * 0.1}`
+- `RevealFx delay` (and `ShineFx speed`) in **milliseconds**: `delay={index * 100}` — `* 0.1` was 1.8.x
 - `RevealFx translateY`: number = rem; prefer `"8"`–`"16"` tokens
-- Viewport-trigger with `useInViewport` + latch; `CountFx` driven by `value`, no trigger prop
+- Viewport-reveal with `useInViewport` + latch into `RevealFx revealed`; `CountFx` driven by `value`, no trigger prop
 - Animate all siblings in a set or none — never one lone animated card
 
 ## Components
@@ -64,6 +64,21 @@ Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents
 | Icons | `IconName` from spec only |
 | Logos grid | `LogoCloud` with `columns` set |
 
+## Imports
+
+Most things come from the package root. Three modules do not, because their
+dependencies are optional peers:
+
+| Import | From |
+|--------|------|
+| charts, gauges, chart chrome | `@once-ui-system/core/data` (needs `recharts`) |
+| `CodeBlock` | `@once-ui-system/core/code` (needs `prismjs`) |
+| `MediaUpload` | `@once-ui-system/core/media` (needs `compressorjs`) |
+
+Naming one of these from the root does not resolve. `IconName` is a real union,
+so an unregistered icon name is a type error, not a blank space — take names
+from `spec.json`.
+
 ## Defaults — omit these
 
 `position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default.

package/ai/rules.md

@@ -47,7 +47,7 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 
 ## Spacing and sizing
 
-4. Use spacing tokens, never raw CSS: `gap`, `padding`, `margin`, `paddingX/Y`, `marginX/Y` accept tokens (`"2" "4" "8" "12" "16" "20" "24" "32" "40" "48" "64"` or `"xs" "s" "m" "l" "xl"`).
+4. Use spacing tokens, never raw CSS: `gap`, `padding`, `margin`, `paddingX/Y`, `marginX/Y` accept the full `SpacingToken` scale (`"0" "1" "2" "4" "8" "12" "16" "20" "24" "32" "40" "48" "56" "64" "80" "104" "128" "160"`, or `"xs" "s" "m" "l" "xl"`). The top of the scale is what rule 17 calls for between sections — it is not an extension, it is part of the same list.
 
 ```tsx
 // Good
@@ -109,9 +109,9 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
     - `CursorCard`, `HoverCard`, `ContextMenu`, `EmojiPicker`, `CompareImage`, `OgCard`, `Timeline`, `MasonryGrid`, `InfiniteScroll`, `SegmentedControl`, `Kbar` (command palette)
     - Forms: `Input`, `PasswordInput`, `OTPInput`, `NumberInput`, `TagInput`, `Select`, `DatePicker`, `DateRangePicker`, `ColorInput`, `Slider`, `Switch`, `Checkbox`, `Chip`
 
-14. Buttons: `variant` = `primary | secondary | tertiary | danger`; pair with `prefixIcon`/`suffixIcon` (icon names, not elements). `IconButton` for icon-only actions with `tooltip`.
+14. Buttons: `variant` = `primary | secondary | tertiary | quaternary | subtle | danger | success | warning | ghost | link` (the slice is authoritative; `primary` is the default); pair with `prefixIcon`/`suffixIcon` (icon names, not elements). `IconButton` for icon-only actions with `tooltip`.
 
-14b. Icon names must come from the `IconName` list in spec.json — never invent names (`more`, `bell`, and `arrowRight` don't exist; `close`, `chevronRight`, and `smiley` do). If no icon fits, omit the icon.
+14b. Icon names must come from `iconNames` in spec.json. In 2.0 `IconName` is a real union, so an unregistered name is a type error rather than a blank space — do not guess a plausible one, and never reach for `as IconName` to silence the check. If no registered icon fits, omit the icon. The registry is 99 icons; brand marks (github, discord, google) are deliberately not among them, so an app registers its own.
 
 14c. Components with a text prop render it — never pass the same text as both prop and children, it renders twice:
 
@@ -155,9 +155,47 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 // Good eyebrow
 <Text variant="label-default-s" onBackground="brand-medium">Pricing</Text>
 // Bad eyebrow
-<Tag variant="neutral" prefixIcon="sparkle">Pricing</Tag>
+<Tag scheme="neutral" prefixIcon="sparkle">Pricing</Tag>
 ```
 
+20b. **Proportion is a decision, not a leftover.** Two columns in a row finish at
+roughly the same place, or one of them is wrong. A tall card beside a strip of
+small controls leaves a column of dead space that reads as an unfinished page —
+and the fix is almost never more whitespace tokens.
+
+Give the thin side real content instead. Tiles grow to carry their own height,
+with a placeholder, a preview, a swatch, a count — something true about the
+thing they stand for. Then keep them quiet: low-contrast surfaces, small labels,
+no competing headline. A grid of twenty loud tiles takes the section away from
+the card it was meant to support.
+
+```tsx
+// Bad: a tall card and 20 chips, most of the row empty
+<Row fillWidth gap="32">
+  <Column flex={1} maxWidth={26}><FeatureCard /></Column>
+  <Column flex={1}><Row wrap gap="4">{items.map(i => <Button key={i} size="s">{i}</Button>)}</Row></Column>
+</Row>
+
+// Good: both sides carry weight, the card still leads
+<Row fillWidth gap="32">
+  <Column flex={2}><FeatureCard /></Column>
+  <Column flex={3}>
+    <Grid columns={5} s={{ columns: 3 }} gap="8" fillWidth>
+      {items.map(i => (
+        <Column key={i} aspectRatio="1 / 1" padding="12" radius="l"
+                background="page" border="neutral-alpha-weak" vertical="between">
+          {/* a preview of the thing, not just its name */}
+        </Column>
+      ))}
+    </Grid>
+  </Column>
+</Row>
+```
+
+Check it by squinting at the two columns' bottom edges. If one ends halfway up
+the other, change the flex ratio, the tile size, or what the tiles contain —
+in that order.
+
 ## Decorative layers
 
 21. Every absolute decorative layer uses the full recipe — `top="0" left="0"` are required or the layer gets offset by parent padding:
@@ -184,21 +222,21 @@ Siblings holding content get `zIndex={1}`. `overflow="hidden"` goes on the paren
 
 ## Effect units
 
-24. `RevealFx`: `delay` is in **seconds** — stagger with `delay={index * 0.1}`, never `index * 80`. `translateY` as a number is in **rem** — use `translateY={1}` or a token like `"16"` (1rem); `16` means 16rem.
+24. `RevealFx`: `delay` is in **milliseconds** — stagger with `delay={index * 100}`, never `index * 0.1` (that was 1.8.x, and 2.0 reads it as a tenth of a millisecond, i.e. no stagger at all). `ShineFx.speed` is milliseconds for the same reason. `translateY` as a number is in **rem** — use `translateY={1}` or a token like `"16"` (1rem); `16` means 16rem.
 
 25. `LogoCloud` extends `Grid` — always set `columns` (and responsive overrides), or logos stack in one column: `columns="4" m={{ columns: 3 }} s={{ columns: 2 }}`.
 
-26. Use decoration recipes from `recipes.md` verbatim, then adjust. Budget: at most one ambient background layer per section, ambient motion in at most the hero and final CTA, one accent color family per page.
+26. Use decoration recipes from `recipes.md` verbatim, then adjust. Application shells — a dashboard with a sidebar, a data-driven nav, a two-pane editor — come from `layouts.md` the same way. Budget: at most one ambient background layer per section, ambient motion in at most the hero and final CTA, one accent color family per page.
 
 ## Motion
 
-27. Animations are **eye-leading, not eye-grabbing**: they direct attention to the one thing that should be read next, they don't announce themselves. Small distances (`translateY="8"`–`"16"`, i.e. 0.5–1rem), short staggers (`delay={index * 0.1}` max), and only on elements worth leading the eye to — the hero heading, stat numbers, the highlighted card in a set.
+27. Animations are **eye-leading, not eye-grabbing**: they direct attention to the one thing that should be read next, they don't announce themselves. Small distances (`translateY="8"`–`"16"`, i.e. 0.5–1rem), short staggers (`delay={index * 100}` max), and only on elements worth leading the eye to — the hero heading, stat numbers, the highlighted card in a set.
 
 28. Do **not** wrap every section in `RevealFx` — uniform entrance animation on everything reads dated and makes scrolling feel slow. Entry-animation budget per page: the hero, plus at most one or two key moments (stats, a card set). Everything else just renders.
 
-28b. Animate **coherent blocks, all-or-none**. Within a sibling set (cards, list items), either every sibling animates with a stagger or none do — never a single item out of the set (e.g. only the highlighted pricing card). For a hero, reveal it as 1–3 stacked chunks with increasing delay (`0 / 0.1 / 0.2`), not individual text fragments. One entrance moment per viewport: if the hero animates, the cards below it don't.
+28b. Animate **coherent blocks, all-or-none**. Within a sibling set (cards, list items), either every sibling animates with a stagger or none do — never a single item out of the set (e.g. only the highlighted pricing card). For a hero, reveal it as 1–3 stacked chunks with increasing delay (`0 / 100 / 200`), not individual text fragments. One entrance moment per viewport: if the hero animates, the cards below it don't.
 
-29. Trigger below-the-fold animations with `useInViewport`, latched so they play once. `RevealFx` takes `trigger`; `CountFx` has no trigger prop — drive its `value` instead:
+29. Trigger below-the-fold animations with `useInViewport`, latched so they play once. `RevealFx` takes `revealed`; `CountFx` has no trigger prop — drive its `value` instead:
 
 ```tsx
 const ref = useRef<HTMLDivElement>(null);
@@ -209,9 +247,29 @@ useEffect(() => {
 }, [inViewport]);
 
 <Column ref={ref} gap="16">
-  <RevealFx trigger={seen} translateY="8">...</RevealFx>
+  <RevealFx revealed={seen} translateY="8">...</RevealFx>
   <CountFx value={seen ? 2400 : 0} speed={1500} separator="," variant="display-strong-m" />
 </Column>
 ```
 
 Without this, mount-timed animations play while still off-screen and the user scrolls into an already-finished state.
+
+## Imports
+
+30. Most things come from the package root, but three modules do not, because
+their dependencies are optional peers and a root re-export would drag the
+specifier into every consumer's module graph:
+
+| Import | From | Peer the app installs |
+|--------|------|-----------------------|
+| charts, gauges, chart chrome | `@once-ui-system/core/data` | `recharts` |
+| `CodeBlock` | `@once-ui-system/core/code` | `prismjs` |
+| `MediaUpload` | `@once-ui-system/core/media` | `compressorjs` |
+
+Naming one of these from the root does not resolve. Each component slice in
+`ai/components/` carries the specifier to import it from.
+
+31. `IconName` is a real union, not `string`. An unregistered name is a type
+error now, where it used to render a blank space with a console warning — so
+take icon names from `spec.json`'s `iconNames` rather than guessing a plausible
+one. An app registers its own by augmenting `IconLibraryOverrides`.