@trading-game/design-intelligence-layer 1.0.2 → 1.0.4

package/AGENTS.md

@@ -6,16 +6,18 @@ Rules of engagement for AI agents building with `@trading-game/design-intelligen
 
 1. **Semantic colour tokens only.** Classes like `bg-background-brand-default`, `text-text-subtle-default`, `border-border-default-default`. Never hex, never `bg-blue-500`, never primitives — except alpha primitives for glazes/glass (`bg-(--primitive-white-alpha-24)`).
 2. **Never use deprecated aliases** (`bg-prominent`, `text-on-subtle`, `border-subtle`, `bg-primary`, `text-primary`, `ring-ring`, `bg-subtle`, `secondary-hover`, `destructive`, mono-alpha). They exist only for un-migrated external consumers and die at v1.0.
-3. **No bold.** Semibold (600) is the maximum weight in any component or component-adjacent UI. 700/800 belong to the foundation heading scale only.
-4. **No shadows** on inline components — elevation = hairline borders + surface steps. Exactly **two** sanctioned exceptions, both named tokens: **floating mobile chrome** (Bottom Navigation) carries the soft ambient `shadow-chrome-default` lift, and the **Slide to Confirm handle** carries `shadow-brand-glow` so a committed money action reads as liftable off its track. Both come from the Refined spec. Never add any other shadow, and never reuse these two tokens elsewhere.
+3. **No bold.** Semibold (600) is the maximum weight in any component or component-adjacent UI. 700/800 belong to the foundation heading scale only. **One sanctioned exception:** the Result Snackbar's amount keeps bold 700 (`--result-snackbar-amount-font-weight`) — the settled figure is the entire reason that surface exists. Do not read this as a licence to bold other component text.
+4. **No shadows** on inline components — elevation = hairline borders + surface steps. Exactly **two** sanctioned shadows, both named tokens. `shadow-chrome-default` belongs to the **floating-chrome class** — chrome that floats over live content and must separate from it: the Bottom Navigation, and the Result Snackbar over a chart. `shadow-brand-glow` belongs to the **Slide to Confirm handle** alone, so a committed money action reads as liftable off its track. Both come from the Refined spec. Never add a third shadow, and never reach for either token outside the class it names.
 5. **Surfaces are solid.** Alpha is only for state layers on top of a solid base: hover/pressed glazes, glass, scrims, selection washes (light theme only).
 6. **Selection states use the selected family**: `bg-background-brand-selected` + `text-text-brand-selected` + `border-border-brand-selected`. Never `brand-default/10` washes, never `text-brand-default` as selected ink — those fail in dark.
-7. **Dark is not a mirror.** Never build a light-theme construction and assume it inverts. If a token pair doesn't exist for what you need, stop and ask — don't improvise per-theme values in a component.
-8. **Typography via type classes.** Component text uses its `.type-<component>-*` class (backed by private `--<component>-*` tokens). No `text-sm`, no `text-[13px]`, no `font-bold`.
-9. **`.type-*` classes are plain CSS, not utilities**: variants can't gate them (`data-[x]:type-foo` does nothing — pick the class in JSX or write a CSS data-attribute rule), and they beat layered `font-*` utilities.
-10. **Radius encodes element class** — buttons/chips `rounded-full`, icon buttons circles, cards/dialogs `rounded-2xl`, menus `rounded-lg`, menu rows `rounded-md`, inputs `rounded-xs` (deliberate, don't "fix" it).
-11. **Sizes sit on the 32/40/48 rail**, default `md` (40px). Button padding-x = height/2 − 4, gap 8, and padding never changes when icons are hidden.
-12. **Focus** = `focus-visible:ring-[3px] focus-visible:ring-ring-focus-strong` (controls) or `ring-ring-focus-soft` (text fields). Error ring = `ring-ring-error-soft`. Every colour must be a plain named token — no alpha-modified constructions, no colour primitives outside the sanctioned glass-ladder set; `npm run check:tokens` enforces both and diffs the Colors page against styles.css.
+7. **The inverse family *is* the opposite theme's page ladder.** `text-{prominent,subtle,disabled}-inverse` carry exactly the values the other theme's page inks carry — light inverse == dark page, dark inverse == light page. Never invent a bespoke construction for it.
+8. **Dark is not a mirror.** Never build a light-theme construction and assume it inverts. If a token pair doesn't exist for what you need, stop and ask — don't improvise per-theme values in a component.
+9. **Typography via type classes.** Component text uses its `.type-<component>-*` class (backed by private `--<component>-*` tokens). No `text-sm`, no `text-[13px]`, no `font-bold`.
+10. **`.type-*` classes are plain CSS, not utilities**: variants can't gate them (`data-[x]:type-foo` does nothing — pick the class in JSX or write a CSS data-attribute rule), and they beat layered `font-*` utilities.
+11. **Radius encodes element class** — buttons/chips `rounded-full`, icon buttons circles, cards/dialogs `rounded-2xl`, menus `rounded-lg`, menu rows `rounded-md`, inputs `rounded-xs` (deliberate, don't "fix" it).
+12. **Sizes sit on the 32/40/48 rail**, default `md` (40px). Button padding-x = height/2 − 4, gap 8, and padding never changes when icons are hidden.
+13. **Disabled is tokens, never `opacity`.** An element `opacity` dims the fill and the ink on top of it by the same factor, so the relationship between them collapses — a disabled `primary` Button used to render its white label at ~1.6:1 on its own washed fill and vanish. Use the trio: `text-disabled-default` for ink, `background-disabled-default` for the surface, `border-disabled-default` for the edge. The background token is a **glaze** — lay it on `background-image` (`[background-image:linear-gradient(var(--background-disabled-default),var(--background-disabled-default))]`) so the variant's own fill stays underneath and each variant keeps its identity. Fill-less variants (`tertiary`, ghost rows, menu items) take the ink only. On-brand surfaces stay on the static white ladder with `text-on-brand-disabled-default`. The only sanctioned `opacity-24` left is Button's `loading`.
+14. **Focus** = `focus-visible:ring-[3px] focus-visible:ring-ring-focus-strong` (controls) or `ring-ring-focus-soft` (text fields). Error ring = `ring-ring-error-soft`. Every colour must be a plain named token — no alpha-modified constructions, no colour primitives outside the sanctioned glass-ladder set; `npm run check:tokens` enforces both and diffs the Colors page against styles.css.
 
 ## Composition patterns
 
@@ -32,6 +34,9 @@ Rules of engagement for AI agents building with `@trading-game/design-intelligen
 - A new component colour token (`--mycomponent-bg`) → forbidden; colour stops at the semantic layer.
 - `position="item-aligned"` on Select → the default is `popper` (list drops below the trigger); don't switch back without a reason.
 - Re-adding `xs` button sizes, Kbd, Collapsible, Ticket Card, Chart, Combobox, Form, or the Badge `glass` variant — all removed by design decisions.
+- `disabled:opacity-24` (or any element `opacity`) as a disabled state → use the token trio; opacity multiplies through children and erases the fill/ink relationship.
+- Carousel or any other component growing its own dots → compose `PaginationDots`.
+- Reaching for `ResultSnackbar` for anything other than a settled **win or loss** — refunds, rejections, and every other notification go to `toast`. It reports a figure; it is not a notification surface.
 
 ## Component index — when to use what
 
@@ -50,7 +55,7 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Button | All actions; variants primary / secondary / tertiary / on-brand family / frosted + frosted-on-brand; `shimmer` modifier for headline CTAs |
 | Calendar | Date and range picking with themed dropdown month/year navigation |
 | Card | Content shells (`default`, `frosted` tint for page surfaces, `frosted-on-brand` for art/brand, `interactive` hover-lift); blank by design, slots supply content |
-| Carousel | Horizontally scrolling content (mobile catalogue) |
+| Carousel | Horizontally scrolling content (mobile catalogue). Exposes `selectedIndex`/`slideCount`/`scrollTo`; `CarouselDots` composes Pagination's indicator rather than drawing its own |
 | Chip | Compact choice pills: quick amounts, single-select filters, outline error-recovery |
 | Checkbox | Boolean form input |
 | Command | Searchable command palette (menu family) |
@@ -69,10 +74,10 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Link | Inline/standalone links — quiet at rest, underline + darker ink on hover; `tone="on-brand"` |
 | Menubar | Horizontal app menu bar (menu family) |
 | Native Select | Styled native `<select>` for OS-native picking; same rail as Input |
-| Navigation Button | Circular icon-only nav control — tinted at rest, one step darker on hover; `frosted-on-brand` variant for art surfaces. Dialog and Sheet close buttons compose it rather than hand-rolling a circle |
+| Navigation Button | Circular icon-only nav control — tinted at rest, one step darker on hover; `frosted-on-brand` variant for art surfaces (no outline, matching Button's frost). Dialog and Sheet close buttons compose it rather than hand-rolling a circle |
 | Navigation Menu | Marketing-style nav with dropdown panels (menu family type) |
 | Numpad | Mobile amount-entry tray: bare 3×4 grid, emits keys, long-press backspace clears |
-| Pagination | Page navigation; circular cells, brand-selected active page |
+| Pagination | Page navigation. Three forms of "which of N am I on": numbered circular cells; `PaginationDots` (carousel-style, active dot widens to a pill); `PaginationBar` (segmented). Dots/bar are controlled and interactive — not to be confused with Progress `dots`, which fills cumulatively |
 | Popover | Click-triggered floating card for small forms/details |
 | Profile Photo | Avatar with verification ring, camera slot, status badge |
 | Progress | Determinate progress bar (brand fill on 20% wash track) |
@@ -94,7 +99,7 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Table | Data tables; 14px cells, medium heads, hover glaze rows |
 | Tabs | Segmented control (`default` pill-on-track) or underline (`line`) |
 | Textarea | Multi-line text (mirrors Input md) |
-| Toast | Transient notifications (sonner, inverse surface) |
+| Toast | Two surfaces, deliberately different: `Toaster`/`toast` is transient system messaging (sonner, inverse borderless pill); `ResultSnackbar` is the settlement surface — floating-chrome glass card, illustration slot, signed figure, visible dwell timer |
 | Toggle / Toggle Group | Chip-treatment pressed buttons; the group joins them into segmented sets — one docs page (`toggle.md`) |
 | Tooltip | Hover hints; inverse surface default, bordered-white `inverse` variant; renders as a Drawer on mobile |
 

package/README.md

@@ -74,13 +74,16 @@ React 18+, ReactDOM, Tailwind CSS v4+.
 
 ## What's inside
 
-- **59 components** — forms, overlays, menus, navigation, data display, plus trading-specific pieces (Numpad, the Stepper amount tray, Slide to Confirm, Steps timelines, Bottom Navigation with its liquid selection bubble + AI circle, Profile Photo)
+- **59 components** — forms, overlays, menus, navigation, data display, plus trading-specific pieces (Numpad, the Stepper amount tray, Slide to Confirm, Steps timelines, Bottom Navigation with its liquid selection bubble + AI circle, Profile Photo, and the Result Snackbar for a settled win or loss)
 - **Three-layer token architecture** — primitives → semantics → component type tokens; components consume semantic colour tokens only, and `npm run check:tokens` fails the build on any drift (undocumented tokens, primitives in components, alpha-modified colour constructions)
 - **Three-layer motion system** — duration/easing primitives → semantic roles (hover, press, surface, overlay) → named signature moves (the liquid travel spring, the arrival pop); overlay animations ship with the package
 - **Light + dark themes** — dark is designed, not mirrored: its own surface mixes, selection fills, and ink steps; every selected/current-state marker (calendar today, breadcrumb page, links, radio, nav bubble) speaks the brand-selected ink family in dark
+- **A tuned ink ladder** — prominent → subtle → disabled is set by the *gap* between steps rather than by matching ramp positions, and the inverse family is defined as the opposite theme's page ladder rather than a bespoke construction. On a brand fill the ladder inverts, descending from white through the sanctioned alpha rungs (`text-on-brand-subtle-static`, `text-on-brand-disabled-default`)
 - **Tinted canvas** — the signature screen background (`--background-tinted-canvas`): a blue aurora melting into the canvas, pure token math, applied once on the page root
 - **The frosted family** — `variant="frosted"` (brand-tinted glass on page surfaces) and `variant="frosted-on-brand"` (white frost on art) across Button, NavigationButton, and Card
-- **No shadows** — elevation is hairlines and surface steps, with two sanctioned exceptions: the Bottom Navigation's floating-chrome lift and the Slide to Confirm handle's brand glow
+- **Disabled is tokenised, not dimmed** — no element `opacity` anywhere: `text-disabled-default` ink, a `background-disabled-default` *glaze* laid over each variant's own fill (white 24% in light, black 50% in dark), and `border-disabled-default` for the edge. So a disabled `primary` still reads as a filled brand button rather than losing its label, and disabled states never compound through nested elements
+- **Position indicators** — Pagination ships three forms of "which of N am I on": numbered cells, `PaginationDots` (active dot widens to a pill) and `PaginationBar` (segmented). Carousel exposes its index and composes them via `CarouselDots`, so there is exactly one indicator implementation
+- **No shadows** — elevation is hairlines and surface steps, with two sanctioned shadows: the floating-chrome lift (Bottom Navigation, Result Snackbar) and the Slide to Confirm handle's brand glow
 - **Pill shape system** — buttons and chips are pills, icon buttons are circles, cards 18px, menus 10px, form fields 4px; every control on the 32/40/48 rail
 - **AI-readable in `node_modules`** — AGENTS.md, all 58 component pages (Toggle and Toggle Group share one), foundations, and patterns ship inside the npm tarball
 - **TypeScript, ESM + CJS**