@trading-game/design-intelligence-layer 0.16.0 → 0.16.2

package/AGENTS.md

@@ -61,6 +61,27 @@ cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-syst
 
 ---
 
+## Step 4 — New-component release checklist (MANDATORY)
+
+Every time you add a new component (UI primitive or Block) to this package, **all** of the following must land in the same PR. Skipping any one of these has shipped broken releases before — npm consumers got a version where the component existed in the demo but couldn't be imported. Do not skip a step.
+
+1. **Source file** — `components/ui/<name>.tsx` (or `components/blocks/<name>-block.tsx`)
+2. **Public export** — add the matching `export * from "../components/<…>/<name>"` line to `src/index.ts`. **This is what gates whether npm consumers receive the component at all.** The demo at `app/page.tsx` imports via the `@/components/...` alias and will work without this — but the published package will not ship the component until this line exists.
+3. **Auto-generated registry** — run `npm run generate:registry` so `app/component-registry.generated.ts` picks the new file up.
+4. **Demo entry** — add a sidebar entry in the `componentNames` list in `app/page.tsx`, and a `case "<Name>":` block in the `SectionContent` switch that renders representative variants.
+5. **README** — add a row in the "Available components" table and a per-component section explaining variants / slots / behaviour.
+6. **Design system guide** (`guides/design-system-guide/trading-game-ds-guide.md`) — add a row in the §8 component list table and a styling-notes entry covering tokens used, edge cases, and `aria` posture.
+7. **Build verification** — run `npm run build` and confirm the component name appears in `dist/index.js` and `dist/index.d.ts` before tagging a release:
+   ```bash
+   npm run build
+   grep -c "<ComponentName>" dist/index.js dist/index.d.ts   # both > 0
+   ```
+8. **Version + publish** — only after every step above is checked in, bump `package.json`, commit, push, tag `v<version>`, and let the workflow publish.
+
+If any of these are missing at the time of release, the published package is broken — fix and re-release before moving on.
+
+---
+
 ## Reference
 
 - Full token + component reference: `node_modules/@trading-game/design-intelligence-layer/README.md`

package/README.md

@@ -98,10 +98,11 @@ npm install react react-dom tailwindcss
 | Component | Import |
 |---|---|
 | Accordion | `Accordion, AccordionItem, AccordionTrigger, AccordionContent` |
-| Alert | `Alert` — dismissible in-page notification. Variants: `default`, `brand`, `info`, `warning`, `danger`, `success`. Layouts: `inline`, `card`. Slots: `title`, `description`, `icon`, `action`, `actions`, `onDismiss`. |
+| Alert | `Alert` — dismissible status notification. Variants: `info`, `warning`, `danger`, `success`. Layouts: `inline`, `card`. Slots: `title`, `description`, `icon`, `action`, `actions`, `onDismiss`. |
 | Alert Dialog | `AlertDialog, AlertDialogTrigger, AlertDialogContent, ...` |
 | Avatar | `Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup` |
 | Badge | `Badge, badgeVariants` |
+| Banner | `Banner` — dismissible promotional surface. Single visual treatment (light-blue diagonal gradient). Layouts: `inline`, `card`. Slots: `title`, `description`, `icon`, `action`, `actions`, `onDismiss`, `onClick` (whole-banner clickable). |
 | Breadcrumb | `Breadcrumb, BreadcrumbList, BreadcrumbItem, ...` |
 | Button | `Button, buttonVariants` |
 | Calendar | `Calendar, CalendarDayButton` |
@@ -232,8 +233,9 @@ States: hover (`bg-secondary-hover`), focus (3px `ring-ring/50`), active (`opaci
 <Badge variant="fill" />            // Blue tint
 <Badge variant="fill-success" />    // Green tint
 <Badge variant="fill-fail" />       // Red tint
-<Badge variant="fill-warning" />    // Orange tint
-<Badge variant="fill-credit" />     // Amber-orange tint — credit/bonus labels
+<Badge variant="fill-warning" />    // Yellow tint — status/warning
+<Badge variant="fill-credit" />     // Light peach — credit/bonus labels
+<Badge variant="fill-demo" />       // Red-orange tint — demo/test-mode flags
 
 // Outline (black border, secondary-hover on hover)
 <Badge variant="outline" />
@@ -251,12 +253,10 @@ States: hover (`bg-secondary-hover`), focus (3px `ring-ring/50`), active (`opaci
 
 ## Alert variants
 
-Dismissible, in-page notification surface. Six variants × two layouts × optional title / description / icon / action / dismiss slots.
+Dismissible **status** notification (info / warning / danger / success). For promotional / marketing surfaces, use **Banner** instead.
 
 ```tsx
 // Variant — controls the surface tint and icon accent
-<Alert variant="default" />   // white surface + subtle border (neutral)
-<Alert variant="brand" />     // solid brand-blue surface, white text
 <Alert variant="info" />      // sky-blue tint
 <Alert variant="warning" />   // yellow tint
 <Alert variant="danger" />    // red tint
@@ -290,9 +290,55 @@ Dismissible, in-page notification surface. Six variants × two layouts × option
 
 **Behaviour:**
 - Dismissal is **controlled** — clicking the close X calls `onDismiss`; the parent owns visibility.
-- Brand variant's buttons use `Button variant="primary-inverse"`; every other variant's buttons use `Button variant="secondary"`. Pass a fully-styled `<Button>` to `action` / `actions` to override.
+- All variants' buttons default to `Button variant="secondary"`. Pass a fully-styled `<Button>` to `action` / `actions` to override.
 - Inline + single-line content (only title OR only description) renders at a fixed 48px height with everything vertically centered. Inline + multi-line and card layouts grow to fit.
-- `role="alert"` + `aria-live="assertive"` for `danger` / `warning`; `role="status"` + `aria-live="polite"` for the rest.
+- `role="alert"` + `aria-live="assertive"` for `danger` / `warning`; `role="status"` + `aria-live="polite"` for `info` / `success`.
+
+## Banner
+
+Dismissible **promotional / marketing** surface — for feature launches, offers, onboarding nudges, cross-promo. Single visual treatment (no severity variants); for status messages use **Alert** instead.
+
+```tsx
+// Layout — controls the shape
+<Banner layout="inline" />    // single row: icon · body · optional action · close X (default)
+<Banner layout="card" />      // body on row 1, up to 2 action buttons on row 2 bottom-left
+
+// Slots — all optional (at least one of title or description is required)
+<Banner
+  layout="inline"
+  title={<>Spring release <b>is here.</b></>}        // wrap emphasis in <b> for brand-blue accent
+  description="New features just landed — take a look at what's changed."
+  icon={<MyIcon />}                                   // omit to use the default 40px brand-blue gift badge
+  action="Get started"                                // string wrapped in Button variant="primary"
+  onDismiss={() => setOpen(false)}                    // when provided, close X is rendered
+  dismissLabel="Dismiss"                              // aria-label for the close X
+/>
+
+<Banner
+  layout="card"
+  title="..."
+  description="..."
+  actions={["Learn more", "Get started"]}             // first = Secondary, second = Primary
+  onDismiss={() => setOpen(false)}
+/>
+
+// Whole-banner clickable — the surface itself is the CTA.
+// Mutually exclusive with action / actions (buttons dropped, dev warning).
+<Banner
+  layout="inline"
+  title="Tap anywhere on this banner"
+  description="Whole surface is the click target."
+  onClick={() => navigate("/promo")}
+  onDismiss={() => setOpen(false)}                    // close X still works independently
+/>
+```
+
+**Visual:**
+- Surface: 135° diagonal gradient `#EBEBFF → #FFFFFF` with `border-primary/20` light-blue edge.
+- Default icon: 40px brand-blue circle with a white `Gift` glyph. Override via `icon` (pass any `ReactNode`) or `icon={null}` to omit.
+- Default action button: `Button variant="primary"` (single inline action) or `[Secondary, Primary]` pair (card actions). Pass `<Button>` elements explicitly to override variant/size.
+- Title supports `<b>` children styled with `text-primary` for in-line brand-blue accent.
+- Close X (32px) hovers to `bg-secondary-hover`.
 
 ## Component behaviour notes