@trading-game/design-intelligence-layer 0.8.8 → 0.9.0

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

@@ -35,7 +35,7 @@ NEVER use:
   ❌ border-border — deprecated alias; use border-border-subtle or border-border-prominent
 
 ALWAYS use semantic tokens:
-  ✅ bg-background, bg-card, bg-popover, bg-subtle, bg-overlay
+  ✅ bg-prominent, bg-card, bg-popover, bg-subtle, bg-overlay
   ✅ text-on-prominent, text-on-subtle, text-on-muted
   ✅ border-border-subtle, border-border-prominent, ring-ring
   ✅ bg-primary, bg-primary-hover, bg-secondary-hover
@@ -118,7 +118,7 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 
 | CSS Variable     | Tailwind Class   | Usage                     |
 | ---------------- | ---------------- | ------------------------- |
-| `--background`   | `bg-background`  | Main page background      |
+| `--prominent`    | `bg-prominent`   | Main page background      |
 | `--card`         | `bg-card`        | Cards, panels, modals     |
 | `--popover`      | `bg-popover`     | Popovers, elevated cards  |
 | `--subtle`       | `bg-subtle`      | Muted / secondary surfaces|
@@ -274,8 +274,8 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | Show LOSS / negative                   | `text-semantic-loss`              | Any non-token red                      |
 | Show WARNING / caution                 | `text-semantic-warning`           | Raw orange hex or primary tint         |
 | Color a tab container background       | `bg-tabs`                         | `bg-subtle` for tabs                   |
-| Color an active/selected tab           | `bg-tabs-active`                  | `bg-background` for active tab         |
-| Color a page background                | `bg-background`                   | `bg-white` directly                    |
+| Color an active/selected tab           | `bg-tabs-active`                  | `bg-prominent` for active tab          |
+| Color a page background                | `bg-prominent`                    | `bg-white` directly                    |
 | Color a modal/dialog backdrop          | `bg-overlay`                      | `bg-black/50` or raw black opacity     |
 | Color a card or panel                  | `bg-card`                         | Arbitrary gray                         |
 | Color an elevated surface (popover)    | `bg-popover`                      | `bg-card` for popovers                 |
@@ -580,12 +580,51 @@ 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.
+
+### NavBar
+
+A landing page top navigation bar with Desktop and Mobile breakpoint variants.
+
+| 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 |
+
+**Components used:** `Button` (variants: `ghost`, `primary`, `secondary`; sizes: `sm`, `icon-sm`)
+
+**Tokens used:** `bg-prominent`, `bg-primary`, `border-border-subtle`, `rounded-xs`, `rounded-md`
+
+---
+
+### Hero
+
+Landing page hero sections in multiple layout types.
+
+| 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 |
+
+**Components used:** `Button` (default `sm`, `secondary sm`); `ArrowUpRight`, `ArrowRight` icons (lucide)
+
+**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`
+
+---
+
 ## 9 — Common Mistakes
 
 | Mistake | Correct Approach |
 | ------- | ---------------- |
 | Using hardcoded hex (`#2323FF`) for primary | Use `bg-primary` or `text-primary` |
-| Using `bg-white` or `bg-black` | Use `bg-background` or `bg-overlay` |
+| Using `bg-white` or `bg-black` | Use `bg-prominent` or `bg-overlay` |
 | Using `border-border` | Use `border-border-subtle` or `border-border-prominent` |
 | Using `bg-hover` | Use `bg-primary/[0.08]` or `bg-secondary-hover` |
 | Using `text-primary-foreground` | Use `text-on-prominent-static-inverse` |

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

@@ -53,7 +53,7 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 
 #### Background tokens
 ```
-✅ bg-background          — page background (white #FFFFFF)
+✅ bg-prominent           — page background (white #FFFFFF)
 ✅ bg-card                — card/panel surface (white #FFFFFF)
 ✅ bg-popover             — popover/dropdown surface (white #FFFFFF)
 ✅ bg-subtle              — subtle tinted surface (#F5F5F5)
@@ -183,6 +183,25 @@ Wait for confirmation before proceeding.
 
 ---
 
+## Rule 8 — Blocks are playground-only (not package exports)
+
+**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`.
+
+```
+❌ 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
+```
+
+| 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 |
+
+---
+
 ## Rule 7 — Package version upgrades (stay aligned with the published design system)
 
 When the user asks to **update**, **upgrade**, or **install the latest** `@trading-game/design-intelligence-layer`, or after the dependency version changes in `package.json`:

package/package.json

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

package/src/styles.css

@@ -15,7 +15,7 @@
 
 /* ── Tailwind theme bridge — maps CSS vars to utility classes ── */
 @theme inline {
-  --color-background: var(--background);
+  --color-prominent: var(--prominent);
   --color-on-prominent: var(--on-prominent);
   --color-on-prominent-static-inverse: var(--on-prominent-static-inverse);
   --font-sans: var(--font-plus-jakarta-sans);
@@ -234,7 +234,7 @@
    UI role and meaning. References primitives only.
    ══════════════════════════════════════════════════════════════ */
 :root {
-  --background: var(--primitive-mono-50);
+  --prominent: var(--primitive-mono-50);
   --on-prominent: var(--primitive-mono-1000);
   --on-prominent-static-inverse: var(--primitive-mono-50);
   /* #FFFFFF — always white, never changes between themes */
@@ -351,7 +351,7 @@
   }
 
   body {
-    @apply bg-background text-on-prominent font-sans antialiased;
+    @apply bg-prominent text-on-prominent font-sans antialiased;
   }
 }