@medalsocial/meda 2.4.1 → 2.5.0

package/dist/shell/shell-header.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { ChevronDown, Monitor, Moon, PanelRightClose, PanelRightOpen, Sun } from 'lucide-react';
+import { ChevronDown, Monitor, Moon, PanelRight, Sun } from 'lucide-react';
 import { createElement, Fragment, isValidElement } from 'react';
 import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, } from '../components/ui/dropdown-menu.js';
 import { cn } from '../lib/utils.js';
@@ -57,7 +57,7 @@ export function WorkspaceSwitcher({ menuItems, menuFooter, workspaceMenuFooter,
     const { workspace, workspaces } = useMedaShell();
     const resolvedFooter = menuFooter ?? workspaceMenuFooter;
     const useConfiguredItems = Array.isArray(menuItems);
-    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "shrink-0", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { children: workspace.name }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[200px]", children: [workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && _jsx("span", { "aria-hidden": "true", children: ws.icon }), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), useConfiguredItems ? (menuItems.map((item) => (_jsxs(Fragment, { children: [renderConfiguredItem(item), item.separatorAfter && _jsx(DropdownMenuSeparator, {})] }, item.id)))) : (_jsxs(_Fragment, { children: [_jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" })] })), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), !useConfiguredItems && (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" })] })), resolvedFooter] })] }));
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", className: "flex min-w-0 items-center gap-2.5 rounded-lg px-2.5 py-2 text-sm font-semibold hover:bg-accent" }), children: [workspace.icon != null && (_jsx("span", { className: "inline-flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted text-foreground ring-1 ring-border/70", "aria-hidden": "true", children: workspace.icon })), _jsx("span", { className: "max-w-[13rem] truncate", children: workspace.name }), _jsx(ChevronDown, { size: 16, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { className: "min-w-[240px]", children: [!useConfiguredItems && workspaces.length > 0 && (_jsxs(_Fragment, { children: [workspaces.map((ws) => (_jsxs(DropdownMenuItem, { children: [ws.icon != null && (_jsx("span", { className: "inline-flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-md bg-muted text-foreground ring-1 ring-border/70", "aria-hidden": "true", children: ws.icon })), ws.name] }, ws.id))), _jsx(DropdownMenuSeparator, {})] })), useConfiguredItems ? (menuItems.map((item) => (_jsxs(Fragment, { children: [renderConfiguredItem(item), item.separatorAfter && _jsx(DropdownMenuSeparator, {})] }, item.id)))) : (_jsxs(_Fragment, { children: [_jsx(DropdownMenuItem, { children: "Manage workspaces" }), _jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Settings" }), _jsx(DropdownMenuItem, { children: "Profile" })] })), _jsx(DropdownMenuSeparator, {}), _jsx(ThemeToggleMenuItem, {}), !useConfiguredItems && (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuItem, { children: "Sign out" })] })), resolvedFooter] })] }));
 }
 /* v8 ignore next — v8 phantom duplicate function record for AppTabs (default params) */
 export function AppTabs({ renderLink } = {}) {
@@ -91,21 +91,42 @@ export function AppTabs({ renderLink } = {}) {
                 onMouseEnter: () => undefined, className: className, children: children }, app.id));
         }) }));
 }
-// ---------------------------------------------------------------------------
-// PanelToggle
-// ---------------------------------------------------------------------------
-export function PanelToggle() {
+export function PanelToggle({ panelViews = [] } = {}) {
     const { panel } = useMedaShell();
     const isOpen = panel.mode !== 'closed';
-    const handleClick = () => {
-        panel.setMode(isOpen ? 'closed' : 'panel');
+    // No registered views → a single button that just opens/closes the panel.
+    if (panelViews.length === 0) {
+        return (_jsx("button", { type: "button", "aria-label": isOpen ? 'Close right panel' : 'Open right panel', "aria-pressed": isOpen, onClick: () => panel.setMode(isOpen ? 'closed' : 'panel'), className: cn('inline-flex h-9 items-center gap-1.5 rounded-[10px] bg-accent px-2.5 text-muted-foreground transition-colors hover:text-foreground', isOpen && 'text-foreground'), children: _jsx(PanelRight, { size: 18, "aria-hidden": "true" }) }));
+    }
+    // Clicking a view toggles it: selecting the already-open view closes the
+    // panel; selecting any other view opens the panel focused on that view.
+    const handleSelect = (viewId) => {
+        if (isOpen && panel.activeView === viewId) {
+            panel.close();
+        }
+        else {
+            panel.focus(viewId);
+        }
     };
-    return (_jsx("button", { type: "button", "aria-label": isOpen ? 'Close right panel' : 'Open right panel', onClick: handleClick, className: cn('inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors', isOpen ? 'bg-accent text-accent-foreground' : 'text-muted-foreground hover:bg-accent'), children: isOpen ? (_jsx(PanelRightClose, { size: 18, "aria-hidden": "true" })) : (_jsx(PanelRightOpen, { size: 18, "aria-hidden": "true" })) }));
+    // ONE grouped control: the whole pill (panel icon + chevron) is a single
+    // dropdown trigger — not two separate buttons.
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { render: _jsx("button", { type: "button", "aria-label": "Right panel views", className: cn('inline-flex h-9 items-center gap-1.5 rounded-[10px] bg-accent px-2.5 text-muted-foreground transition-colors hover:text-foreground data-[popup-open]:text-foreground', isOpen && 'text-foreground') }), children: [_jsx(PanelRight, { size: 18, "aria-hidden": "true" }), _jsx(ChevronDown, { size: 14, "aria-hidden": "true" })] }), _jsxs(DropdownMenuContent, { align: "end", sideOffset: 8, className: "w-64 rounded-xl p-1.5", children: [_jsx("div", { className: "px-2 pt-1.5 pb-1 font-bold text-[10.5px] uppercase tracking-wider text-muted-foreground", children: "Panel views" }), panelViews.map((view) => {
+                        const Icon = view.icon;
+                        const active = isOpen && panel.activeView === view.id;
+                        return (_jsxs(DropdownMenuItem, { onClick: () => handleSelect(view.id), className: cn('gap-2.5 rounded-[9px] px-2.5 py-2 text-sm', active && 'text-foreground'), children: [_jsx("span", { className: cn('grid h-[26px] w-[26px] shrink-0 place-items-center rounded-[7px] transition-colors', active ? 'bg-primary/15 text-primary' : 'bg-muted text-muted-foreground'), children: Icon != null ? _jsx(Icon, { size: 16, "aria-hidden": "true" }) : null }), _jsx("span", { className: "flex-1 font-medium", children: view.label }), active ? _jsx("span", { className: "size-1.5 rounded-full bg-primary" }) : null] }, view.id));
+                    })] })] }));
 }
 /* v8 ignore next — v8 phantom duplicate function record for ShellHeader (default params) */
-export function ShellHeader({ globalActions, headerCenter, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, } = {}) {
+export function ShellHeader({ globalActions, headerCenter, headerLeading, appTabsRenderLink, className, workspaceMenuItems, workspaceMenuFooter, showPanelToggle = true, panelViews = [], } = {}) {
     const band = useShellViewport();
     if (band === 'mobile')
         return null;
-    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'gap-3 border-b border-border bg-background px-3', className), children: [_jsx("div", { className: "flex shrink-0 items-center", children: _jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }) }), _jsx("div", { className: "flex min-w-0 flex-1 items-center", children: headerCenter !== undefined ? headerCenter : _jsx(AppTabs, { renderLink: appTabsRenderLink }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [globalActions, _jsx(PanelToggle, {})] })] }));
+    // Leading content (e.g. section tabs) sits in the LEFT region just after
+    // the WorkspaceSwitcher — separated by whitespace only (no divider line),
+    // matching the design prototype's topbar spacing.
+    const leadingRegion = headerLeading != null ? (_jsx("div", { className: "ml-2 flex min-w-0 items-center", children: headerLeading })) : null;
+    if (headerCenter !== undefined) {
+        return (_jsxs("header", { className: cn('grid h-[var(--shell-header-height)] w-full grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2 justify-self-start", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 items-center justify-center justify-self-center", children: headerCenter }), _jsxs("div", { className: "flex min-w-0 items-center justify-end gap-2 justify-self-end", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
+    }
+    return (_jsxs("header", { className: cn('flex h-[var(--shell-header-height)] w-full items-center justify-between', 'gap-4 bg-background px-4', className), children: [_jsxs("div", { className: "flex min-w-0 shrink-0 items-center gap-2", children: [_jsx(WorkspaceSwitcher, { menuItems: workspaceMenuItems, menuFooter: workspaceMenuFooter }), leadingRegion] }), _jsx("div", { className: "flex min-w-0 flex-1 items-center", children: _jsx(AppTabs, { renderLink: appTabsRenderLink }) }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [globalActions, showPanelToggle && _jsx(PanelToggle, { panelViews: panelViews })] })] }));
 }

package/dist/shell/shell-main.js

@@ -7,5 +7,5 @@ const layoutClass = {
     fullbleed: 'w-full',
 };
 export function ShellMain({ layout = 'workspace', className, children }) {
-    return (_jsx("main", { "data-meda-shell-main-layout": layout, className: cn('flex-1 min-w-0 overflow-y-auto bg-shell-main', '[content-visibility:auto]', layoutClass[layout], className), children: children }));
+    return (_jsx("main", { "data-meda-shell-main-layout": layout, className: cn('flex-1 min-w-0 overflow-y-auto bg-shell-main', layoutClass[layout], className), children: children }));
 }

package/dist/shell/types.d.ts

@@ -99,12 +99,14 @@ export interface AppShellIconRailConfig {
     footer?: ReactNode;
     activeId?: string;
     renderLink?: import('./icon-rail.js').IconRailProps['renderLink'];
+    labelVisibility?: import('./icon-rail.js').IconRailProps['labelVisibility'];
 }
 /** ContextRail configuration for `<AppShell variant="workspace">`. */
 export interface AppShellContextRailConfig {
     appId: string;
     module: ContextModule;
     activeItemId?: string;
+    renderLink?: import('./context-rail.js').ContextRailProps['renderLink'];
     header?: ContextRailHeader;
     scroll?: ContextRailScroll;
 }

package/dist/styles/theme.css

@@ -1,4 +1,5 @@
 @import "./tokens.css";
+@import "@xyflow/react/dist/style.css";
 
 /* Tell Tailwind v4 to scan meda's compiled component output so utilities
    like `h-full`, `mt-auto`, `py-3.5`, and `bg-shell-rail` (used by IconRail,

package/dist/styles/tokens.css

@@ -236,8 +236,10 @@
   --shell-panel: var(--color-neutral-50);
   --shell-border: var(--color-neutral-200);
   --shell-shadow: 0 4px 12px hsl(0 0% 0% / 0.04);
-  --shell-header-height: 56px;
+  --shell-header-height: 64px;
+  --shell-mobile-header-height: 48px;
   --shell-rail-width: 60px;
+  --shell-rail-label-width: 88px;
   --shell-context-default: 300px;
   --shell-context-min: 240px;
   --shell-context-max: 420px;

package/dist/workflow-builder/workflow-canvas.d.ts

@@ -1,5 +1,4 @@
 import { type Connection, type EdgeChange, type NodeChange, type ReactFlowProps } from '@xyflow/react';
-import '@xyflow/react/dist/style.css';
 import type { WorkflowEdge, WorkflowNode } from './types.js';
 export interface WorkflowCanvasProps {
     nodes: WorkflowNode[];

package/dist/workflow-builder/workflow-canvas.js

@@ -1,7 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Background, BackgroundVariant, Controls, ReactFlow, } from '@xyflow/react';
-import '@xyflow/react/dist/style.css';
 import { useCallback } from 'react';
 import { cn } from '../lib/utils.js';
 import { workflowEdgeTypes } from './edges/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/meda",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "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

@@ -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

@@ -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()` |