@once-ui-system/core 1.8.5 → 2.0.0-alpha.1

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)
 
@@ -86,7 +87,7 @@ For the emphasized item in a set (e.g. "most popular" pricing tier). Border + to
 Self-contained drifting brand/accent blobs (already blurred and pointer-transparent). Use behind a final CTA or feature visual — counts as continuous motion:
 
 ```tsx
-<Card fillWidth radius="l" border="neutral-alpha-weak" overflow="hidden" padding="48">
+<Card fillWidth radius="l" border overflow="hidden" padding="48">
   <BlobFx position="absolute" top="0" left="0" fill opacity={60} seed={2} />
   <Column zIndex={1} center gap="24">
     {/* CTA content */}
@@ -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
 
@@ -11,6 +11,9 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For pr
 | `fill` | `fillWidth fillHeight` |
 | `fit` | `fitWidth fitHeight` |
 | `center` | `horizontal="center" vertical="center"` |
+| `maxWidth="l"` | `fillWidth maxWidth="l"` |
+| `fillWidth` | `fillWidth minWidth={0}` |
+| `border` | `border="neutral-alpha-weak"` |
 
 - `Flex` only when direction changes at breakpoints: `<Row s={{ direction: "column" }}>`
 - Page skeleton: `Column as="main" fillWidth horizontal="center"` → content `Column maxWidth="l"` → sections
@@ -22,9 +25,10 @@ Load with task bundle from `@once-ui-system/core/ai/tasks/{intent}.json`. For pr
 Static panel recipe (pricing tiers, stats, settings sections):
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
+- Bare `border` (and `borderTop`, `borderBottom`, …) = the default border. Name a colour only to deviate: `border="brand-alpha-medium"`.
 - `Card` = interactive only (`href` or `onClick`). Static panels = Column + surface recipe.
 - Colors: `{scheme}-{weight}` or `{scheme}-alpha-{weight}`. Never hex/rgb.
 - `background` also: `surface | overlay | page | transparent`
@@ -40,6 +44,8 @@ Static panel recipe (pricing tiers, stats, settings sections):
 
 Absolute layers always: `position="absolute" top="0" left="0" fill pointerEvents="none"`, content `zIndex={1}`.
 
+- `zIndex` only inside that layer group (or on a sticky header over its pane). Never on a lone element, never a page-wide ladder.
+
 - Gradient `width`: quarter-percent (400 = 100%). Glows: 100–200.
 - Glow colors: `brand-alpha-medium`, not `brand-background-weak`
 - Ambient layers on full-bleed section wrapper, outside `maxWidth` column
@@ -47,9 +53,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,9 +70,24 @@ 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.
+`position="relative"`, `direction` on Row/Column, `variant="primary"` on Button, `size="m"` when default, `fillWidth` beside `maxWidth`, `minWidth={0}` beside `fillWidth`, a border colour that restates the default.
 
 ## Before building
 

package/ai/rules.md

@@ -40,14 +40,26 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 <Row fillWidth fillHeight horizontal="center" vertical="center">...</Row>
 ```
 
-3. Never write a prop that equals its default. The spec marks defaults with `= value`. Common offenders:
+3. Never write a prop that equals its default, or one that another prop on the same element already implies. The spec marks defaults with `= value`. Common offenders:
    - `position="relative"` (default on all layout components)
    - `direction="row"` on `Row`, `direction="column"` on `Column`
    - `variant="primary"`, `size="m"` on `Button`
+   - `fillWidth` beside `maxWidth` — `maxWidth` already fills the width up to the cap
+   - `minWidth={0}` beside `fillWidth` — `fillWidth` already sets `min-width: 0`
+   - a colour on `border` (or `borderTop`, `borderBottom`, `borderX`, …) that only restates the default — bare `border` draws the default border; name a colour only to deviate from it
+
+```tsx
+// Good
+<Column maxWidth="l" border radius="l">
+// Bad
+<Column fillWidth maxWidth="l" minWidth={0} position="relative" border="neutral-alpha-weak" radius="l">
+```
+
+3b. `zIndex` belongs to a stacking group, not to a page. Use it only inside an isolated group that needs an order — a decorative absolute layer and the content sibling above it (rule 21), a sticky header over the pane it covers — and keep the values small within that group. A `zIndex` on a lone element, or a page-wide ladder of `zIndex={3}`, `{5}`, `{9}`, means the hierarchy is being managed by hand; restructure the tree instead.
 
 ## 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
@@ -66,10 +78,10 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
    - `background` also accepts `surface | overlay | page | transparent`
    - `onBackground` colors text/icons on a background
 
-8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border="neutral-alpha-weak"` (or `-medium`) + `radius="l"`.
+8. Standard surface recipe: `background="surface"` (or `"overlay"` over imagery) + `border` + `radius="l"`. Bare `border` is the default border; name a colour (`border="neutral-alpha-medium"`, `border="brand-alpha-medium"`) only when the surface should differ from it.
 
 ```tsx
-<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="16">
+<Column background="surface" border radius="l" padding="24" gap="16">
 ```
 
 ## Text
@@ -109,9 +121,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 +167,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 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:
@@ -166,7 +216,7 @@ If you can't ask (or the user says "you decide"), default to: restrained, center
 <Background position="absolute" top="0" left="0" fill pointerEvents="none" ... />
 ```
 
-Siblings holding content get `zIndex={1}`. `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
+Siblings holding content get `zIndex={1}`. That layer and its content sibling are the whole stacking group — nothing else in the section needs a `zIndex` (rule 3b). `overflow="hidden"` goes on the parent **only when it has a radius** (cards, panels) — clipping a full-bleed section turns the glow into a hard-edged band.
 
 21b. Ambient section layers (hero glows) live on the **full-width section wrapper**, outside the `maxWidth` content column, with generous room (`paddingY="80"`+). Inside a narrow container the gradient gets clipped at the container edge and reads as a misplaced card:
 
@@ -184,21 +234,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 +259,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`.