@trading-game/design-intelligence-layer 0.14.0 → 0.15.0

package/guides/design-system-guide/trading-game-ds-guide.md

@@ -614,71 +614,237 @@ These are styling behaviors you can't discover from TypeScript types alone:
 
 ## 8.5 — Blocks Catalogue
 
-> Blocks are fully composed UI sections built from design system primitives. They appear in the **Blocks** tab of the playground.
-> - Blocks are **NOT exported** from the npm package — they are playground demonstrations only.
-> - To build them in a consuming project, import the underlying components (`Button`, etc.) from `@trading-game/design-intelligence-layer` and compose them manually using design tokens only.
-> - Do NOT mistake a Block for a component — it will not appear in Rule 1's component list.
+> Blocks are fully composed UI sections built from design system primitives. They are **exported from the package** the same as primitives — import them by name and pass data via props.
+> - **Variants** (`layout` / `mode` / `status`) live on a single block, not separate components.
+> - Each block ships with internal state where appropriate (e.g. `NavBarBlock` manages its own mobile-menu drawer).
+> - Blocks appear in the **Blocks** tab of the playground for visual reference, with the demo importing the same exports a consumer would.
 
-### NavBar
+### `HeroBlock`
 
-A landing page top navigation bar with Desktop and Mobile breakpoint variants.
+Marketing hero section with two layouts.
+
+```tsx
+import { HeroBlock } from "@trading-game/design-intelligence-layer"
+
+<HeroBlock
+  layout="centered"                                       // "centered" | "split"
+  tagline={{ label: "What's new", suffix: "v2.0" }}
+  heading="Solve your customer's main problem"
+  body="One or two sentences expanding on the value prop."
+  primaryCta={{ label: "Get started" }}
+  secondaryCta={{ label: "Learn more" }}                  // split layout only
+/>
+```
 
 | Variant | Description |
 |---------|-------------|
-| Desktop | Full-width bar: logo left, ghost nav links centre-left, Sign in (ghost) + Sign up (primary) right |
-| Mobile — closed | Logo left, hamburger icon-button right |
-| Mobile — open | Logo + close icon top row; stacked ghost nav links + full-width Sign in / Sign up below a divider |
+| `centered` (Desktop) | Centred single-column: tagline pill + heading + body + single primary CTA with `ArrowRight` icon; no image |
+| `split` (Desktop) | Two columns: tagline pill + heading + body + Get started / Learn more CTAs left; square image panel right |
+| `split` (Mobile) | Single column stacked: text content centred above, image panel full-width below |
 
-**Components used:** `Button` (variants: `ghost`, `primary`, `secondary`; sizes: `sm`, `icon-sm`)
+**Components used:** `Button` (default `sm`, `secondary sm`); `ArrowUpRight`, `ArrowRight` icons (lucide)
 
-**Tokens used:** `bg-prominent`, `bg-primary`, `border-border-subtle`, `rounded-xs`, `rounded-md`
+**Tokens used:** `bg-prominent`, `bg-subtle`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`, `bg-semantic-win`, `rounded-xl`, `rounded-full`, `px-layout-margin-inline`, `gap-layout-gutter`, `py-24`, `text-5xl`, `font-semibold`, `font-display`, `tracking-tight`, `text-lg`, `font-body`, `text-sm`, `shadow-sm`, `max-w-2xl`
 
 ---
 
-### Hero
+### `AuthBlock`
+
+Sign-in / sign-up form. Form fields are identical between modes; `mode` drives heading, terms copy, CTA label, and the footer cross-link.
+
+```tsx
+import { AuthBlock } from "@trading-game/design-intelligence-layer"
+
+<AuthBlock
+  mode="sign-in"                                          // "sign-in" | "sign-up"
+  logoSrc="/path/to/brand-icon.svg"                       // consumer-provided
+  providers={["google", "telegram", "x"]}                 // default: all three
+  onSubmit={({ email }) => { ... }}
+  crossLinkHref="/auth/signup"
+/>
+```
+
+| Region | Content |
+|--------|---------|
+| Top | Brand logo + wordmark lockup |
+| Heading | "Sign in" / "Sign up" (mode-driven) |
+| Providers | Configurable OAuth buttons (Google, Telegram, X) |
+| Body | "or" divider + email input + terms paragraph |
+| Footer | Primary CTA + footer cross-link to the opposite mode |
+
+**Components used:** `Button`, `Input`, `Link`
+
+**Tokens used:** `text-on-prominent`, `text-on-subtle`, `bg-border-subtle`, `font-display`, `font-body`
+
+---
 
-Landing page hero sections in multiple layout types.
+### `FAQBlock`
+
+Frequently-asked-questions section with optional help card.
+
+```tsx
+import { FAQBlock } from "@trading-game/design-intelligence-layer"
+
+<FAQBlock
+  layout="desktop"                                        // "desktop" | "mobile"
+  items={[{ value: "q1", question: "...", answer: "..." }, ...]}
+  intro={<>Optional intro paragraph with a <Link>link</Link>.</>}
+  helpCard={{ title: "Need more help?", body: "...", ctaLabel: "Contact us" }}
+/>
+```
 
 | Variant | Description |
 |---------|-------------|
-| Type 1 — Desktop | Two columns: tagline pill + heading + body + Get started / Learn more CTAs left; square image panel right |
-| Type 1 — Mobile | Single column stacked: text content centred above, image panel full-width below |
-| Type 2 — Desktop | Centred single-column: tagline pill + heading + body + single primary CTA with `ArrowRight` icon; no image |
+| `desktop` | `text-5xl` heading, `gap-12`, help card padding `p-8` |
+| `mobile` | `text-4xl` heading, `gap-10`, help card padding `p-6` |
 
-**Components used:** `Button` (default `sm`, `secondary sm`); `ArrowUpRight`, `ArrowRight` icons (lucide)
+**Components used:** `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Button`
 
-**Tokens used:** `bg-prominent`, `bg-subtle`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`, `bg-semantic-win`, `rounded-xl`, `rounded-full`, `px-layout-margin-inline`, `gap-layout-gutter`, `py-24`, `text-5xl`, `font-semibold`, `font-display`, `tracking-tight`, `text-lg`, `font-body`, `text-sm`, `shadow-sm`, `max-w-2xl`
+**Tokens used:** `text-on-prominent`, `text-on-subtle`, `bg-subtle`, `font-display`, `font-body`, `rounded-xl`
 
 ---
 
-### Sheet Open Positions
+### `NavBarBlock`
 
-A slide-in panel listing the user's open trading positions. Responsive — renders as a right-side `Sheet` on desktop and a bottom `Drawer` on mobile.
+A landing page top navigation bar with internal mobile-menu state. Single component handles both desktop bar and mobile drawer.
 
-| State | Description |
-|-------|-------------|
-| Active | Scrollable list of open positions with direction, asset, stake, and P&L per row. Win/loss coloured with semantic tokens. Footer button links to transaction history. |
-| Empty | Empty state with icon and "No trades yet." message in place of the list. |
+```tsx
+import { NavBarBlock } from "@trading-game/design-intelligence-layer"
+
+<NavBarBlock
+  brand={{ fullLogoSrc: "...", iconLogoSrc: "...", alt: "Brand" }}
+  links={[{ label: "Products" }, { label: "Docs" }, ...]}
+  signIn={{ onClick: ... }}
+  signUp={{ onClick: ... }}
+/>
+```
 
-**Components used:** `Sheet`, `Drawer`, `Item`, `ItemGroup`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `Button`, `NavigationButton`, `Separator`
+| Breakpoint | Description |
+|------------|-------------|
+| Desktop (≥600 px) | Full-width bar: full logo + tertiary nav links left; Sign in (tertiary) + Sign up (primary) right |
+| Mobile — closed | Icon logo left, hamburger icon-button right |
+| Mobile — open | Stacked tertiary nav links + full-width Sign in (secondary) / Sign up (primary) below a divider |
 
-**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-semantic-win`, `text-semantic-loss`, `text-on-prominent`, `text-on-subtle`
+**Components used:** `Button` (variants: `tertiary`, `secondary`, default; sizes: `sm`, `icon-sm`); `Menu`, `X` icons (lucide)
+
+**Tokens used:** `bg-prominent`, `border-border-subtle`, `rounded-md`, `px-layout-margin-inline`
 
 ---
 
-### Header navigation
+### `HeaderNavigationBlock`
 
-A product app top header bar. Not a landing page component — used inside the trading game itself.
+A product app top header bar. Includes optional history button with overlaid numeric count badge.
+
+```tsx
+import { HeaderNavigationBlock } from "@trading-game/design-intelligence-layer"
+
+<HeaderNavigationBlock
+  onBack={() => router.back()}
+  badge={{ label: "Demo", variant: "fill-warning" }}
+  balance={{ amount: "1000.00", currency: "USDT" }}
+  history={{ count: 5, onClick: openHistorySheet }}       // count 0 hides badge; >99 shows "99+"
+  actions={<SoundToggleButton />}
+/>
+```
 
 | Region | Content |
 |--------|---------|
-| Left | `NavigationButton` (back arrow) |
-| Centre | `Badge` (fill-warning "Demo" label) + account balance amount + currency label |
-| Right | `NavigationButton` icons for history and sound toggle |
+| Left | `NavigationButton` (back arrow, rendered only if `onBack` provided) |
+| Centre | `Badge` (fill-warning "Demo" label) + balance amount + currency |
+| Right | History `NavigationButton` with optional numeric badge (`bg-primary`, `ring-2 ring-prominent`) + `actions` slot for additional icon buttons |
+
+**Components used:** `NavigationButton`, `Badge`; `ArrowLeft`, `History` icons (lucide)
+
+**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`, `bg-primary`, `text-on-primary`, `max-w-layout-diagram-small`, `px-layout-margin-inline`
+
+---
+
+### `OpenPositionsBlock`
+
+A slide-in panel listing open trading positions. Responsive — `Sheet` on desktop, `Drawer` on mobile (via `useIsMobile()`).
+
+```tsx
+import { OpenPositionsBlock, type Position } from "@trading-game/design-intelligence-layer"
+
+const positions: Position[] = [
+  { kind: "rise-fall", direction: "Rise", market: "Vol 100", duration: "30 minutes",
+    stake: "1.00 USDT", pnl: "+0.96 USDT", win: true },
+  ...
+]
+
+<OpenPositionsBlock
+  trigger={<Button variant="secondary">Active trades</Button>}
+  positions={positions}
+  sheetTitle="Positions"
+  onViewHistory={openHistoryPage}
+/>
+```
+
+Positions are a discriminated union by `kind`:
+
+| `kind` | Title rendered as | Extra fields |
+|--------|--------------------|--------------|
+| `"rise-fall"` | `direction` (e.g. "Rise" / "Fall") | — |
+| `"swipe"` | `Swipe-<direction>` (e.g. "Swipe-up") | — |
+| `"box-o"` | `"Box-O"` | `multiplier` |
+| `"digits"` | Type label (e.g. "Matches", "Under") | `type`, `digit?` |
+
+**Components used:** `Sheet`, `Drawer`, `Item`, `ItemGroup`, `ItemContent`, `ItemTitle`, `ItemActions`, `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `Button`, `NavigationButton`, `Separator`
+
+**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-semantic-win`, `text-semantic-loss`, `text-on-prominent`, `text-on-subtle`
+
+---
+
+### `ResultBlock`
+
+Universal end-of-round result card. Fixed-width (320 px) with animated halo + thumb illustration (bundled inline as base64) + contract/duration badges + CTA.
+
+```tsx
+import { ResultBlock } from "@trading-game/design-intelligence-layer"
+
+<ResultBlock
+  status="win"                                            // "win" | "loss"
+  amount="10,000.00"
+  currency="USDT"
+  contractLabel="Rise"
+  duration="2 hours"
+  pickedDigit={7}                                         // optional, for Digits contracts
+  ctaMode="next-round"                                    // "next-round" | "go-again" | "conversion"
+/>
+```
+
+| `ctaMode` | Renders |
+|-----------|---------|
+| `"next-round"` | Single "Next round" button |
+| `"go-again"` | Single "Go again" button |
+| `"conversion"` | "Ready to play for real?" heading + "Deposit now" + "Stay in demo" |
+
+The float / shake / halo animations are defined in `src/styles.css` and ship with the package — consumers who `@import "@trading-game/design-intelligence-layer/styles"` get them automatically.
+
+**Components used:** `Card`, `Badge` (variant `standard`), `Button`
+
+**Tokens used:** `bg-semantic-win`, `bg-semantic-loss`, `text-semantic-win`, `text-semantic-loss`, `text-on-prominent`, `bg-border-prominent/40`, `font-display`, `font-semibold`, `tabular-nums`, `tracking-tight`, `rounded-md`, `shadow-sm`
+
+---
+
+### `ResultDialog`
+
+Fixed-width system dialog (title + body + two CTAs). Used for messages adjacent to `ResultBlock` like "out of balance" or "on a roll" — same width and styling, no thumb or amount.
+
+```tsx
+import { ResultDialog } from "@trading-game/design-intelligence-layer"
+
+<ResultDialog
+  title="You're out of balance."
+  body="Deposit to keep playing or stay in demo mode."
+  primaryLabel="Deposit now"
+  secondaryLabel="Stay in demo"
+/>
+```
 
-**Components used:** `NavigationButton`, `Badge`
+**Components used:** `Card`, `Button`
 
-**Tokens used:** `bg-prominent`, `border-border-subtle`, `text-on-prominent`, `text-on-subtle`
+**Tokens used:** `text-on-prominent`, `text-on-subtle`, `rounded-md`, `shadow-sm`
 
 ---
 

package/guides/rules/design-system-consuming-project.mdc

@@ -210,22 +210,30 @@ Wait for confirmation before proceeding.
 
 ---
 
-## Rule 8 — Blocks are playground-only (not package exports)
+## Rule 8 — Blocks are first-class exports (import them by name)
 
-**Blocks** are pre-composed UI sections (e.g. NavBar) demonstrated in the **Blocks** tab of the design system playground. They are **not** exported from `@trading-game/design-intelligence-layer`.
+**Blocks** are opinionated, composed UI sections — exported from `@trading-game/design-intelligence-layer` the same as primitives. Import by name and pass data via props. Variants live as a `layout` / `mode` / `status` prop on a single block, not as separate components.
 
 ```
-❌ Do NOT import blocks from the package — they don't exist there
-❌ Do NOT treat block names (e.g. "NavBar") as component names from Rule 1
-✅ To build a block pattern in your project: compose it manually using package components + tokens
-✅ Reference guides/design-system-guide/trading-game-ds-guide.md Section 8.5 for block structure
+✅ Import blocks directly from the package — same pattern as primitives
+✅ Pass data via props; variants are configured via a single variant prop
+✅ Block names ARE valid component names (treat them like Rule 1 components)
+❌ Do NOT re-implement a block by hand if a block export already covers it
+❌ Do NOT split variants into separate blocks — use the variant prop
 ```
 
-| Block | Playground tab | Importable? |
-|-------|---------------|-------------|
-| NavBar | Blocks → NavBar | No — build with `Button` + tokens |
-| Hero (Type 1) | Blocks → Hero | No — build with `Button` + tokens; two-column layout with image panel |
-| Hero (Type 2) | Blocks → Hero | No — build with `Button` + `ArrowRight` icon + tokens; centred single-column, no image |
+| Block | Variants | Importable? |
+|-------|----------|-------------|
+| `HeroBlock` | `layout: "centered" \| "split"` | Yes — `import { HeroBlock }` |
+| `AuthBlock` | `mode: "sign-in" \| "sign-up"` | Yes — `import { AuthBlock }` |
+| `FAQBlock` | `layout: "desktop" \| "mobile"` | Yes — `import { FAQBlock }` |
+| `NavBarBlock` | — (internal mobile-menu state) | Yes — `import { NavBarBlock }` |
+| `HeaderNavigationBlock` | — (optional `history.count` badge) | Yes — `import { HeaderNavigationBlock }` |
+| `OpenPositionsBlock` | `Position` discriminated union | Yes — `import { OpenPositionsBlock, type Position }` |
+| `ResultBlock` | `status` + `ctaMode` | Yes — `import { ResultBlock }` |
+| `ResultDialog` | — | Yes — `import { ResultDialog }` |
+
+See `guides/design-system-guide/trading-game-ds-guide.md` § 8.5 for full per-block API, used components, and used tokens.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/styles.css

@@ -490,4 +490,26 @@
   font-weight: 600;
   font-size: 8px;
   line-height: 12px;
+}
+
+/* ── Result block — icon motion ─────────────────────────────── */
+[data-results-motion="halo"] {
+  opacity: 0.22;
+}
+[data-results-motion="icon-win"] {
+  animation: results-icon-float 2.2s ease-in-out infinite;
+}
+[data-results-motion="icon-loss"] {
+  animation: results-icon-shake 2.4s ease-in-out infinite;
+}
+@keyframes results-icon-float {
+  0%, 100% { transform: translateY(0) rotate(0); }
+  50%      { transform: translateY(-10px) rotate(-4deg); }
+}
+@keyframes results-icon-shake {
+  0%, 100% { transform: rotate(-8deg); }
+  50%      { transform: rotate(8deg); }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-results-motion] { animation: none !important; }
 }