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