npm - @medalsocial/meda - Versions diffs - 2.4.1 → 2.4.2 - Mend

@medalsocial/meda 2.4.1 → 2.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/package.json +10 -2
package/skills/brand/SKILL.md +198 -0
package/skills/components/SKILL.md +196 -0
package/skills/shell/SKILL.md +151 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/meda",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Shared Meda UI shell and runtime package.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,7 +20,11 @@
   "files": [
     "README.md",
     "components.json",
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts",
+    "!skills/**/_artifacts",
+    "!skills/**/_artifacts/**"
   ],
   "exports": {
     ".": {
@@ -191,6 +195,7 @@
     "@storybook/addon-vitest": "10.3.6",
     "@storybook/react-vite": "10.3.6",
     "@tailwindcss/vite": "4.2.4",
+    "@tanstack/intent": "0.0.41",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.2",
     "@types/react": "19.2.14",
@@ -220,6 +225,9 @@
     "vitest-axe": "0.1.0",
     "wrangler": "4.87.0"
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
   "scripts": {
     "build": "pnpm exec tsc -p tsconfig.build.json && node ./scripts/build.mjs",
     "lint": "biome check .",

package/skills/brand/SKILL.md ADDED Viewed

@@ -0,0 +1,198 @@
+---
+name: brand
+description: Use when picking a CTA color, choosing brand-vs-semantic tokens, building a button/badge/pill, styling a chart or sidebar, configuring focus rings, editing any file under `src/styles/`, or scaffolding theme tokens in a new app that consumes `@medalsocial/meda`. Required reading before any visual work — covers the constant-brand CTA rule, the full token contract, and Tailwind v4 wiring.
+---
+# Meda Brand & Tokens
+## When to load this skill
+- Editing `tokens.css`, `theme.css`, `globals.css`, or any file under `src/styles/`.
+- Choosing a color for a CTA, link, badge, status pill, sidebar item, or chart series.
+- Adding, renaming, or removing a token.
+- Picking typography (font family, weight, size scale).
+- Configuring focus rings, radii, or spacing.
+- Wiring a brand logo or accent color in a consumer app.
+## Overview
+`@medalsocial/meda` is **purple-forward with a zinc-aligned neutral base** — not a custom warm/cool scheme. Two coexisting layers of tokens:
+- **Primitive ramps** — `brand-*`, `neutral-*`, `error-*`, `info-*`, `success-*`, `warning-*`, plus dark-mode `surface-*` constants. Constant across themes.
+- **Semantic tokens** — `--primary`, `--accent`, `--background`, `--card`, `--sidebar`, `--chart-1`...`--chart-5`, `--text-*`. Flip by theme.
+Most components reference semantic tokens. Primary CTAs and brand-identity surfaces pin to the brand ramp directly — see the rule below.
+CSS framework: **Tailwind v4**, CSS-first via `@theme inline` in `src/styles/theme.css`. **No `tailwind.config.js`**, no JS preset. Primitives are exposed as Tailwind theme keys (`--color-brand-*`, `--color-neutral-*`, `--color-chart-*`, etc.), so `bg-brand-500`, `text-success-600`, `bg-chart-3` work natively. Dark mode uses the Tailwind `dark:` variant on the `<html>` root.
+## Brand ramp (constant across themes — purple, 11 stops)
+| Stop | Hex |
+|---|---|
+| brand-50  | `#FAFAFD` |
+| brand-100 | `#EEEAF5` |
+| brand-200 | `#DCD4E8` |
+| brand-300 | `#B8A3D2` |
+| brand-400 | `#9A6AC2` |
+| brand-500 | `#7E3FAC` |
+| brand-600 | `#6A2E96` |
+| brand-700 | `#482070` |
+| brand-800 | `#2F1552` |
+| brand-900 | `#1C0E38` |
+| brand-950 | `#120A24` |
+## The constant-brand CTA rule (critical)
+**Primary CTAs and brand-identity surfaces use `bg-brand-500 hover:bg-brand-600 text-white` in BOTH light and dark themes. Do NOT use `bg-primary` / `text-primary-foreground` for primary CTAs.**
+**Why:** `--primary` deliberately flips — `brand-800` in light, `brand-100` in dark. `brand-100` is a pale near-white, so `bg-primary` renders a primary CTA as a washed-out near-white pill in dark mode. Medal's brand identity is the rich `#7E3FAC` purple applied constantly, not theme-inverted.
+**`bg-primary` is fine when used as a tint/overlay** (e.g. `bg-primary/12 text-primary` for an active rail item — see the `shell` skill). The prohibition is specifically about solid CTA fills where the user expects a vivid brand presence.
+```tsx
+// ❌ Wrong: pale in dark
+<Button className="bg-primary text-primary-foreground">Get started</Button>
+// ✅ Right: constant brand-purple in both themes
+<Button className="bg-brand-500 hover:bg-brand-600 text-white">Get started</Button>
+// ✅ Also right (active state, tinted overlay)
+<Link className="bg-primary/12 text-primary">Dashboard</Link>
+```
+Logos and brand marks render in `var(--color-brand-500)`, not `currentColor`.
+## Neutral ramp (zinc-aligned)
+| Stop | Hex | Tailwind zinc |
+|---|---|---|
+| neutral-50  | `#FAFAFA` | zinc-50 |
+| neutral-100 | `#F4F4F5` | zinc-100 |
+| neutral-200 | `#E4E4E7` | zinc-200 |
+| neutral-300 | `#A1A1AA` | zinc-400 |
+| neutral-400 | `#71717A` | zinc-500 |
+| neutral-500 | `#52525B` | zinc-600 |
+| neutral-600 | `#3F3F46` | zinc-700 |
+| neutral-700 | `#27272A` | zinc-800 |
+| neutral-800 | `#18181B` | zinc-900 |
+| neutral-900 | `#111113` | between zinc-900/950 |
+| neutral-950 | `#09090B` | zinc-950 |
+**Do not** ship a generic gray neutral palette (Apple-style cool grays, Tailwind `gray-*`). Use the zinc-aligned ramp.
+## Status ramps
+| Status | Family | Mid (600) |
+|---|---|---|
+| error | rose | `#E11D48` |
+| info | blue | `#2563EB` |
+| **success** | **teal**, not green | `#0D9488` |
+| warning | amber | `#D97706` |
+Each ramp has 10 stops (50, 100–900).
+## Surface primitives (dark-mode constants)
+- `--surface-bg`: `#09090B`
+- `--surface-card`: `#18181B`
+- `--surface-muted`: `#27272A`
+- `--surface-border`: `#2E2E33`
+- `--surface-sidebar`: `#0F0F12`
+## Semantic tokens (flip by theme)
+### shadcn-shape core
+| Token | Light | Dark |
+|---|---|---|
+| `--background` | `neutral-50` | `surface-bg` |
+| `--foreground` | `neutral-950` | `neutral-50` |
+| `--card` | `neutral-50` | `surface-card` |
+| `--card-foreground` | `neutral-950` | `neutral-50` |
+| `--popover` | `neutral-50` | `surface-card` |
+| **`--primary`** | **`brand-800`** | **`brand-100`** |
+| `--primary-foreground` | `brand-50` | `brand-900` |
+| `--secondary` | `neutral-200` | `surface-muted` |
+| `--muted` | `neutral-100` | `surface-muted` |
+| `--muted-foreground` | `neutral-500` | `neutral-300` |
+| `--accent` | `neutral-200` | `surface-muted` |
+| `--destructive` | `error-600` | `error-400` |
+| `--border` | `neutral-200` | `surface-border` |
+| `--input` | `neutral-200` | `surface-muted` |
+| `--ring` | `brand-600` | `brand-400` |
+**Critical:** `--accent` is a NEUTRAL by contract (not a brand color). Use `brand-*` tokens directly when you want brand color. `--ring` (focus ring) is brand-keyed and theme-flips between brand-600 and brand-400.
+### Status (semantic)
+| Token | Light | Dark |
+|---|---|---|
+| `--success` / `--success-foreground` | `success-600` / `neutral-950` | `success-400` / `neutral-950` |
+| `--warning` / `--warning-foreground` | `warning-600` / `neutral-950` | `warning-400` / `neutral-950` |
+| `--info` / `--info-foreground` | `info-600` / `neutral-50` | `info-400` / `neutral-950` |
+| `--danger` (alias for destructive) | `error-600` | `error-400` |
+### Sidebar
+| Token | Light | Dark |
+|---|---|---|
+| `--sidebar` | `neutral-100` | `surface-sidebar` |
+| `--sidebar-foreground` | `neutral-950` | `neutral-50` |
+| `--sidebar-primary` | `brand-700` | `brand-400` |
+| `--sidebar-accent` | `neutral-50` | `surface-card` |
+| `--sidebar-border` | `neutral-200` | `surface-border` |
+| `--sidebar-ring` | `brand-500` | `brand-400` |
+### Chart (5 series)
+| Token | Light | Dark | Role |
+|---|---|---|---|
+| `--chart-1` | `brand-600` | `brand-500` | Brand purple |
+| `--chart-2` | `info-600` | `info-500` | Blue |
+| `--chart-3` | `success-600` | `success-400` | Teal |
+| `--chart-4` | `warning-600` | `warning-500` | Amber |
+| `--chart-5` | `error-600` | `error-400` | Rose |
+Always cycle in this order — `--chart-1` first — so brand purple owns the primary series across consumers.
+### Text
+| Token | Light | Dark |
+|---|---|---|
+| `--text` | `neutral-950` | `neutral-50` |
+| `--text-muted` | `neutral-500` | `neutral-300` |
+| `--text-link` | `brand-600` | `brand-400` |
+| `--text-primary` | `neutral-950` | `neutral-100` |
+| `--text-secondary` | `neutral-600` | `neutral-300` |
+## Typography — Geist only
+- `--font-family-sans`: **`"Geist"`**
+- `--font-family-mono`: **`"Geist Mono"`**
+**No Inter, no system stacks.** Geist + Geist Mono only.
+Size scale: `display` 36, `h1` 30, `h2` 24, `h3` 20, `h4` 18, `body-lg` 16, `body` 14, `body-sm` 13, `caption` 11, `overline` 10.
+## Radii
+`--radius` (base) 8px. Scale: `radius-sm` 4, `radius-md` 6, `radius-lg` 8, `radius-xl` 12, `radius-2xl` 16, `radius-3xl` 20, `radius-4xl` 24, `radius-full` 9999.
+## Spacing
+`xs` 4, `sm` 8, `md` 12, `lg` 16, `xl` 24, `2xl` 32, `3xl` 48, `4xl` 64 (px). Use the named tokens, not raw px values, so consumer overrides flow through.
+## Anti-patterns
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| `bg-primary` for a primary CTA | `--primary` flips to pale brand-100 in dark — washed-out CTAs | `bg-brand-500 text-white` (constant) |
+| Generic gray neutrals (Tailwind `gray-*`) | Medal is zinc-aligned, not cool gray | Use `neutral-*` from the ramp |
+| `--primary` mapped to brand-500 | Lib has primary as brand-800 light / brand-100 dark | Map exactly — light=brand-800, dark=brand-100 |
+| Treating `--accent` as a brand color | `--accent` is neutral by contract | Use `brand-*` tokens directly |
+| Hard-coded `ring-blue-500` for focus rings | Focus rings are brand-keyed via `--ring` | `focus-visible:ring-2 focus-visible:ring-ring` |
+| Picking chart colors ad-hoc per app | Loses cross-consumer parity | Cycle `--chart-1`..`--chart-5` in order |
+| Adding Inter or system fonts | Canonical is Geist + Geist Mono | Stick to the two families |
+| `success` as green | Canonical success is teal | Use the teal scale |
+| `[...].join(' ')` for classNames | Noisy, error-prone | Use a consumer-owned `cn()` helper — see the `components` skill |
+| Raw px (e.g. `pt-[12px]`) for spacing | Bypasses consumer overrides | Use the named spacing tokens |

package/skills/components/SKILL.md ADDED Viewed

@@ -0,0 +1,196 @@
+---
+name: components
+description: Use when implementing a UI component in any app consuming `@medalsocial/meda` — building a card, dialog, status pill, empty state, dropdown, tooltip — or picking a primitive vs a shadcn-style adapter vs a domain folder. Required reading before generating any new visual code; the `meda-storybook` MCP server is the source of truth for what already exists.
+---
+# Meda Components
+## When to load this skill
+- About to author or modify a React component that renders UI.
+- Choosing where a new component lives (primitive / ui-adapter / domain / recipe).
+- Composing `Card`, `EmptyState`, `StatusPill`, or another exported primitive.
+- Picking between primitives and shadcn-style ui adapters.
+- Writing or updating a `*.stories.tsx`.
+- Importing `MarkdownView` or another optional-peer-deps component.
+## Look up first, generate second
+**Before writing any new visual component, query the `meda-storybook` MCP server.** It exposes the running Storybook (`pnpm storybook` on `http://localhost:6006`) and is the authoritative index of what already exists. Many "new" components are existing primitives composed differently.
+If the MCP is not running, start it:
+```bash
+pnpm storybook
+```
+The MCP is registered in `.mcp.json`.
+## Where things live
+| Folder | What it is |
+|---|---|
+| `src/primitives/` | Standalone visual building blocks. Each owns its own styling. |
+| `src/components/ui/` | shadcn-style adapters that wrap `@base-ui/react`. |
+| `src/shell/` | Layout regions — see the `shell` skill. |
+| `src/{chat,kanban,calendar,timeline,marketing,workflow-builder,...}/` | Domain folders for higher-level composed surfaces. |
+| `src/recipes/` | Framework-specific glue (e.g. `recipes/next.ts`). |
+| `src/lib/` | Shared utilities (`cn()`, etc.). |
+**Don't invent a new top-level layer** (primitives/ui/recipes). Adding a new *domain* folder for a real product area is fine; check with a maintainer first if uncertain.
+## Primitive vs ui-adapter vs domain — picking where to add
+| If you need… | Reach for | Example |
+|---|---|---|
+| A self-contained visual element with no behavior dependency | `src/primitives/` | `Card`, `StatusPill`, `EmptyState`, `Skeleton`, `FilterRail` |
+| An overlay / menu / form control wrapping `@base-ui/react` | `src/components/ui/` | `DropdownMenu`, `Dialog`, `Drawer`, `Tooltip`, `Command`, `Checkbox`, `Collapsible` |
+| A composed surface tied to a product area | A domain folder | A chat thread (`src/chat/`), a kanban column (`src/kanban/`) |
+| Framework-specific glue | `src/recipes/` | `recipes/next.ts` |
+## Primitives layer
+**`@base-ui/react` is the canonical primitives layer.** Forbidden in new code: `@radix-ui/*` packages. shadcn-style adapters in `src/components/ui/` wrap `@base-ui/react` — follow the existing patterns in `dropdown-menu.tsx` / `tooltip.tsx`.
+## Card — compound component
+```tsx
+import { Card } from '@medalsocial/meda';
+<Card>
+  <Card.Header>
+    <h3 className="text-h4">Workspace usage</h3>
+  </Card.Header>
+  <Card.Body>
+    Body content here.
+  </Card.Body>
+  <Card.Footer>
+    <Button variant="ghost">Cancel</Button>
+    <Button>Save</Button>
+  </Card.Footer>
+</Card>
+```
+`Card`, `Card.Header`, `Card.Body`, `Card.Footer` are all `<div>`-typed and accept any standard div props. The header/footer auto-hide their borders when adjacent to the body (`last:border-b-0` / `first:border-t-0`), so a header-only or body-only card has no orphan border. Always use the subcomponents — don't reach into the card with raw padded `<div>`s.
+## EmptyState — variants matter
+```tsx
+import { EmptyState } from '@medalsocial/meda';
+import { Inbox } from 'lucide-react';
+<EmptyState
+  icon={Inbox}
+  title="No messages yet"
+  description="When someone messages your workspace, it'll show up here."
+  action={<Button>Invite teammates</Button>}
+  variant="panel"
+/>
+```
+Variants:
+- `'default'` — full-page empty state, generous vertical spacing.
+- `'panel'` — panel-sized empty state (e.g. inside a right panel or card).
+- `'inline'` — compact, for list-row or table-row empty states.
+The `icon` prop accepts a Lucide component (`Inbox`) OR a rendered element (custom inline SVG). Lucide components are auto-sized; rendered elements are placed in an `inline-flex` span and you control their size.
+## StatusPill — solid tones, two sizes
+```tsx
+import { StatusPill } from '@medalsocial/meda';
+<StatusPill tone="success">Synced</StatusPill>
+<StatusPill tone="warning" size="md">Action required</StatusPill>
+<StatusPill tone="danger" dot={false}>Failed</StatusPill>
+```
+- `tone`: `'neutral' | 'info' | 'success' | 'warning' | 'danger'`
+- `size`: `'sm'` (default, 11px text) or `'md'` (12px text)
+- `dot`: `true` (default) to show a leading dot
+**Why solid backgrounds (not tinted):** the 11px small size needs ≥4.5:1 contrast to pass WCAG AA. Tinted backgrounds (`bg-info/15 text-info`) fail axe gates at this size. Solid `bg-info text-info-foreground` etc. always passes via the theme tokens. If you need a tinted variant, use it at `size="md"` or larger only, and verify with `vitest-axe`.
+## ui-adapters — NOT exported from the npm package
+shadcn-style adapters in `src/components/ui/` (`Dialog`, `DropdownMenu`, `Tooltip`, `Drawer`, `Command`, `Checkbox`, `Collapsible`) wrap `@base-ui/react`. **They are intentionally NOT exported from `@medalsocial/meda`** — meda follows the shadcn philosophy: you own the ui code.
+Two supported ways to consume them:
+1. **Vendor via the meda shadcn registry** (recommended for shell-consistent apps). meda publishes a registry at `https://meda.medalsocial.com/r/...` — install via the shadcn CLI:
+   ```bash
+   npx shadcn@latest add https://meda.medalsocial.com/r/<component>.json
+   ```
+   The components land in your app's `@/ui` folder (configurable via your `components.json` aliases). You own and can modify the code.
+2. **Write your own wrapping `@base-ui/react` directly.** When you need a primitive meda doesn't provide a recipe for, follow the patterns visible in meda's `src/components/ui/dropdown-menu.tsx` / `tooltip.tsx` and ship the result in your own `@/ui` folder.
+Do NOT try `import { Dialog } from '@medalsocial/meda'` — it will fail with a missing-export error.
+## Optional peer dependencies — MarkdownView pattern
+`MarkdownView` has optional peers (`react-markdown`, `remark-gfm`, `rehype-highlight`). It is **intentionally not re-exported from `src/primitives/index.ts`** — even type re-exports cause TS to follow the chain and break consumers who haven't installed the peers. Import via the dedicated subpath:
+```ts
+import { MarkdownView, type MarkdownViewProps } from '@medalsocial/meda/markdown-view';
+```
+When you add another optional-peer component, follow this pattern: own subpath, no root re-export, peers declared as `peerDependenciesMeta.*.optional`.
+## Storybook discipline
+**Every exported component has a `*.stories.tsx`.** New components without stories fail review.
+Stories live next to the component (`card.tsx` + `card.stories.tsx`). Use the `__stories__/` folder only for cross-component demos (full shell stories, theme-switcher demos).
+Visual snapshots run through Chromatic on every PR.
+## Icons
+**Lucide React only.** No other icon libraries in new code. Never use emojis as UI icons. Custom-drawn icons require explicit review.
+Shell sizes: 22px (rails), 16px (header), 14px (inline). Inside primitives like `EmptyState`, the icon auto-sizes to match the variant.
+## className composition
+Do not use `[...].join(' ')` or template-string concatenation for classes — noisy, merge-unsafe.
+meda uses a `cn()` helper internally (`src/lib/utils.ts`) built from `clsx` + `tailwind-merge`, but it is **not exported from the package**. In consumer apps, declare your own — first install the two deps explicitly (don't rely on them being transitive — that's not safe under pnpm strict, Yarn PnP, or any layout that hides un-declared dependencies):
+```bash
+pnpm add clsx tailwind-merge
+```
+```ts
+// your-app/src/lib/utils.ts
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+```
+```tsx
+import { cn } from '@/lib/utils';
+<div className={cn('base classes', isActive && 'active', className)} />
+```
+## Anti-patterns
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| Generating UI without checking Storybook first | Duplicates existing primitives | Query `meda-storybook` MCP first |
+| `@radix-ui/*` in new code | Deprecated primitives layer | Wrap `@base-ui/react` in `src/components/ui/` |
+| Re-exporting `MarkdownView` from root | Breaks consumers without optional peers | Import from `@medalsocial/meda/markdown-view` |
+| Tinted `StatusPill` at `size="sm"` | Fails WCAG AA at 11px (vitest-axe gate) | Use solid tones at `sm`; tints only at `md`+ with a11y verification |
+| Raw `<div>` inside `<Card>` with custom padding | Bypasses border-collapse logic; off-grid spacing | Use `Card.Header` / `Card.Body` / `Card.Footer` |
+| `import { Dialog } from '@medalsocial/meda'` | Not exported — meda follows the shadcn "you own the ui" model | Vendor via `npx shadcn@latest add https://meda.medalsocial.com/r/...` or write your own wrapping `@base-ui/react` |
+| `import { cn } from '@medalsocial/meda'` | Not exported | Declare your own three-line `cn()` using `clsx` + `tailwind-merge` (already transitive) |
+| Adding emojis as UI icons | Inconsistent sizing + brand | Use Lucide equivalents (`Clock`, `Check`, `AlertTriangle`) |
+| Inventing a new top-level layer folder | Loses the established taxonomy | Use primitives / ui / domain / recipes |
+| Skipping `*.stories.tsx` for an exported component | Breaks the lookup-first discipline for the next contributor | Always ship a story |
+| `[...].join(' ')` for classes | Error-prone | Use `cn()` |

package/skills/shell/SKILL.md ADDED Viewed

@@ -0,0 +1,151 @@
+---
+name: shell
+description: Use when scaffolding or modifying shell regions (icon rail, context rail, header, panel, command palette) in any app consuming `@medalsocial/meda` — Picasso, pilot-talk, NextMedal, apps/web. Required reading before adding a rail item, picking an AppShell variant (auth/workspace/chat), wiring command palette actions, configuring `MedaShellProvider`, or any `IconRail` change.
+---
+# Meda Shell
+## When to load this skill
+- Scaffolding a new shell — picking `AppShell` variant and configuring `MedaShellProvider`.
+- Adding/removing/reordering icon rail items.
+- Registering command palette actions.
+- Wiring the workspace switcher or theme toggle in the header.
+- Building or modifying the right panel.
+- Touching anything under `src/shell/` in `@medalsocial/meda`.
+## App shell variants
+The package exports a single `<AppShell>` component with a discriminated `variant` prop. Pick exactly one variant per route group:
+| Variant | When to use | Key config |
+|---|---|---|
+| `'auth'` | Sign-in / sign-up / password reset / OAuth callbacks. Lets the form scroll past viewport (dense forms, high zoom). | `auth`, `branding`, optional `preview` (right-side art) + `actions` (top-right) |
+| `'workspace'` | Logged-in product shell. Has icon rail + context rail + header + main + optional right panel. | `iconRail`, `contextRail`, `rightPanel`, `workspace` (menu items override), `appTabs` (router integration), `headerCenter`, `banners`, `mainLayout`, `globalActions` |
+| `'chat'` | Chat-first surfaces (full-bleed messaging UI; no rails). | `globalActions` |
+`AppShellWorkspace.workspace.menuItems` REPLACES the default workspace dropdown ("Manage workspaces / Settings / Profile / Sign out") when provided. **The theme toggle is preserved automatically** — consumers do not have to re-implement theme cycling.
+## MedaShellProvider — the runtime root
+Wrap your app once with `<MedaShellProvider>` (typically in the root layout). Props:
+```ts
+interface MedaShellProviderProps {
+  workspace: WorkspaceDefinition;                                 // required
+  workspaces?: WorkspaceDefinition[];                             // for the switcher
+  apps: AppDefinition[];                                          // required, non-empty (throws if empty)
+  defaultActiveApp?: string;                                      // app id; defaults to apps[0]
+  storage?: ShellStorageAdapter;                                  // defaults to localStorage adapter
+  mobileBottomNav?: MobileBottomNavItem[];                        // mobile nav config
+  commandPaletteHotkey?: string;                                  // e.g. 'mod+k' (default)
+  themeAdapter?: 'default' | 'next-themes' | ThemeAdapter;        // pick per-framework
+  children: ReactNode;
+}
+```
+- **`themeAdapter: 'next-themes'`** for Next.js apps using `next-themes`. The adapter is lazy-loaded so default-adapter consumers don't pay for the bridge.
+- **`themeAdapter: 'default'`** uses the built-in adapter (no external dep).
+- Pass a custom `ThemeAdapter` object to integrate with any other theme system.
+- `apps` MUST have at least one entry — the provider throws on empty array.
+## Regions and component map
+| Region | Component | Source |
+|---|---|---|
+| Icon rail | `IconRail` | `src/shell/icon-rail.tsx` |
+| Context rail | `ContextRail` | `src/shell/context-rail.tsx` |
+| Header | `ShellHeader` + `WorkspaceSwitcher` | `src/shell/shell-header.tsx` |
+| Main | `ShellMain` | `src/shell/shell-main.tsx` |
+| Right panel | `RightPanel` | `src/shell/right-panel.tsx` |
+| Command palette | `CommandPalette` + `CommandRegistryContext` | `src/shell/command-palette.tsx` |
+## The flat-rail rule (critical)
+**The `IconRail` is a flat list of equal-weight icons. No section headers, no per-group labels, no in-line dividers between groups.**
+`IconRail` accepts `mainItems`, `utilityItems`, and a `footer`. Use those three slots — do NOT inject section labels or dividers via `renderLink`, custom items, or a wrapping component.
+**Why:** A "Testing" divider above Journeys was specced and built three different ways in 2026-05 (renderLink-injected, a real `IconRailDivider` API in meda, and a consumer `pnpm patch`). All three were abandoned — meda PR #161 and labs PR #162 were closed unmerged; labs PR #163 removed the work. The icon-button slot is 44×44; anything wider overflows and overlaps the next icon, and an icon-only ~60px rail cannot host a text label legibly. **Do not re-propose dividers, group headers, or "mark this surface as testing/ops" rail treatments.**
+If a surface needs a type indicator, it lives in the surface itself (a banner, a header pill, a column-header badge) — never in the icon rail.
+The existing `RailDivider` in `icon-rail.tsx` is a different pattern: a chevron toggle that **repositions** utility items between top and bottom of the rail. It is spatial, not a group label. Do not generalize it into section headers.
+## IconRail item shape + active styling
+```ts
+interface IconRailItem {
+  id: string;
+  label: string;          // shown only in tooltip, never inline
+  icon: LucideIcon;       // Lucide React only — no other icon libs
+  to: string;
+  badge?: ReactNode;      // small status indicator, top-right of the slot
+}
+```
+Slot is `h-11 w-11 rounded-xl`. Active state uses `bg-primary/12 text-primary` (a 12%-alpha brand tint, NOT a solid brand fill — this is the legitimate `bg-primary` use case from the `brand` skill's note). Inactive uses `text-muted-foreground hover:bg-accent hover:text-foreground`. Don't override unless you're consciously diverging.
+Pass `activeId` to mark which item is active; usually derived from your router's current path.
+## `renderLink` — when to use it
+`IconRail` and other rail components accept a `renderLink` prop that wraps the default `<a>`:
+```tsx
+renderLink={({ item, isActive, className, children, linkProps }) => (
+  <NextLink href={item.to} className={className} {...linkProps}>
+    {children}
+  </NextLink>
+)}
+```
+**Use it for:** integrating with Next.js `Link`, TanStack Router, React Router — anything that needs client-side navigation hooks.
+**Do NOT use it for:** injecting dividers, headers, badges outside the slot, or any non-link content (see the flat-rail rule). The `className` parameter constrains your wrapper to the 44×44 slot — non-link content overflows.
+## Command palette
+`CommandPalette` is registry-driven. Components register their commands via the **public hooks** `useCommands` and `useCommandGroup` from `@medalsocial/meda/shell` — both must run inside a `<CommandPalette>` (they throw otherwise).
+```tsx
+import { useCommands, useCommandGroup } from '@medalsocial/meda/shell';
+function MyFeature() {
+  // Optional: register the group first so its label + ordering are known.
+  useCommandGroup({ id: 'tools', label: 'Tools', priority: 50 });
+  useCommands([
+    { id: 'my.action', label: 'Run my action', group: 'tools', run: () => doIt() },
+  ]);
+  return null; // or your real UI
+}
+```
+Each hook auto-handles register-on-mount and unregister-on-unmount via `useEffect`. Lower `priority` numbers render the group earlier (default 100).
+`CommandRegistryContext` is internal — don't import or `useContext` it directly. The hooks are the supported API.
+The default palette hotkey is `'mod+k'` — override via `MedaShellProvider.commandPaletteHotkey`. Hotkey matching is strict modifier-aware: `'mod+k'` does NOT fire on `mod+shift+k`. Use `'mod'` (resolves to ⌘ on macOS, Ctrl on Windows/Linux), not platform-specific keywords.
+## Right panel patterns
+Use a single `RightPanel` per shell. Don't build a parallel right-side surface — multiple right panels create state and dismiss-behavior conflicts. For a stacked detail experience, register multiple `PanelView`s with the existing `PanelViewsProvider` (`src/shell/panel-views-provider.tsx`).
+## Drag patterns
+`RailDropSlot`, `RailDropZones`, `DragModeBanner` are the canonical drag patterns. Don't add custom drag handlers to the rail — use these so the visual + a11y behavior matches across consumers.
+## Anti-patterns
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| Adding a section divider/header to `IconRail` | Three prior attempts abandoned; slot geometry can't host labels | Keep the rail flat; put type indicators in surfaces |
+| Using `renderLink` for non-link content | Wraps inside the 44×44 slot — overflows/overlaps | Use `mainItems` / `utilityItems` / `footer` only |
+| Picking `'workspace'` variant on a sign-in route | Renders rails on routes with no app context | Use `'auth'` variant; switch to `'workspace'` after auth |
+| Re-implementing the theme toggle when overriding `workspace.menuItems` | The package inserts the toggle automatically | Just ship your menu items; toggle is added between items and footer |
+| Custom icon library | Inconsistent sizing + brand tone | Lucide React only |
+| Multiple `RightPanel`s in one shell | Dismiss/state conflicts | Use `PanelViewsProvider` for stacked detail |
+| Forking `MedaShellProvider` per app | Loses cross-consumer parity | Compose around it; pass a custom `ThemeAdapter` for theme integration |
+| Hard-coded modifier in hotkey strings (`'cmd+k'`) | Breaks on Windows/Linux | Use `'mod+k'` — resolves per-platform |