## What are patterns

Patterns are two things simultaneously: shell elements (web components that coordinate multiple child regions) and composition recipes (documented HTML structures that show how to assemble primitives for a specific problem).

Shell elements (`admin-shell`, `chat-shell`, `editor-shell`) stamp no markup — they orchestrate behaviors CSS alone cannot: resize observers, keyboard routing, panel toggling, state sync. You author the HTML; the pattern wires the JavaScript. Composition recipes are documented in the /site/patterns/ pages and serve as copy-paste starting points.

## Decision matrix

Start here. Find your intent, go straight to the pattern.

I need to build… | Pattern
--- | ---
App Shells
A full admin SaaS app (sidebar + topbar + content + statusbar) | admin-shell
A chat interface with history, input, and streaming responses | chat-shell
A design-tool shell (canvas + navigator + inspector panes) | editor-shell
A sidebar that collapses to a drawer at narrow viewports | responsive-shell-sidebar
App navigation: sidebar rail, grouped nav, sub-nav, collapsible | app-nav
Data & Tables
A data table with inline editing and tree/expand rows | data-tables-inline-edit-and-tree
A kanban board with draggable cards and column swim lanes | kanban-board
Bulk actions toolbar for selected rows (delete, export, move) | bulk-action-toolbar
A filter bar above a list or table (multi-facet, chips, clear-all) | filter-bar
Search with result previews, categories, recent, and suggestions | search-discovery
A chart embedded inside a card (KPI, sparkline, summary) | chart-in-card
A conversion funnel visualization | conversion-funnel
A retention / cohort heatmap | retention-cohort
Forms & Wizards
A form layout (field groups, sections, submit/cancel footer) | form-system
A form inside a drawer (side panel form, quick-edit) | form-drawer
Conditional form fields, dependent selects, autocomplete inputs | forms-conditional-and-autocomplete
A multi-step wizard or onboarding flow in a drawer | wizard-drawer
Permissions & Access
A permissions grid (role × resource matrix) | permissions-matrix
A role picker (assign roles to users) | permissions-role-picker
Sharing / collaborator management (invite, revoke, change level) | permissions-sharing
Access requests (request → review → approve / deny flow) | access-requests
API key management + data export controls | admin-keys-and-export
Records & Review
A record detail view in a side drawer | record-detail-drawer
An approval workflow (request → reviewers → decision) | approvals
A diff view (code or content before/after comparison) | diff-review
Comments, mentions, threaded replies, reactions | comments-and-collaboration
A public profile page with verification badges | profile-public-and-verification
AI & Agent Surfaces
Display LLM token usage and cost per request | agent-cost
Show the agent's memory / context window state | agent-memory
A prompt library with save, search, and insert | agent-prompt-library
Display tool calls the agent made (name, args, result) | agent-tool-call
Communication & Notifications
Notification bell with badge + dropdown digest | notifications-bell-and-digest
System-wide banners (announcements, maintenance, warnings) | system-banners
Marketing & Public
Marketing sections (hero, pricing, CTA, testimonials) | marketing-engagement

## Pattern vs Component

| Component | Pattern
--- | --- | ---
Renders UI | Yes — light DOM, `@scope`-isolated CSS, slots | Shell elements orchestrate author-supplied HTML; composition recipes are documented starting points
Scope | Single element | Coordinates multiple elements via slots and `data-*` roles
Examples | `button-ui`, `card-ui`, `modal-ui` | `admin-shell`, `kanban-board` recipe, `permissions-matrix` recipe
Customization | Attributes, slots, CSS custom properties | HTML structure, `data-*` region markers, slot vocabulary

## Using a shell pattern

Shell elements stamp no HTML — you author the structure; the element wires the behavior.

<admin-shell mode="rounded"> <admin-sidebar slot="leading" resizable collapsible> <admin-topbar slot="header"> <span slot="heading">My App</span> </admin-topbar> <section-ui> <nav-ui> <nav-item-ui icon="house" text="Dashboard" selected></nav-item-ui> <nav-item-ui icon="gear" text="Settings"></nav-item-ui> </nav-ui> </section-ui> </admin-sidebar> <admin-content> <admin-topbar> <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost" size="sm"></button-ui> <breadcrumb-ui><span>Dashboard</span></breadcrumb-ui> </admin-topbar> <admin-scroll> <admin-page> <admin-page-header> <header><div><h1>Dashboard</h1></div></header> </admin-page-header> <admin-page-body> <section><!-- page content --></section> </admin-page-body> </admin-page> </admin-scroll> </admin-content> </admin-shell>