create-ailk 0.1.0 → 0.2.0

package/component-catalog.md

@@ -0,0 +1,456 @@
+# AILK component catalog — search by capability, not by name
+
+<!-- GENERATED FILE — do not hand-edit. Regenerate with `pnpm --filter create-ailk run build-catalog`. -->
+
+The component inventory of `@working-theory/ui` and the shells of `@working-theory/templates` — the library an AI Launch Kit site is built from. It exists because a name search fails: a site rebuilt five components AILK already had, because it searched for the names IT would have used and AILK uses different ones — `ContactOverlay`→`FormLightbox`, `SearchOverlay`→`SpotlightPanel`/`NavSearchTrigger`, `SiteRail`→`SidebarNav`, `FunnelNav`→`Nav`, `NumberedWorkList`→`Steps`/`StairSteps`.
+
+**What this file does NOT cover.** All six component tiers are indexed — Sections, Blocks, Chrome, Primitives, Panels and Shells — so a component absent from these tables is genuinely absent from the library. Outside the file: the **design tokens** (tier 0 — colors, spacing, typography, radius and the rest are values in `@working-theory/theme`, not components; `packages/ui/src/tokens/` holds their Storybook stories and the small display components those stories use); the **page compositions** in `packages/ui/src/pages/` and `packages/templates/src/pages/`, which assemble whole pages from the tiers below; and every non-component module (hooks, `utils/`, `.ts` helpers).
+
+**Two things a listing does not promise.** First, the tables index every component file in the six tiers, **including the paid module slices** — the `Booker` family is here, and a build with the scheduling module switched off will not contain it. Listed is not the same as present in your tree; check the modules your site was scaffolded with. Second, this file carries no **props or data shapes**: it says what a component is FOR, never what it accepts. For a section's accepted `data` fields, read its Zod schema, or the `component-catalog.json` manifest the AILK source repo generates alongside this file.
+
+**Before you build a component, search this file for what it DOES.**
+
+1. Read **Find by capability** below — it maps the words people actually type to the names AILK uses.
+2. If nothing matches, grep the per-tier tables for a verb or noun from your requirement (`grep -i backdrop`, `grep -i "multi-step"`), not for your working name for the component.
+3. Check the Primitives, Panels and Shells tables too — a low-level control, a collapsible layout container, or a route-level frame lives there, not under Sections or Blocks.
+4. Only then build. If you do build, you are declaring the capability is genuinely absent.
+
+Inventory: **286 component files** across 6 tiers — 59 sections, 115 blocks, 18 chrome, 79 primitives, 7 panels, 8 shells. 283 distinct names: `SchedulerEmbed`, `Separator`, `Tabs` exist in more than one tier as genuinely different components, listed once per tier with its own source path.
+
+Description coverage: **282/286** components carry a capability description derived from source — 41 from the section registry's hand-authored when-to-use text, 204 from the component's own doc-comment header, 37 from its tier barrel's roster line. **4** have none; they are listed under [Undescribed components](#undescribed-components) rather than given a sentence invented from their name.
+
+Of those, **252** are *strong* — a capability sentence you could match a requirement against — and **30** are *weak*: either one short clause, or a long one that spends itself on wiring (client boundaries, class names, which primitives it composes) instead of on what the thing is for. Weak rows are marked `(weak)` and listed in full under [Weak descriptions](#weak-descriptions). Coverage is 99%, but **findable-without-luck coverage is 88%**.
+
+Per tier, strong out of total: **Sections** 58/59 · **Blocks** 110/115 · **Chrome** 11/18 · **Primitives** 64/79 (4 undescribed) · **Panels** 6/7 · **Shells** 3/8. A tier low on this line is a tier where a capability search is most likely to come up empty on something that exists.
+
+That grade is **mechanical**. It counts what it can measure — how much a description adds beyond the component's own name, how much of it is spent on wiring, whether the extraction came out damaged — and it cannot tell a fluent paragraph about the wrong subject from a useful one. A person reading these tables will find more rows unusable than the weak count admits. Treat it as a floor on the problem, not a measurement of it, and read the source before concluding a capability is absent.
+
+---
+
+## Find by capability
+
+The left column is search vocabulary — how a person phrases the need. It is hand-authored (no source file calls `FormLightbox` a "contact overlay"), but every component named on the right is checked against the live inventory when this file is generated, so a row can never point at a component that no longer exists.
+
+| If you are looking for… | Use | Notes |
+| --- | --- | --- |
+| contact overlay · modal form · popup form · form in a dialog · form on a dimmed backdrop · lightbox form | `FormLightbox` (sections) · `VideoLightbox` (blocks) · `SpotlightPanel` (sections) · `ContactForm` (sections) | FormLightbox is the modal-form one: a trigger opens a multi-step form inside a Radix Dialog on a dimmed/blurred backdrop (focus trap, ESC/backdrop close, scroll lock, lazy mount). ContactForm is the INLINE form — do not mistake it for the overlay and rebuild the overlay. |
+| search overlay · command palette · cmd-K · ⌘K search · spotlight · quick find | `NavSearchTrigger` (blocks) · `DocsSearch` (blocks) · `AskAiCommandGroup` (blocks) · `SpotlightPanel` (sections) | Read this one carefully: AILK does NOT ship a site-wide ⌘K palette. It ships the PARTS — NavSearchTrigger (the ⌘K trigger pill), DocsSearch (trigger + CommandDialog over a Fumadocs-shaped index, docs-scoped), AskAiCommandGroup (a CommandGroup you drop into your own dialog), and the Command/CommandDialog primitives in `packages/ui/src/primitives`. Composing a site palette from these is expected; forking the dialog is not. SpotlightPanel is the dimmed-backdrop centered-card band — it hosts a form/flow, not a search index. |
+| site rail · vertical nav column · left rail · app sidebar · icon rail · dashboard sidebar | `SidebarNav` (chrome) · `SidebarNavRailItems` (chrome) · `DocsSidebar` (chrome) · `SidePanel` (chrome) | Pick by context: SidebarNav is the DASHBOARD rail (it hardcodes a teams section and a user footer, and is the `sidebar` prop of DashboardShell) — fighting it into a marketing site is the wrong call; DocsSidebar is the DOCS rail (takes a page tree); SidebarNavRailItems is SidebarNav's collapsed icon-rail row. SidePanel is the RIGHT edge, not a left rail. |
+| funnel nav · minimal chrome with one CTA · stripped-down header · landing-page nav · one-action header · sticky CTA | `Nav` (chrome) · `SectionNav` (chrome) · `FloatingCta` (chrome) | There is no separate funnel-nav component, and there does not need to be: this is a CONFIGURATION of Nav — pass it one action and no link list. SectionNav is the in-page section jump nav; FloatingCta is the persistent floating single-action affordance. |
+| numbered work list · ordered steps · process list · how it works · 1-2-3 steps · staircase | `Steps` (blocks) · `StepFlow` (sections) · `StairSteps` (sections) · `FlowStepper` (sections) | For a numbered LIST you want Steps (presentational block) or StairSteps (staggered staircase section). StepFlow and FlowStepper are listed because the phrase collides, but they are the interactive multi-step FORM and its progress indicator — not a work list. |
+| accordion · collapsible · expand/collapse · show more · disclosure | `Accordion` (primitives) · `Collapsible` (primitives) · `FaqItem` (blocks) · `FAQ` (sections) · `Objection` (sections) | `Accordion` is the standalone primitive (Radix, multi-panel) and `Collapsible` is the single show/hide — reach for those for generic disclosure. FaqItem and the FAQ/Objection sections carry their own expand/collapse and are the right choice for question-and-answer CONTENT, because they also feed the page's JSON-LD. |
+| banner · announcement bar · cookie consent · notification strip | `Banner` (chrome) · `AlertSection` (sections) | Banner is chrome (announcement + consent, with dismiss/consent islands); AlertSection is the in-page dismissible strip. |
+| logo wall · client logos · trusted by · partner marks | `LogoCloud` (sections) · `Awards` (sections) |  |
+| pricing table · plan comparison · feature matrix · tier cards | `Pricing` (sections) · `PricingTierCard` (blocks) · `ComparisonMatrix` (blocks) · `ComparisonTable` (sections) · `BillingToggle` (blocks) |  |
+| avatar stack · people grid · about-us team · bios | `Team` (sections) · `TeamMemberCard` (blocks) |  |
+| booking · scheduling · calendar · pick a time · appointment | `Booker` (sections) · `SchedulerEmbed` (blocks) | Booker is the in-page day-strip/slot-grid transaction; SchedulerEmbed is the third-party provider iframe. |
+| sign in · sign up · login form · oauth buttons · account menu | `AuthPanel` (sections) · `AuthCard` (blocks) · `AccountMenu` (chrome) |  |
+| email capture · newsletter signup · subscribe box | `Newsletter` (sections) · `NewsletterFormInline` (blocks) · `NewsletterDetail` (blocks) |  |
+| video player · embedded video · video modal | `VideoSection` (sections) · `VideoEmbed` (blocks) · `VideoLightbox` (blocks) |  |
+| image slider · gallery · carousel · lightbox for images | `Carousel` (sections) · `Gallery` (sections) · `MediaBand` (sections) |  |
+| locale switcher · language picker · region selector · view toggle | `LocaleSwitcher` (blocks) · `MarkdownViewToggle` (blocks) | Dark-mode switching is `ThemeToggle`, a PRIMITIVE — see the Primitives table below. Import it from `@working-theory/ui/primitives`. |
+| table of contents · on-page nav · jump links · sticky outline | `SectionNav` (chrome) · `DocsTocButton` (blocks) · `DocumentChassis` (sections) |  |
+
+---
+
+## Sections (59)
+
+Page-level content bands. Most are MDX-driven (authored by `type` in page frontmatter and dispatched by `SectionRenderer`); a few are composed directly in a route.
+
+Import: `import { X } from "@working-theory/ui/sections";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `AlertSection` | A compact, dismissible in-page alert strip — use for a confirmation or status notice (e.g. a delivery-page 'your download is on its way' message), typically the first section on the page. Bounded to success/info/warning tone; dismissal persists per-visitor. | MDX `type: alert` |
+| `AlertSectionDismissIsland` | Dismiss state + × button for AlertSection. Mirrors the chrome Banner's dismiss-persistence precedent (`packages/ui/src/chrome/BannerDismissIsland.tsx`): a localStorage-backed dismissed flag, read on mount and written on dismiss, with graceful degradation when localStorage is unavailable (SSR, iframe, quota, etc.). | internal — compose from `packages/ui/src/sections/AlertSectionDismissIsland.tsx` |
+| `AskAi` | Use above the footer — hands the visitor to a third-party AI seeded with the entity question. Bounded to five measured providers (ChatGPT/Claude/Google AI/Grok/Perplexity), each deep-linked with an authored prompt. The `ticker` variant renders a compact full-width band instead of the default headline/description/provider-row layout. | MDX `type: ask-ai` |
+| `AuthPanel` | A sign-in/sign-up panel with an optional bounded OAuth provider row (google, github) — UI-contract only, no auth backend; submit and provider clicks are callback props the composing page wires up. | MDX `type: auth-panel` · `import { AuthPanel } from "@working-theory/ui/sections"` |
+| `Awards` | A two-column evidence band — headline/CTA left, up to 5 award or press badges right — use for third-party recognition (badges may render as labeled placeholders until real marks are supplied). | MDX `type: awards` |
+| `BentoGrid` | A mixed-span mosaic of feature cards — use for a visually varied capability overview. | MDX `type: bento-grid` · `import { BentoGrid } from "@working-theory/ui/sections"` |
+| `BlogList` | A blog post list with pagination — use for the blog index page only. | MDX `type: blog-list` · `import { BlogList } from "@working-theory/ui/sections"` |
+| `BlogPost` | A single blog post body with TOC and related posts — use only on the blog-post chassis. | MDX `type: blog-post` · `import { BlogPost } from "@working-theory/ui/sections"` |
+| `Booker` | The custom booker — use on a scheduling page where the whole see-days/pick-slot/confirm transaction should land in the page itself rather than a provider iframe (the `scheduler-embed` alternative). Authors supply only `calLink` plus optional eyebrow/headline framing; duration, meeting type, and timezone are DERIVED from the calendar via /v1/schedule/availability and can never be typed into content. | MDX `type: booker` |
+| `BookerIsland` | The island owns exactly two things: the state machine, and the two calls across the scheduling seam. It talks to `/v1/schedule/availability` and `/v1/schedule/book` — never to a provider — so the day this deploy flips to the self-hosted engine, nothing in this file changes. | internal — compose from `packages/ui/src/sections/BookerIsland.tsx` |
+| `Carousel` | An image carousel/slider — use for a sequential set of visual items in constrained space. | MDX `type: carousel` · `import { Carousel } from "@working-theory/ui/sections"` |
+| `ComparisonTable` | A general-purpose entity-vs-entity comparison — use for /vs pages, not tied to pricing plans. | MDX `type: comparison-table` |
+| `ContactChannels` | A support channel directory — use to list alternate ways to reach the team (icon + title + description + CTA). | MDX `type: contact-channels` · `import { ContactChannels } from "@working-theory/ui/sections"` |
+| `ContactForm` | A contact form with typed fields — use as the primary conversion action on Contact pages. | MDX `type: contact-form` · `import { ContactForm } from "@working-theory/ui/sections"` |
+| `ContentBlock` | Long-form prose with optional media — use for narrative explanation that doesn't fit a card grid. | MDX `type: content-block` |
+| `CTA` | A focused call-to-action block — use to end a page or section with one clear next step. | MDX `type: cta` · `import { CTA } from "@working-theory/ui/sections"` |
+| `DecisionSplit` | An honest either-option decision block — use on /vs pages before any comparison. | MDX `type: decision-split` |
+| `Definition` | A single-term definition callout — use for one prominent 'What is X?' answer-first block. | MDX `type: definition` |
+| `DocumentChassis` | A long-read document page (privacy policy, terms, DPA, working agreement) — chrome-free header + optional stat strip + a sticky numbered section nav beside continuous prose; one document per page/route. The authored `sections` list drives both the nav and the body. | MDX `type: document-chassis` |
+| `DocumentViewer` | A paginated document embedded in a page (a report, a client deliverable) — use for a 10-50 page PDF at a closed 16:9 (deck) or letter (portrait) geometry, rendered by a dynamically-imported PDF.js so it never enters the main bundle. `src` accepts a public path or the authenticated `/v1/deliverables/:grantId` route. Not for long-read prose — that is `document-chassis`. | MDX `type: document-viewer` |
+| `DocumentViewerCanvas` | The PDF.js renderer for DocumentViewer. This file is reached ONLY via the dynamic import in DocumentViewerClient.tsx — that is deliberate: the static `import "pdfjs-dist"` below is what lands in this file's own route-split chunk instead of the main bundle (a static import of the renderer is a spec violation, not a style preference). | internal — compose from `packages/ui/src/sections/DocumentViewerCanvas.tsx` |
+| `DocumentViewerClient` | The interactive shell for DocumentViewer. Split out of DocumentViewer.tsx (which stays RSC) for the same reason AlertSection composes AlertSectionDismissIsland: interactivity is contained to one client island. *(weak)* | internal — compose from `packages/ui/src/sections/DocumentViewerClient.tsx` |
+| `FAQ` | Question-and-answer pairs — use to pre-empt buyer objections that are naturally phrased as questions. | MDX `type: faq` · `import { FAQ } from "@working-theory/ui/sections"` |
+| `Feature` | A multi-item benefit/feature highlight grid — use to walk through several product capabilities. | MDX `type: feature` |
+| `FlowStepper` | Rendering a served flow config as a real multi-step form. | `import { FlowStepper } from "@working-theory/ui/sections"` |
+| `FormLightbox` | The VideoLightbox dialog shell hosting a StepFlow instead of a video: a trigger (e.g. a "Let's Start" Button — any focusable element the caller supplies) opens the SAME StepFlow inside a Radix Dialog on the dimmed/blurred backdrop shared with VideoLightbox/SpotlightPanel. | `import { FormLightbox } from "@working-theory/ui/sections"` |
+| `Gallery` | An image gallery — use to showcase product screenshots or visual work. | MDX `type: gallery` · `import { Gallery } from "@working-theory/ui/sections"` |
+| `GlossaryIndex` | An A-Z glossary index — use for a browsable list of defined terms. | MDX `type: glossary-index` · `import { GlossaryIndex } from "@working-theory/ui/sections"` |
+| `Hero` | Top-of-page introduction — headline, optional subhead and CTAs; use once per page as the first section. | MDX `type: hero` · `import { Hero } from "@working-theory/ui/sections"` |
+| `HeroFormSlot` | The panel hero's right-column gate card: a `FormCard` wrapping either the consumer's conversational intake (when eligible and a `HeroIntakeProvider` is mounted) or the embedded multi-step `StepFlow`, which is also where `controls.showForm` hands the surface over. /. | `import { HeroFormSlot } from "@working-theory/ui/sections"` |
+| `HeroIntakeContext` | The bounded seam through which a consumer page mounts its own conversational intake as the FIRST surface INSIDE one of Hero's existing gate surfaces (the `lightboxCta` FormLightbox, or the panel variant's form-slot card), with the existing multi-step StepFlow as the in-gate fallback (correcting 's whole-page swap). | `import { HeroIntakeContext } from "@working-theory/ui/sections"` |
+| `HeroPromptCapture` | The Hero `promptCapture` opt-in's wiring. Composes the two new blocks — `PromptCaptureCard` (the chat-style card) and `SuggestionChipCarousel` (the one-expanded-slot chip row) — and owns the ONE piece of state they share: the typed text. A chip click writes into it; the card renders and edits it; submit carries it onward. | `import { HeroPromptCapture } from "@working-theory/ui/sections"` |
+| `HeroQuickSearch` | Surfaces the existing ⌘K quick-search as an inline trigger inside the hero CTA cluster (Chassis 2). It does NOT re-roll a search input: it composes the SearchInputTrigger primitive (an input-style control at CTA height) plus the Command palette primitive, so there is ONE search mechanism. The nav's compact 24px ⌘K pill stays as-is — the hero reads as a search INPUT, matching the 44px "Get Started" CTA. | internal — compose from `packages/ui/src/sections/HeroQuickSearch.tsx` |
+| `Items` | A general-purpose card/items grid — use for services, use cases, or any homogeneous list of cards. | MDX `type: items` · `import { Items } from "@working-theory/ui/sections"` |
+| `ListingApplicationFlow` | This is the thing a consuming site mounts INSTEAD of hand-writing three proxy routes, a save-on-advance form, and a decision about where a bearer token lives. | `import { ListingApplicationFlow } from "@working-theory/ui/sections"` |
+| `LogoCloud` | A customer/partner logo wall — use for trust-by-association social proof. | MDX `type: logoCloud` · `import { LogoCloud } from "@working-theory/ui/sections"` |
+| `MDXContent` | The keystone the docs route and blog both render their compiled MDX through. | `import { MDXContent } from "@working-theory/ui/sections"` |
+| `MediaBand` | A single full-width image band — use for the 1-up visual moment Gallery's 2-column minimum can't express (e.g. between pricing plan columns); renders a labeled placeholder until a real image is supplied. | MDX `type: media-band` · `import { MediaBand } from "@working-theory/ui/sections"` |
+| `ModuleAbsent` | What a slice section renders when its module is not here. The oss dispatch table must name a component for every `SectionName`, and `booker`'s real component strips with the scheduling slice. This is the entry it names instead; a slice that IS installed registers over it through `registerSliceRenderer`. | internal — compose from `packages/ui/src/sections/ModuleAbsent.tsx` |
+| `Newsletter` | An email signup form — use for a low-commitment conversion ask. | MDX `type: newsletter` · `import { Newsletter } from "@working-theory/ui/sections"` |
+| `Objection` | Objection-and-response pairs — use for you-might-think rhetoric that isn't phrased as a question. | MDX `type: objection` |
+| `PaymentReceipt` | A checkout payment outcome — use only on a checkout Delivery/confirmation page to show status + receipt details. | MDX `type: payment-receipt` · `import { PaymentReceipt } from "@working-theory/ui/sections"` |
+| `Pricing` | A plan comparison — the page's pricing decision surface; six variants cover tables, toggles, single-price offers, and add-on grids. | MDX `type: pricing` · `import { Pricing } from "@working-theory/ui/sections"` |
+| `PricingTable` | A grid of subscription plan tiers that SUBSCRIBE — the capability-bearing twin of the `Pricing` CMS section (which renders href-based marketing tier CTAs, no live Stripe call). `PricingTable` is scaffolded by `scaffold-commerce` (not registered in `SectionRenderer`'s CMS dispatch table) and each tier's action POSTs to the subscription surface's `subscribeHandler` route + redirects to the returned Stripe Checkout URL — the same `onCheckout`-callback shape `CheckoutForm` uses for one-time products. | `import { PricingTable } from "@working-theory/ui/sections"` |
+| `ProjectListingShelves` | Two shelves of ProjectListingCards partitioned from ONE list of public listing rows: `status === "active"` on one shelf, `status === "closed"` on the other. `closed` is COMPUTED by the API read (the window-end check lives server-side, / D6b) — this component never recomputes it, it only reads the field. | `import { ProjectListingShelves } from "@working-theory/ui/sections"` |
+| `SchedulerEmbed` | A declarative third-party booking iframe (e.g. Google Calendar Appointment Schedules) — use for a booking/scheduling moment; sets the provider's cookies on load, so a site classifying it as non-essential may wrap it in a consent gate. | MDX `type: scheduler-embed` · `import { SchedulerEmbed } from "@working-theory/ui/sections"` · `packages/ui/src/sections/SchedulerEmbed.tsx` |
+| `SectionEmpty` | The shared empty-state body every section's `*Empty` variant delegates to. | `import { SectionEmpty } from "@working-theory/ui/sections"` |
+| `SectionRenderer` | Typed dispatch table. Maps a section's `type` discriminant to its React component. | `import { SectionRenderer } from "@working-theory/ui/sections"` |
+| `Separator` | An inter-section spacer — use to add rhythm or a visible rule between two sections that need more separation than default spacing gives. | MDX `type: separator` · `import { Separator } from "@working-theory/ui/sections"` · `packages/ui/src/sections/Separator.tsx` |
+| `SocialProof` | Tweet/post-shaped social proof items — use for lightweight, screenshot-style endorsements. | MDX `type: social-proof` · `import { SocialProof } from "@working-theory/ui/sections"` |
+| `SplitContentMedia` | Lays out a SectionHeader (text, one side) beside a media slot (the other side) — the HubSpot/wealthsmyth split content+media pattern. | `import { SplitContentMedia } from "@working-theory/ui/sections"` |
+| `SpotlightPanel` | A full-width dimmed/blurred backdrop (abstract pattern or product image) behind a centered elevated card carrying a headline, support text, and a form/flow embed — use for a demo or signup moment that needs focus without leaving the page flow (apollo.io /demo pattern). | MDX `type: spotlight-panel` · `import { SpotlightPanel } from "@working-theory/ui/sections"` |
+| `StairSteps` | A 2-5 step staircase — use for process/journey narratives where direction carries meaning (an ascending 'up-right' staircase for a build-up story, a descending 'down-right' one for the conversionfactory.co 'from idea to impact' pattern). | MDX `type: stair-steps` · `import { StairSteps } from "@working-theory/ui/sections"` |
+| `Stats` | A number-led credibility row — use to show scale or outcome metrics. An optional leadQuote can front the row with an analyst quote (staggered variant mirrors apollo.io's mixed-size evidence band). | MDX `type: stats` |
+| `StepFlow` | A data-driven multi-step lead-capture form (one small field group per step, progress affordance, per-step advance) — use for a longer qualifying gate where a single-step ContactForm would feel too long; fires onStepComplete after each step so an abandoned flow still captures a partial lead. | MDX `type: step-flow` · `import { StepFlow } from "@working-theory/ui/sections"` |
+| `Tabs` | Tabbed content panels — use to let a reader choose between parallel content without scrolling. | MDX `type: tabs` · `import { Tabs } from "@working-theory/ui/sections"` · `packages/ui/src/sections/Tabs.tsx` |
+| `Team` | A team member grid — use on About pages to introduce the people behind the product. | MDX `type: team` · `import { Team } from "@working-theory/ui/sections"` |
+| `Testimonials` | Direct customer quotes — use for first-person social proof with attribution. | MDX `type: testimonials` |
+| `VideoSection` | The standard large-centered-video section (acquisition.com/workshop pattern) — optional headline/intro above a bounded-width centered video, optional caption/CTA below; renders a labeled placeholder until a real source is supplied. | MDX `type: video-section` · `import { VideoSection } from "@working-theory/ui/sections"` |
+
+---
+
+## Blocks (115)
+
+Intermediate composition tiles — the pieces sections are built from. Compose primitives and panels; never import a section.
+
+Import: `import { X } from "@working-theory/ui/blocks";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `AddonCard` | Apollo.io-pattern add-on tile: header-area eyebrow+name+price, optional qualifier/CTA, titled or plain-string feature rows with a selectable checkmark tone (Pricing addons variant). | `import { AddonCard } from "@working-theory/ui/blocks"` |
+| `AddressFieldset` | The composite control for StepFlow's "address" field type. No such component existed in the library before this — built by composing the existing Field/Input/Select primitives, no bespoke markup, no new primitive. Mirrors PhoneNumberField's division of labor for the "tel" field type: this block renders the six named controls; the consuming section combines/reads them, it does no combining itself. | `import { AddressFieldset } from "@working-theory/ui/blocks"` |
+| `AgentContextCard` | Capability-bearing block that renders agent provenance. RSC note: no hooks or browser APIs — server-renderable by default. *(weak)* | `import { AgentContextCard } from "@working-theory/ui/blocks"` |
+| `ArticleHeaderAtoms` | They define the title / meta-line / tags / back-link / action-bar treatment ONCE so the docs and blog headers cannot drift. `DocsArticleHeader` (top layout) and `BlogPostHeader` (sticky-rail layout) are thin wrappers that COMPOSE these atoms — there is no `layout` switch or stack of `show*` booleans; the two arrangements differ only in which atoms each wrapper places and in what order. | `import { ArticleHeaderAtoms } from "@working-theory/ui/blocks"` |
+| `ArticlePager` | The footer prev/next pager. Given the previous and next destinations — docs pages in tree order, or blog posts in date order — renders two link tiles (a directional label + the destination title). Either side may be absent (first / last item) — the present side still anchors to its edge. Renders nothing when both sides are absent. | `import { ArticlePager } from "@working-theory/ui/blocks"` |
+| `AskAiCommandGroup` | The ⌘K palette's composable "Ask AI" group; one CommandItem per provider seeding "About &lt;entity>: &lt;query>" (or the entity promptText when the query is empty); composed by the consumer's own CommandDialog. | `import { AskAiCommandGroup } from "@working-theory/ui/blocks"` |
+| `AskAiProviderRow` | The ONE shared provider-link row every ask-AI placement composes — the AskAi section (band + ticker variant) and the Hero `askAi` opt-in all render THIS block, never a per-placement fork. Renders a bounded set of five measured providers, each a deep link seeded with an AUTHORED `promptText` — the prompt is always consumer-supplied data, never derived from page context (headline, entity name, etc.). | `import { AskAiProviderRow } from "@working-theory/ui/blocks"` |
+| `AuthCard` | Logo (top-center, inside). Axes: intent: "sign-in" \| "sign-up" — drives heading / subhead / footer copy. method: "password" \| "magic-link" \| "sso" — drives the body + primary action. | `import { AuthCard } from "@working-theory/ui/blocks"` |
+| `AwardBadgePlaceholder` | The labeled placeholder an Awards badge slot renders when no image has been supplied — mirrors MediaPlaceholder's role but in an award-chevron/ laurel badge silhouette rather than a generic photo frame, since an unfilled award slot should read as "an award badge goes here," not "a photo goes here." The shape (a laurel-flanked medallion over a chevron ribbon) is a hand-drawn SVG outline — never a copied G2/Capterra/Apollo asset. | internal — compose from `packages/ui/src/blocks/AwardBadgePlaceholder.tsx` |
+| `BackgroundPattern` | Decorative SVG dot-grid / line pattern for ContactForm section. Decorative block (generalized beyond its original single consumer). Renders an absolutely-positioned decoration behind a section's content. Originally the pattern anchored behind ContactForm's form column; SpotlightPanel composes it as a full-bleed section backdrop (dimmed + blurred, behind a centered card) — same block, a second placement. | `import { BackgroundPattern } from "@working-theory/ui/blocks"` |
+| `BadgeRow` | Horizontal cluster of static badge labels used by Hero and Feature section families for `data.badge` and tag-list patterns. | `import { BadgeRow } from "@working-theory/ui/blocks"` |
+| `BillingToggle` | Monthly / Annual billing period toggle for the Pricing section. Purely presentational — click handlers come from the parent (Pricing section). No "use client" needed at the block level; the parent Pricing section is "use client" and passes the callbacks down. | `import { BillingToggle } from "@working-theory/ui/blocks"` |
+| `BlogPostHeader` | Layout: the better-auth sticky left rail — eyebrow ← back-link · decorative title · author byline · date/reading-time meta · tags. Per the title here is DECORATIVE (aria-hidden): the semantic `&lt;h1>` is rendered atop the right content column by `BlogPost` (bodyOnly), so the page keeps exactly one heading. | `import { BlogPostHeader } from "@working-theory/ui/blocks"` |
+| `BookerAttendeeFields` | TWO FIELDS. A booking needs somewhere to send the invite and a name to put on it; every additional field is one more reason to abandon a transaction the user had already decided to complete. Notes, phone, and company are deliberately absent — the provider collects them after the invite lands, if the operator wants them at all. | internal — compose from `packages/ui/src/blocks/BookerAttendeeFields.tsx` |
+| `BookerDateStrip` | ONLY DAYS THAT HAVE OPEN SLOTS APPEAR. That is the structural argument this block makes, and the reason the composition is a horizontal strip rather than the month grid every booking widget reaches for: a month grid spends its whole area rendering the ~24 days you cannot book, then needs a second interaction to reveal which of the remaining six are live. | internal — compose from `packages/ui/src/blocks/BookerDateStrip.tsx` |
+| `BookerEventHeader` | TWO KINDS OF TEXT, AND THE DIFFERENCE MATTERS. `eyebrow` and `headline` are AUTHORED: the operator's words about why someone would book. Everything in the meta row — duration, meeting type, timezone — is DERIVED from the calendar on the availability read, which is why the section schema has no field for any of it. | internal — compose from `packages/ui/src/blocks/BookerEventHeader.tsx` |
+| `BookerPanel` | The booking card, fully controlled. One chassis, five views, ONE FOOTER. | internal — compose from `packages/ui/src/blocks/BookerPanel.tsx` |
+| `BookerSlotGrid` | The selected day's open times. Two columns at 48px on mobile — the measured pixel target — widening to three at `lg` so the desktop variant shows more of the day without scrolling. Two columns is not an arbitrary density: at 390px it is the widest grid where a time still reads at a glance, and it puts eight times (a full working day's openings) inside one thumb-reachable block. | internal — compose from `packages/ui/src/blocks/BookerSlotGrid.tsx` |
+| `BrandLogo` | Brand identity lockup (mark + wordmark + badge slot) as a home link. Brand identity lockup for Nav, Footer, and other surfaces. | `import { BrandLogo } from "@working-theory/ui/blocks"` |
+| `Card` | The base surface-chrome block the section tier composes instead of hand-rolling `rounded + hairline border + surface + p-card` (7× duplicated at time). A block owns its visual identity: it looks the same everywhere it is composed, and a higher tier SELECTS a look via `variant` — it never patches via className. | `import { Card } from "@working-theory/ui/blocks"` |
+| `CheckoutForm` | Product/amount selection + checkout submit for the one-time checkout surface. | `import { CheckoutForm } from "@working-theory/ui/blocks"` |
+| `CheckoutPriceCard` | The order-summary card the flow's side panel becomes at checkout: eyebrow, offer name + description, seat/credit line items, an optional caller-supplied add-credits row, and (on the quoted arm only) total + due-today; with a `configurator` it also renders the in-card seat stepper, period toggle, add-on credits row and on-demand breakdown, pricing itself with the pure `price`. | `import { CheckoutPriceCard } from "@working-theory/ui/blocks"` |
+| `ChoiceCard` | Onboarding "Is this you?" disambiguation card — reimplements the ploy.ai persona-disambiguation capture: a researched candidate option vs a "none of these are me" option, confirmed by the user ("a human-input seam the user answers to orient the agent"). Purely presentational and props-driven: renders options + an optional "none of these" option + a confirm action, disabled until a selection is made. | `import { ChoiceCard } from "@working-theory/ui/blocks"` |
+| `CodeBlock` | Read-only code display with syntax highlighting. Modeled on the Claude docs code-block pattern. | `import { CodeBlock } from "@working-theory/ui/blocks"` |
+| `ComparisonMatrix` | Full feature × tier comparison matrix for the Pricing 'with-comparison-table' variant. Renders N collapsible ComparisonGroups, each containing M feature rows with per-tier values. | `import { ComparisonMatrix } from "@working-theory/ui/blocks"` |
+| `Composer` | The chat input, per the ploy.ai capture contract. | `import { Composer } from "@working-theory/ui/blocks"` |
+| `ConsentGroup` | The composite control for the `consent` field kind: one real checkbox per consent purpose, each with its statement and inline policy links, inside one fieldset. | `import { ConsentGroup } from "@working-theory/ui/blocks"` |
+| `ConsentStatement` | The sentence a person agrees to, with its policy links inline. | `import { ConsentStatement } from "@working-theory/ui/blocks"` |
+| `ContactChannelItem` | Renders one support channel entry: colored icon square + headline + description paragraph + CTA link (with trailing arrow icon). | `import { ContactChannelItem } from "@working-theory/ui/blocks"` |
+| `ContactFormFields` | Renders the form field grid (Input / Textarea / Select primitives) + submit Button + optional consent text footer. | `import { ContactFormFields } from "@working-theory/ui/blocks"` |
+| `ContactInfoAside` | For ContactForm 'split-with-pattern' variant. Renders address / phone / email contact info rows. Each row: sr-only &lt;dt> label + visible &lt;dd> with Icon + Text. Phone and email render as tel:/mailto: links (click-to-call / click-to-email). | `import { ContactInfoAside } from "@working-theory/ui/blocks"` |
+| `ConversationalIntake` | The UI half of the conversational-intake feature: renders the transcript, closed-question answer pills, a free-text form, a thinking indicator, and Skip — driven entirely through the `NextTurn` interface exported by `./engine` (merged). | internal — compose from `packages/ui/src/blocks/conversational-intake/ConversationalIntake.tsx` |
+| `DescriptionList` | Semantic &lt;dl> of aligned term/definition rows (rows + inline layouts). A semantic &lt;dl> rendering label/value rows from an `items` prop. Each item is a &lt;dt> (muted, min-width-aligned term) paired with a &lt;dd> (value). The value is a ReactNode, so callers compose richer values (spans, lists, mono text) inside it. | `import { DescriptionList } from "@working-theory/ui/blocks"` |
+| `DetailCard` | The collapsible console / data-panel card: a composable card with a header (title + optional actions + collapse toggle), an optional tab bar, a body slot, and an optional footer. The "deferred SidePanel DetailCard" from, built as a general content card any console / detail view can compose without inventing its own card structure. | `import { DetailCard } from "@working-theory/ui/blocks"` |
+| `DetailHeader` | The entity-bearing sibling of PageHeader: a Breadcrumb wayfinding trail above an EntityHeader identity row, plus a forwarded actions slot. | `import { DetailHeader } from "@working-theory/ui/blocks"` |
+| `DistributionList` | Per-option answer-share list over the Progress primitive. One question's answer distribution: a title, an "answered" count line, and one row per declared option (a label, a pre-formatted share `display` string, and a `Progress` bar). `display` is pre-formatted by the caller (Rule 10 — this block never formats numbers itself); `share` drives the `Progress` fill, scaled to the primitive's 0–100 range. | `import { DistributionList } from "@working-theory/ui/blocks"` |
+| `DocsActionBar` | The agent-facing article toolbar that lands in the DocsArticleHeader `actionBar` slot, presented as the Claude-docs **"Copy page ▾" split button**. The in-page rendered↔markdown toggle is NOT reimplemented here — that is the existing MarkdownViewToggle block, which the route mounts around the article body. This bar only adds the copy + open-in affordances. | `import { DocsActionBar } from "@working-theory/ui/blocks"` |
+| `DocsArticleHeader` | The article header: a breadcrumb trail (with the TOC popover button at its inline-end), the page title (the single &lt;h1>), an optional lead description, and an "updated" meta line. Leaves an `actionBar` slot for the Phase-5 DocsActionBar (markdown toggle / copy / share) — empty until then. | `import { DocsArticleHeader } from "@working-theory/ui/blocks"` |
+| `DocsFeedback` | The article-footer feedback widget: a "Was this helpful?" thumbs yes/no pair plus an "Edit this page on GitHub" link. Clicking a thumb records the answer (fires a `gtag` analytics event when the site's GA is present) and, on "no", reveals an optional free-text note. After answering, the prompt is replaced with a thank-you line. | `import { DocsFeedback } from "@working-theory/ui/blocks"` |
+| `DocsSearch` | The cmd-K documentation search: a ⌘K trigger pill (NavSearchTrigger) that opens a CommandDialog over a passed-in search index. Typing filters the index by title/description (cmdk's built-in filter, fed a `value` that bundles both); selecting a result navigates there. | `import { DocsSearch } from "@working-theory/ui/blocks"` |
+| `DocsTocButton` | Clicking the `List`-icon button opens a Popover rendering the shared `TableOfContents` (styling preserved). Esc / outside-click closes it (Radix default); in-page anchor jumps work as they do in the rail. The button renders nothing when there are no TOC entries, so the breadcrumb row stays clean on heading-less / `wide` pages. | `import { DocsTocButton } from "@working-theory/ui/blocks"` |
+| `EntityHeader` | The single identity-row source: an optional leading avatar, a title/name (Heading), an optional subtitle/meta line (Text), an optional type-badge slot above the title, and an optional trailing actions slot. | `import { EntityHeader } from "@working-theory/ui/blocks"` |
+| `FaqItem` | Q&A pair block for FAQ section families (expanded + accordion). Defaults reproduce the current render except the deliberate item-spacing-asymmetry fix. | `import { FaqItem } from "@working-theory/ui/blocks"` |
+| `FeatureCard` | Icon badge + title + a short check-list + an optional "Learn more" link — the card used in HubSpot's right-hand product grid. Generalizes the inline card markup currently hand-rolled in sections/Feature.tsx. | `import { FeatureCard } from "@working-theory/ui/blocks"` |
+| `FeatureCardGrid` | Responsive column schedule (mobile-first, uniform cells): base. Uniform responsive grid of FeatureCard tiles. Strictly equal-span cells at every breakpoint; use BentoGrid for variable-span layouts. | `import { FeatureCardGrid } from "@working-theory/ui/blocks"` |
+| `FloatingBar` | Z-40 (spec) — the same rung Nav's sticky bar and FloatingCta already occupy; no new z-index token. The same-slot takeover works by DOM ORDER, not a higher z: a `position="sticky"` FloatingBar rendered later in the document (inside body content, after the nav) paints over a `fixed` FloatingBar at equal z-40 once it sticks, given an `opaque` surface. | internal — compose from `packages/ui/src/blocks/FloatingBar.tsx` |
+| `FlowSidePanel` | The per-view side panel of the flow/recommender surface. ONE CHASSIS, THREE VIEWS. | `import { FlowSidePanel } from "@working-theory/ui/blocks"` |
+| `FooterBottomBar` | Separator + copyright line (+ optional trailing social). Bottom bar with a single top divider + copyright line. | `import { FooterBottomBar } from "@working-theory/ui/blocks"` |
+| `FooterNav` | Data-driven footer nav: flat row or titled columns (row/columns layout). These two renderings of the same footer-link data were used mutually-exclusively by the chrome `Footer`'s `layout` switch — collapsing them removes a real either/or the parent managed. | `import { FooterNav } from "@working-theory/ui/blocks"` |
+| `FormCard` | Stateless, centered max-w-md form-card chassis: a Card wrapping an optional title + description header, a field-stack body (children), and a footer slot for the primary action + a secondary line below it. The SHARED look composed by both the contact-form section's 'card' variant and the auth-panel section — this block owns none of their field/state machinery, only the surrounding chrome. | `import { FormCard } from "@working-theory/ui/blocks"` |
+| `InviteMemberDialog` | The invite modal — reimplements the ploy.ai "Invite Team Member" capture (Email textbox + Role select, default Member, options Member/Admin, helper "Admins can invite and remove members." + Send Invitation). | `import { InviteMemberDialog } from "@working-theory/ui/blocks"` |
+| `InvoiceForm` | Draft-invoice creation form. Creates a draft invoice (single line item), for the invoice surface (U4). | `import { InvoiceForm } from "@working-theory/ui/blocks"` |
+| `InvoiceList` | Capability-bearing invoice rows (status + amount + hosted-invoice link). A customer's invoice rows, shared by the invoice surface (U4). Capability-bearing: binds a schema.org `Invoice` resource-payload fragment per row (imported from `@working-theory/schema`) — so a co-located `.text.ts` + `.text.test.ts` renderer is required and gated by `scripts/check-ax-parity.sh`. | `import { InvoiceList } from "@working-theory/ui/blocks"` |
+| `KeyPointsPanel` | ONE shared block composed by two consumers: Hero's `panel` variant (text-left / panel-right) and Pricing's `band-hero` arrangement (header-left / panel-right, tiers below). | internal — compose from `packages/ui/src/blocks/KeyPointsPanel.tsx` |
+| `LinkCard` | A whole-tile link card: the entire tile IS the anchor (Claude-docs link-card anatomy). Optional leading icon, a title heading, and an optional description paragraph. Hover fill + chrome are intrinsic to the block — never props. | `import { LinkCard } from "@working-theory/ui/blocks"` |
+| `LinkListItem` | Hub-page spoke list row: prose Link + optional description, enlarged to the 44px touch-target floor. Fix: the enlarged-hit-area pattern (same idiom as ShortcutTrigger, SegmentedControl's touchTargetFloor) — `min-h-(control-height-big)` clamps the anchor's clickable box to 44px while `inline-flex items-center` keeps the visible text at its normal prose size. | `import { LinkListItem } from "@working-theory/ui/blocks"` |
+| `ListingFullPreview` | The full-page-preview `custom` step renderer. The founder's assembled application, rendered as a page, with an edit link back to the step that owns each rendered part. Purely presentational: every entry's label and formatted value arrive pre-built on `entries` (this block does no formatting of its own), and `onEdit` is the only way it ever changes anything — it never mutates, saves, or fetches. | `import { ListingFullPreview } from "@working-theory/ui/blocks"` |
+| `ListingPrivacyNotice` | The per-listing privacy notice. It names the FOUNDER — not the platform — as the party collecting a visitor's personal data, and it renders ON THE FLOW (where a visitor submits answers), not on the listing page. | `import { ListingPrivacyNotice } from "@working-theory/ui/blocks"` |
+| `ListingQuestionReview` | The edit-only question-review `custom` step renderer. The founder is refining a diagnostic template the SITE authored, not composing one from nothing (`projectListingQuestionsSchema`, `packages/validation/src/schemas/project-listings.ts`). | `import { ListingQuestionReview } from "@working-theory/ui/blocks"` |
+| `ListingTilePreview` | The founder's tile, as it will look, updating as they type. | `import { ListingTilePreview } from "@working-theory/ui/blocks"` |
+| `LocaleSwitcher` | Compact globe + locale dropdown. Extracts the "🌐 English ▾" affordance that lived as an inline node in the chrome Footer story into a reusable block. Composes the `Select` primitive (NOT a raw &lt;select>): a leading globe icon, the current locale label (via SelectValue), and the trigger's built-in chevron. | `import { LocaleSwitcher } from "@working-theory/ui/blocks"` |
+| `LogoRow` | The ONE logo-strip implementation; bounded layout/treatment/logoSize plus an opt-in motion-safe marquee; composed by the LogoCloud section and the Hero logoStrip opt-in. | `import { LogoRow } from "@working-theory/ui/blocks"` |
+| `MarkdownViewToggle` | 2-state rendered ↔ markdown view toggle for content pages. The human complement to the agent-facing /llms.txt surface. Mirrors the Claude-docs "view/copy as markdown" affordance. Ships at Tier 3 (Block) because it is an interactive view-toggle control composing the SegmentedControl primitive with the CodeBlock block — not a page-level layout shell. | `import { MarkdownViewToggle } from "@working-theory/ui/blocks"` |
+| `MediaFigure` | The reusable *frame* for the visual half of a split section: an `Image` constrained by an optional `AspectRatio`, with consistent rounding, an optional caption, an optional decorative frame, and an optional overlay slot + scrim for text/badges/play-buttons over media. | `import { MediaFigure } from "@working-theory/ui/blocks"` |
+| `MediaPlaceholder` | The single shared labeled placeholder a declared IMAGERY SLOT renders when no asset has been supplied yet — a chassis never silently ships an empty slot, and never renders an accidental image. Composed by `Hero`/`Feature`/`Gallery` (sections tier) whenever their `imagerySlot` data flag is `true` and the corresponding asset is absent. | internal — compose from `packages/ui/src/blocks/MediaPlaceholder.tsx` |
+| `MemberList` | Settings "People" member rows — reimplements the ploy.ai Team Members list capture (avatar + email + "(you)" + role Badge). Purely presentational and props-driven: no session/permission logic; the caller supplies the member list, role labels, and an optional per-row actions slot (e.g. a "Remove" menu). | `import { MemberList } from "@working-theory/ui/blocks"` |
+| `MetricComparisonTable` | A numeric comparison table over the Table primitive. The operator-dashboard comparison view's core surface: one column per waitlist (plus a "total" column) and one row per metric (raw, qualified, qualification rate, one row per tier). | `import { MetricComparisonTable } from "@working-theory/ui/blocks"` |
+| `NavActionList` | CTA action cluster block (one shared button chrome; variant = paint, size = box). Extracts the action-cluster variant routing that was duplicated verbatim between Nav (ActionCluster, Nav.tsx:240–342) and NavMobileMenu (action map, NavMobileMenu.tsx:344–435). This block is the vehicle for the later Nav + NavMobileMenu refactors — both will compose it. | `import { NavActionList } from "@working-theory/ui/blocks"` |
+| `NavFlyoutPanel` | Mega-menu body block (feature grid + action bar) for Nav flyouts. Renders the content of a flyout (mega-menu) panel opened by a NavigationMenu trigger in the Nav chrome component. | `import { NavFlyoutPanel } from "@working-theory/ui/blocks"` |
+| `NavSearchTrigger` | ⌘K search trigger control for Nav desktop pill + mobile icon-only surfaces. ⌘K search trigger button for Nav, desktop + mobile. Thin domain wrapper over the ShortcutTrigger primitive: it resolves the i18n "Open search" label and passes the search specifics (Search icon, the ⌘/K shortcut, the onSearchOpen handler) to ShortcutTrigger. | `import { NavSearchTrigger } from "@working-theory/ui/blocks"` |
+| `NewsletterDetail` | One "why subscribe" detail item: colored icon square + headline + description. Vertically arranged (icon top, heading + description below). Used in the right-column 2-up grid of the 'side-by-side-with-details' variant. | `import { NewsletterDetail } from "@working-theory/ui/blocks"` |
+| `NewsletterFormInline` | Inline email signup form: email Input + submit Button side-by-side at sm+, stacked on mobile (input full-width on its own row, Subscribe below). Manages its own submit state so the parent Newsletter section can remain RSC-oriented (only this block needs the client boundary). | `import { NewsletterFormInline } from "@working-theory/ui/blocks"` |
+| `OnboardingChecklist` | Global onboarding launcher: floating "N/5" bubble expanding into a Popover (lg+) / bottom Sheet (&lt;lg) checklist with SegmentedProgress + item rows (ploy-capture recomposition). The global onboarding launcher captured off ploy.ai's app frame (behavior spec: `post-ftu-checklist` — "global onboarding launcher (floating, all pages)"). | `import { OnboardingChecklist } from "@working-theory/ui/blocks"` |
+| `PageHeader` | RSC. Page-level header composing the Breadcrumb primitive for the left-side wayfinding trail, a generic right-side `actions` slot, and an optional `switcher` slot for header-owned segment switching. Fills AppShell's `header` slot (DashboardShell and similar). No accent bar. No tab API. No named action props — the caller assembles whatever button/menu nodes it needs and passes them as `actions`. *(weak)* | `import { PageHeader } from "@working-theory/ui/blocks"` |
+| `PageHeaderSwitcher` | Header-owned context-switcher island (DropdownMenu-backed). Header-owned segment switcher rendered inside PageHeader's `switcher` slot. Composes DropdownMenu (Radix-backed — positioning, click-outside, Escape, focus management, and roving keyboard nav all come for free). | `import { PageHeaderSwitcher } from "@working-theory/ui/blocks"` |
+| `PairingCard` | Quiet card naming a matched WaitlistRecommendation pairing: both resolved offer names + the resolved reason, joined against a caller-supplied offers[] by key. | `import { PairingCard } from "@working-theory/ui/blocks"` |
+| `PaymentLinkCard` | A single shareable Stripe Payment Link (pay-by-link surface). Renders the link's offer name, active-status chip, optional amount, and the hosted URL with a one-click copy action. | `import { PaymentLinkCard } from "@working-theory/ui/blocks"` |
+| `PaymentLinkForm` | Product selection + "create link" submit for the pay-by-link surface. | `import { PaymentLinkForm } from "@working-theory/ui/blocks"` |
+| `PaymentLinkList` | Presentational list composing PaymentLinkCard rows. A site owner's shareable payment links (pay-by-link surface). Composes one `PaymentLinkCard` per link. | `import { PaymentLinkList } from "@working-theory/ui/blocks"` |
+| `PaymentResult` | Success/cancel result state for the one-time checkout surface — the terminal render a consumer's success/cancel return-URL page shows after the Stripe-hosted Checkout redirect. | `import { PaymentResult } from "@working-theory/ui/blocks"` |
+| `PaymentStatusBadge` | Capability-bearing payment/invoice/subscription status chip. Payment-state chip shared by the invoice-status (U4) and subscription-status (U5) surfaces. | `import { PaymentStatusBadge } from "@working-theory/ui/blocks"` |
+| `PhoneNumberField` | Single-box combo phone input for the "tel" field kind (supersedes the two-segment country-Select + number-Input layout). | `import { PhoneNumberField } from "@working-theory/ui/blocks"` |
+| `PortalEntry` | Presentational "Manage billing" entry action, reuses U1 StripeActionButton; target of U5 SubscriptionStatus's Manage action. A standalone "Manage billing" entry point into Stripe's hosted Customer Portal — the smallest surface (spec: AILK owns only the entry; Stripe hosts the portal itself). | `import { PortalEntry } from "@working-theory/ui/blocks"` |
+| `PostRow` | A single horizontal row in the two-column blog index: a landscape cover thumbnail (left) followed by the post's title · excerpt · author+date meta · tag list. The WHOLE row is one link (aria-labelled by the title, so screen readers announce the post title rather than the concatenated row content). | `import { PostRow } from "@working-theory/ui/blocks"` |
+| `PricingExtraTierRow` | Compact horizontal extra-tier row for the Pricing 'two-tiers-with-extra-tier' variant. Renders plan name + description on the left and a CTA on the right. Structurally different from PricingTierCard (no price display in this variant). | `import { PricingExtraTierRow } from "@working-theory/ui/blocks"` |
+| `PricingTierCard` | Single pricing tier card (all 4 Pricing variants). Renders a single pricing tier: plan name + optional badge, description, price display, CTA button, and feature checklist. | `import { PricingTierCard } from "@working-theory/ui/blocks"` |
+| `PricingTierCardFeaturesDisclosure` | Phone-breakpoint (&lt;md, 768px — the same phone/tablet step CardGrid's own mobile-stacking ramp uses) presentation of a tier card's feature list: collapsed behind a disclosure button so price + CTA (which render ABOVE this row, see PricingTierCard's row-slot ordering) fit the first card view on a phone — the wisprflow.ai/pricing pattern. `md` and up renders the SAME feature list, always expanded, in a second, non-interactive tree — desktop/tablet is unaffected by the collapse. | `import { PricingTierCardFeaturesDisclosure } from "@working-theory/ui/blocks"` |
+| `PricingTierCardSeatControl` | Seat-count range picker for the Team tier card. Renders a Select primitive that lets the user choose an "Up to N seats" option from a caller-supplied list of numbers. The parent PricingTierCard stays a pure RSC; only this tiny island is hydrated. Pattern mirrors PageHeaderSwitcher.tsx: small "use client" island imported by an otherwise-server-rendered parent, keeping the client bundle minimal. *(weak)* | `import { PricingTierCardSeatControl } from "@working-theory/ui/blocks"` |
+| `ProjectListingCard` | The tile for one listing on a shelf (`ProjectListingShelves`). The whole tile is a single anchor (LinkCard's bespoke-by-semantics precedent: Card renders a &lt;div> and cannot satisfy a whole-tile-link contract, so this composes Link directly rather than Card). | `import { ProjectListingCard } from "@working-theory/ui/blocks"` |
+| `PromptCaptureCard` | The chat-style prompt card: a multiline field carrying the authored placeholder, with a circular arrow submit control pinned bottom-right that stays muted (disabled) until the visitor has typed something. Enter submits; Shift+Enter inserts a newline — the chat-composer convention. | `import { PromptCaptureCard } from "@working-theory/ui/blocks"` |
+| `Prose` | The single typography wrapper both the docs route and blog render their compiled-MDX body inside. It styles every RAW markdown element a compiled document emits — h2–h6, p, ul/ol/li, blockquote, table parts, hr, a, inline code, pre, img, kbd, strong/em — via `@working-theory/theme` semantic tokens and type roles. No raw color or spacing literals; dark mode rides the semantic tokens (no `dark:` variants needed). | `import { Prose } from "@working-theory/ui/blocks"` |
+| `RecommendationCard` | "For you" proactive-recommendation tile: status + title + description + "Why this?" disclosure + context chip + action + dismiss (ploy-capture recomposition). The "For you" proactive-recommendation card captured off ploy.ai's Overview page (behavior spec: -2, — `overview-page` "For you" feed / rebuild-triage row "For you" recommendation card"). | `import { RecommendationCard } from "@working-theory/ui/blocks"` |
+| `ResponseChart` | The single-question aggregate chart of the diagnostic's results reveal. Renders exactly ONE `FlowAggregateQuestion`. The chart type is FIXED by `question.answerType` — a closed `single \| multi` union — and there is no `chartType`/`variant` prop: an author cannot request a doughnut for a multi-select question, because there is no prop through which to ask. | `import { ResponseChart } from "@working-theory/ui/blocks"` |
+| `ResultsReveal` | The results-reveal active-region composition: one ResponseChart per resultsReveal-flagged, aggregate-matched segmentation step, in served order. | `import { ResultsReveal } from "@working-theory/ui/blocks"` |
+| `SchedulerEmbed` | A declarative third-party booking iframe. Renders a full-width, border-0, lazy-loaded &lt;iframe> at `src` with a graceful loading skeleton (shown until the iframe's own `load` event fires) and a timeout-gated plain-link fallback beneath it — for environments that block third-party frames (ad blockers, a strict CSP `frame-src`) where the iframe may load blank or never load at all. | `import { SchedulerEmbed } from "@working-theory/ui/blocks"` · `packages/ui/src/blocks/SchedulerEmbed.tsx` |
+| `SectionHeader` | Alignment-parameterized section header (eyebrow/subtitle/description/supportLink). The same component serves two ranks (headingLevel="section" \| "subsection") and three alignments (align="start" \| "center" \| "end"). It knows nothing about columns/splits/carousels — it is width-flexible and fills whatever container the section places it in. | `import { SectionHeader } from "@working-theory/ui/blocks"` |
+| `ShareBar` | The reader-facing counterpart to DocsActionBar. Both surfaces share the same SplitButton *affordance + slot* (outline variant, right-justified on the post title row) but fill it with different actions: DocsActionBar carries the AI-ingestion set (Copy page + Open in …), ShareBar carries the social-share set (X · LinkedIn · Bluesky · Copy link). One primitive, two configs. | `import { ShareBar } from "@working-theory/ui/blocks"` |
+| `SinglePriceCard` | 2-column split card for the Pricing 'single-price-with-details' variant. *(weak)* | `import { SinglePriceCard } from "@working-theory/ui/blocks"` |
+| `SocialIcons` | Horizontal row of social icon links. Renders brand icons (via Icon primitive + simple-icons paths) inside accessible Link primitives. Each platform link gets an aria-label. Shared by company-mission, simple-centered, and newsletter-below footer variants, and composed by TeamMemberCard for member social links. *(weak)* | `import { SocialIcons } from "@working-theory/ui/blocks"` |
+| `StatTicker` | Static, horizontally overflow-scrollable workspace stat strip with an optional trailing CTA; no auto-scroll marquee (ploy-capture recomposition). The Overview stat strip captured off ploy.ai (behavior spec: -2, — `overview-ticker` "-viewport"/"-track"/"-segment"/"-value"/"-cta"). | `import { StatTicker } from "@working-theory/ui/blocks"` |
+| `Steps` | The numbered install/guide walkthrough: an ordered list of `Step` items, each a zero-padded number marker + an optional per-step heading + body, joined top-to-bottom by a connecting vertical rule. The classic docs "follow these steps" surface, rendered from `@working-theory/ui` so docs pages stay design-system citizens. | `import { Steps } from "@working-theory/ui/blocks"` |
+| `StreamingMessage` | One chat turn's message rendering, per the ploy.ai capture contract. | `import { StreamingMessage } from "@working-theory/ui/blocks"` |
+| `StripeActionButton` | Checkout/portal entry-point trigger with pending + test-mode affordances. The checkout/portal entry-point action button shared by the checkout (U2) and billing-portal (U6) surfaces. | `import { StripeActionButton } from "@working-theory/ui/blocks"` |
+| `SubscriptionStatus` | Current plan + lifecycle state for the subscriptions surface — shows state via U1's `PaymentStatusBadge` plus a portal "Manage" action. | `import { SubscriptionStatus } from "@working-theory/ui/blocks"` |
+| `SuggestionChipCarousel` | A 3-6 icon-chip row with exactly one chip expanded (muted category + bold prompt), auto-rotating motion-safe with hover/focus pause; a click hands the chip's prompt to the host. A row of 3-6 icon chips in which exactly ONE is expanded at a time. | `import { SuggestionChipCarousel } from "@working-theory/ui/blocks"` |
+| `TableOfContents` | The shared "On this page" rail consumed by the docs shell and the blog post layout (do not couple it to docs-only context). Renders a flat list of heading anchors and scroll-spies the heading currently in view, highlighting the matching item. | `import { TableOfContents } from "@working-theory/ui/blocks"` |
+| `TeamMemberCard` | Renders one team member in either of two layout modes: 'inline' — small circular avatar left + name/role right (with-small-images variant) 'stacked' — large circular avatar top + name/role/social-links below (with-large-images variant). | `import { TeamMemberCard } from "@working-theory/ui/blocks"` |
+| `TestimonialAside` | For ContactForm 'with-testimonial' variant. Rating (optional 0–5): rendered via Rating primitive with accessible label. avatar (optional): composed via Avatar + AvatarFallback + AvatarImage (initials fallback). | `import { TestimonialAside } from "@working-theory/ui/blocks"` |
+| `UserBlock` | Position-agnostic identity/account trigger block: avatar + primary label + optional secondary line, with density/affordance/collapsed/truncation variants. A single focusable button-rooted element that forwardRef's + spreads props so DropdownMenuTrigger asChild (AccountMenu) can clone it as its trigger anchor. | `import { UserBlock } from "@working-theory/ui/blocks"` |
+| `VerifyCodeField` | Presentational code-entry unit for StepFlow's `verify` step type: a status line ("We sent a code to…"), a 6-digit numeric code Field, and a resend link. Composes existing Field/Input/Button/Text primitives — no bespoke markup, no new primitive. | `import { VerifyCodeField } from "@working-theory/ui/blocks"` |
+| `VersionHistory` | Day-grouped auto-saved version list with a "Current" marker — reimplements the ploy.ai artifact-editor Versions capture ("10 auto-saved versions", grouped by day, `Current` on one entry). Purely presentational and props-driven: renders the grouped list only. Designed to be embedded inside a popover by a higher tier — this block does NOT render the popover/trigger itself. | `import { VersionHistory } from "@working-theory/ui/blocks"` |
+| `VersionSwitcher` | Version-dropdown block for brand lockup accessory slots. Renders the current version label as a Badge-styled trigger pill that opens a DropdownMenu of older available versions. Designed for use in the `brandAccessory`/`badge` slot of Nav and BrandLogo so both surfaces render the version accessory identically from a single shared source. | `import { VersionSwitcher } from "@working-theory/ui/blocks"` |
+| `VideoEmbed` | The shared video player: poster + large Play affordance (click, default) or muted autoplay with native controls, reduced-motion-aware. 'click' (default) — the acquisition.com thank-you pattern: a poster image with a large, labeled Play affordance. Nothing plays, nothing is fetched, until the visitor activates it — the video element itself only mounts on activation. | `import { VideoEmbed } from "@working-theory/ui/blocks"` |
+| `VideoLightbox` | The shared video player, presented as a DIALOG. A trigger (a poster thumbnail, a "Watch the video" button — any focusable element the caller supplies) opens the SAME VideoEmbed inside a Radix Dialog on a dimmed/blurred backdrop. | `import { VideoLightbox } from "@working-theory/ui/blocks"` |
+| `VideoPlaceholder` | The true-to-size, play-marked placeholder a declared VIDEO slot renders when no source has been supplied yet — the video-flavored sibling of `MediaPlaceholder`: a circle-with-centered-triangle play mark (mirroring `VideoEmbed`'s own poster/Play affordance styling) inside a dashed aspect box sized to the SAME `ratio` the real player would use, so swapping in a real source never shifts the slot's footprint. | `import { VideoPlaceholder } from "@working-theory/ui/blocks"` |
+
+---
+
+## Chrome (18)
+
+Persistent framing UI that wraps page content — navigation, footers, sidebars, banners. Not MDX-driven.
+
+Import: `import { X } from "@working-theory/ui/chrome";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `AccountMenu` | Auth-agnostic account dropdown (theme + settings + admin + sign-out). Composes the DropdownMenu primitive (Radix-backed — positioning, click-outside, Escape, focus management, and roving keyboard nav all come for free) with the Icon, Link, and ThemeToggle primitives. AccountMenu carries NO session, routing, or sign-out logic of its own: every behaviour arrives via props, so the same component serves any auth stack. | `import { AccountMenu } from "@working-theory/ui/chrome"` |
+| `ArtifactToolbar` | Chrome-tier artifact-canvas toolbar (ploy-capture recomposition). Reimplements the captured ploy.ai artifact-canvas toolbar: artifact tab strip ("All outputs" gallery tab + per-artifact tabs with close ×) · Preview/Code toggle · Select (element-pick) toggle · history back/forward · a read-only path bar · responsive-viewport cycle · refresh · Versions dropdown trigger · Publish. | `import { ArtifactToolbar } from "@working-theory/ui/chrome"` |
+| `Banner` | Site-wide announcement and consent banner chrome. *(weak)* | `import { Banner } from "@working-theory/ui/chrome"` |
+| `BannerConsentIsland` | Accept / Reject action cluster for the consent Banner. Isolated to "use client" so Banner stays RSC. The onAccept / onReject callbacks must be Server Actions when used inside an RSC tree; they may be regular functions in client contexts (Storybook, testing). *(weak)* | internal — compose from `packages/ui/src/chrome/BannerConsentIsland.tsx` |
+| `BannerDismissIsland` | Isolated to "use client" so Banner (Server Component) stays RSC. Mirrors the Nav / NavMobileMenu split: interactivity is contained here. Rendering: wraps its children in a relative-positioned div and absolutely places the × dismiss button at the end (RTL-safe: `end-4`) of the bar. *(weak)* | internal — compose from `packages/ui/src/chrome/BannerDismissIsland.tsx` |
+| `DocsSidebar` | The left documentation rail. Consumes a `tree` prop (structurally a Fumadocs `source.pageTree` Root) and renders its folders (static section groups), pages (links), and separators (section captions / dividers). The current page is highlighted via `aria-current="page"`. Kept repo-agnostic: the route passes `docsSource.pageTree`; no nav data is hardcoded here, so a fork reuses it unchanged. | `import { DocsSidebar } from "@working-theory/ui/chrome"` |
+| `FacetNav` | Chrome-tier faceted secondary navigation (ploy-capture recomposition). One reusable component servicing THREE captured consumers: Settings' grouped Org/Workspace nav, Assets' All + tag-facet counts, and Docs' All + folder tree + tag facets. | `import { FacetNav } from "@working-theory/ui/chrome"` |
+| `FloatingCta` | Persistent fixed corner action pill. *(weak)* | `import { FloatingCta } from "@working-theory/ui/chrome"` |
+| `Footer` | Site footer server component with secondary nav links. Label resolution order for navItems labels. Resolved labels are passed into FooterNav as pre-resolved strings — no duplicated resolution logic across variants. | `import { Footer } from "@working-theory/ui/chrome"` |
+| `Nav` | Primary navigation server component with locale-aware links. Three layout variants supported via `navAlignment`. Flyout (mega-menu) items: the desktop link list is ALWAYS a single SectionNav render path — there is no Path A/B fork. | `import { Nav } from "@working-theory/ui/chrome"` |
+| `NavMobileMenu` | Client subcomponent for mobile hamburger state. Isolates "use client" to this narrow component so Nav (Server Component) stays clean. Renders a hamburger button + collapsible link list. Closes the menu automatically when the pathname changes (route navigation). *(weak)* | internal — compose from `packages/ui/src/chrome/NavMobileMenu.tsx` |
+| `NavOverflowMenu` | The Nav row's per-breakpoint link-overflow disclosure. The desktop link row never wraps: a fixed per-breakpoint inline-link budget (4 at md, 6 at lg+) is enforced by the caller (Nav), which splits `navItems` into an inline slice and an overflow slice. This component renders ONLY the overflow slice, behind a disclosure trigger, in source order — it never computes the budget itself. | internal — compose from `packages/ui/src/chrome/NavOverflowMenu.tsx` |
+| `NotificationsMenu` | Bell trigger + notifications popover chrome (ploy-capture app-frame). Presentational, props-driven. The unread count and row list arrive entirely via props — this component carries NO fetch/polling logic of its own. Rows are pre-formatted at the call site (relative time, heading, empty copy) per the AILK i18n/formatting convention (design-system-rules Rule 10). | `import { NotificationsMenu } from "@working-theory/ui/chrome"` |
+| `SectionNav` | Chrome-tier route-aware section navigation. A horizontal, tab-styled section nav promoting Working Theory's bespoke `UnifiedTabs`/`TheoriesTabs` to a tokenized, tier-correct AILK component. | `import { SectionNav } from "@working-theory/ui/chrome"` |
+| `SidebarNav` | Application sidebar rail (nav + teams + user) for dashboard shells. Server Component (RSC). Renders the vertical sidebar rail for application-shell layouts. Used as the `sidebar` prop of DashboardShell. Wrap in a FixedPanel (panels tier) to get the expanded ↔ rail ↔ hidden state machinery. Independently reusable in future shells (settings, analytics, etc.). *(weak)* | `import { SidebarNav } from "@working-theory/ui/chrome"` |
+| `SidebarNavRailItems` | Client boundary for the collapsed rail tooltip affordance. Isolated "use client" boundary so SidebarNav itself stays a Server Component. Renders icon-only nav links with Tooltip labels when the rail is collapsed. *(weak)* | internal — compose from `packages/ui/src/chrome/SidebarNavRailItems.tsx` |
+| `SidePanel` | Chrome-tier right-edge content panel. Fills the ResizablePanel right-edge slot in AppShell. Provides a rich header (title / subtitle / type-badge / avatar / actions / close), a scrollable body, and an optional footer. Mirrors how SidebarNav fills the left edge. | `import { SidePanel } from "@working-theory/ui/chrome"` |
+| `WorkspaceSwitcher` | Org/workspace switcher chrome (ploy-capture app-frame). Presentational, props-driven. Tenancy data (org, user, workspace list, credit meters, actions) arrives entirely via the optional `tenancy` prop — this component carries NO fetch/session logic of its own. When `tenancy` is absent it degrades cleanly to a static, non-interactive single-tenant identity row: no popover, no chevron, no menu semantics. | `import { WorkspaceSwitcher } from "@working-theory/ui/chrome"` |
+
+---
+
+## Primitives (79)
+
+The base control and text vocabulary — Button, Heading, Text, Link, Icon, Input, Dialog, Command, Tooltip, ThemeToggle and the rest. This is the only tier allowed to render raw HTML elements; every tier above it composes these instead. Search here before building any low-level control.
+
+Import: `import { X } from "@working-theory/ui/primitives";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `Accordion` | Collapsible panel set built on @radix-ui/react-accordion. | `import { Accordion } from "@working-theory/ui/primitives"` |
+| `Alert` | Contextual status message for user feedback. Supports four semantic variants (default, error, warning, success, info) that map to AILK Brand 1.3 status tokens. | `import { Alert } from "@working-theory/ui/primitives"` |
+| `AlertBanner` | Full-width status or promotional banner strip. Renders a horizontally-centered, full-width bar for site-level notices: informational, success, warning, error, and promotional messages. | `import { AlertBanner } from "@working-theory/ui/primitives"` |
+| `AlertDialog` | Confirmation overlay composed from @radix-ui/react-alert-dialog. Unlike Dialog, AlertDialog traps focus and requires the user to explicitly confirm or cancel before dismissing — appropriate for destructive actions. | `import { AlertDialog } from "@working-theory/ui/primitives"` |
+| `AlertDot` | Colored status dot with optional notification count. Use on integration cards, avatars, or any icon needing inline status indication. Pass `count` to render a capped badge (e.g. "99+") instead of a plain dot. Announces status to assistive technology via role="status" and a caller-supplied aria-label (required by accessibility contract). | `import { AlertDot } from "@working-theory/ui/primitives"` |
+| `AspectRatio` | Constrains content to a given width/height ratio. Thin re-export of @radix-ui/react-aspect-ratio. RSC-safe: no hooks or browser APIs — default server component. *(weak)* | `import { AspectRatio } from "@working-theory/ui/primitives"` |
+| `Avatar` | Circular or square user/company avatar with image, initials, or icon fallback. | `import { Avatar } from "@working-theory/ui/primitives"` |
+| `Badge` | Inline label chip with semantic status variants and size scale. | `import { Badge } from "@working-theory/ui/primitives"` |
+| `Breadcrumb` | Navigation primitive that renders an ordered wayfinding trail with accessible current-page marking and logical-direction separators. | `import { Breadcrumb } from "@working-theory/ui/primitives"` |
+| `Button` | `&lt;button>` (or any element via `asChild`) with cva variant + size styling via @working-theory/theme tokens. | `import { Button } from "@working-theory/ui/primitives"` |
+| `Calendar` | Date picker built on react-day-picker with AILK semantic tokens. | `import { Calendar } from "@working-theory/ui/primitives"` |
+| `Checkbox` | Accessible checkbox control backed by @radix-ui/react-checkbox. Renders a 16×16 checkbox with a Check icon when checked. Supports disabled state, custom className, and all Radix Checkbox.Root props. | `import { Checkbox } from "@working-theory/ui/primitives"` |
+| `ChipInput` | Row of dismissible chips with an optional add button. | `import { ChipInput } from "@working-theory/ui/primitives"` |
+| `CitationMarker` | Inline citation/source marker for agent-generated content. Renders a compact numbered or labeled source reference inline with text. Used alongside AI-generated content to surface provenance for individual claims. | `import { CitationMarker } from "@working-theory/ui/primitives"` |
+| `Code` | Code inline primitive — renders a semantic &lt;code> for code/variable spans inside prose. Inline sibling of Text. | `import { Code } from "@working-theory/ui/primitives"` |
+| `Collapsible` | Thin re-export of the Radix Collapsible root and content parts, plus the styled CollapsibleTrigger button. | `import { Collapsible } from "@working-theory/ui/primitives"` |
+| `Command` | Keyboard-navigable command palette / search input. Thin wrapper over the `cmdk` library (Command component) with AILK semantic token styling. Provides the full sub-component set: Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut. | `import { Command } from "@working-theory/ui/primitives"` |
+| `ConfidenceIndicator` | Accessible confidence-level badge for AI-generated claims. Bound to the `@working-theory/validation` confidence shape: confidence_level = "low" \| "medium" \| "high" This matches the `overallConfidence` enum in market-landscape-summary and canonical-messaging-summary schemas, and the free-text `confidence_level` on HypothesisClaim. | `import { ConfidenceIndicator } from "@working-theory/ui/primitives"` |
+| `Container` | _no description in source — read `packages/ui/src/primitives/Container.tsx`_ | `import { Container } from "@working-theory/ui/primitives"` |
+| `ContextMenu` | Right-click / long-press contextual action menu. Thin wrapper over @radix-ui/react-context-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, Trigger, Portal, Content, Group, Label, Item, CheckboxItem, RadioGroup, RadioItem, ItemIndicator, Separator, Sub, SubTrigger, SubContent, Shortcut. | `import { ContextMenu } from "@working-theory/ui/primitives"` |
+| `CopyButton` | CopyButton Primitive. *(weak)* | `import { CopyButton } from "@working-theory/ui/primitives"` |
+| `Delta` | Sign-driven semantic indicator for numeric change. *(weak)* | `import { Delta } from "@working-theory/ui/primitives"` |
+| `Dialog` | Modal overlay composed from @radix-ui/react-dialog. *(weak)* | `import { Dialog } from "@working-theory/ui/primitives"` |
+| `DropdownMenu` | Contextual action menu anchored to a trigger. Thin wrapper over @radix-ui/react-dropdown-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, Trigger, Portal, Content, Group, Label, Item, CheckboxItem, RadioGroup, RadioItem, ItemIndicator, Separator, Sub, SubTrigger, SubContent, Shortcut. | `import { DropdownMenu } from "@working-theory/ui/primitives"` |
+| `EmptyState` | Purposeful empty / zero-item state indicator. Distinct from loading (`Skeleton`, `SectionSkeleton`) and error (`SectionErrorBoundary`) states. Use `EmptyState` when content is absent by design (no items yet, no search results, no activity), not when content is loading or a render error occurred. | `import { EmptyState } from "@working-theory/ui/primitives"` |
+| `Field` | Composes Label + a control slot + helper/error text. | `import { Field } from "@working-theory/ui/primitives"` |
+| `Form` | `preventDefault` + native Validity State + ARIA wiring. | `import { Form } from "@working-theory/ui/primitives"` |
+| `GradientText` | Mechanism (pure CSS, no client JS): the `.gt-text` utility in `@working-theory/theme`'s tokens.css sets `background-image: var(gradient-brand)` plus `background-clip: text` + transparent fill, so the gradient shows through the glyphs. That is the SAME technique `ShimmerText` uses via `.st-text`, minus the sweep: no `background-size` stretch, no `@keyframes`, no animate companion class. | `import { GradientText } from "@working-theory/ui/primitives"` |
+| `Heading` | _no description in source — read `packages/ui/src/primitives/Heading.tsx`_ | `import { Heading } from "@working-theory/ui/primitives"` |
+| `HoverCard` | Floating card revealed on hover, built on @radix-ui/react-hover-card. Exports Root, Trigger, and Content. The trigger is typically an anchor or interactive element; the content floats alongside it on pointer hover/focus. | `import { HoverCard } from "@working-theory/ui/primitives"` |
+| `Icon` | Single rendering path for Lucide UI icons and brand/channel logos (Simple Icons raw paths). | `import { Icon } from "@working-theory/ui/primitives"` |
+| `Image` | Wraps `next/image` and closes foot-guns at the type level. | `import { Image } from "@working-theory/ui/primitives"` |
+| `InlineMessage` | Quiet helper/error/warning text for forms. | `import { InlineMessage } from "@working-theory/ui/primitives"` |
+| `Input` | Single-line text input with variant styling. Supports default, warning, and error validation states, three size variants, and optional leading/trailing icon slots. | `import { Input } from "@working-theory/ui/primitives"` |
+| `Label` | Form field label with peer-disabled state styling. Wraps @radix-ui/react-label for correct association with form controls via `htmlFor`. Automatically dims and shows a not-allowed cursor when the associated control carries the `disabled` attribute (peer-disabled). | `import { Label } from "@working-theory/ui/primitives"` |
+| `Link` | _no description in source — read `packages/ui/src/primitives/Link.tsx`_ | `import { Link } from "@working-theory/ui/primitives"` |
+| `LoaderRing` | Compact loading-animation indicator. Renders the three loading animations (spinner, dots, check-transition) and, for terminal status, composes the shared StatusBadge primitive (success/error/warning). Sizes track the AILK icon-size token scale; all colors are AILK Brand 1.3 semantic tokens. | `import { LoaderRing } from "@working-theory/ui/primitives"` |
+| `Menubar` | Horizontal application menu bar with keyboard navigation. | `import { Menubar } from "@working-theory/ui/primitives"` |
+| `MenuItem` | Interactive menu item for dropdowns, context menus, etc. Full-width, left-aligned button with support for left/right icons, secondary text, selection state, and destructive variant. | `import { MenuItem } from "@working-theory/ui/primitives"` |
+| `MoneyAmount` | Locale-aware currency display. *(weak)* | `import { MoneyAmount } from "@working-theory/ui/primitives"` |
+| `NavigationMenu` | Accessible site navigation with flyout content. Thin wrapper over @radix-ui/react-navigation-menu with AILK semantic token styling. Provides the full Radix sub-component set: Root, List, Item, Trigger, Content, Link, Viewport, Indicator. | `import { NavigationMenu } from "@working-theory/ui/primitives"` |
+| `Pagination` | • Link mode (default, RSC-safe) — prev/next render as `&lt;a>` links built from `baseUrl` (`?page=N`); the inactive boundary control is a disabled `&lt;span>`. This is the original behaviour and is unchanged. | `import { Pagination } from "@working-theory/ui/primitives"` |
+| `PanelEdgeHandle` | Presentational primitive (Primitives tier, Tier 1). A full-height vertical edge handle with a ≥44px touch target (min-w-11). Used by tier-2 panels as the interactive edge handle — FixedPanel (collapse/expand) and ResizablePanel (drag-resize). | `import { PanelEdgeHandle } from "@working-theory/ui/primitives"` |
+| `Popover` | Floating content panel anchored to a trigger. Thin wrapper over @radix-ui/react-popover with AILK semantic token styling. Provides: Popover (root), PopoverTrigger, PopoverAnchor, PopoverContent, PopoverClose — the full Radix sub-component set. | `import { Popover } from "@working-theory/ui/primitives"` |
+| `Progress` | Wraps @radix-ui/react-progress with AILK token-driven styling. Supports three size variants (sm, md, lg) and two track colors (default, secondary). The indicator fill switches to the success emphasis token when `isComplete` is true. | `import { Progress } from "@working-theory/ui/primitives"` |
+| `ProgressRing` | Circular SVG progress indicator. Renders a ring (stroke arc) or pie (filled wedge) progress meter, plus success/error/warning filled-ring status states that mirror LoaderRing's status variants for consistent visual language. | `import { ProgressRing } from "@working-theory/ui/primitives"` |
+| `ProvenanceBadge` | Agent/human/system authorship chip with optional audit id. | `import { ProvenanceBadge } from "@working-theory/ui/primitives"` |
+| `RadioGroup` | Accessible radio button group backed by @radix-ui/react-radio-group. Exports RadioGroup (Root) and RadioGroupItem. The Root renders as a grid with gap-2 by default; items are 16×16 px filled circles. | `import { RadioGroup } from "@working-theory/ui/primitives"` |
+| `Rating` | Renders star icons for a 0–5 numeric rating, with full and half-star support and an accessible aria-label. | `import { Rating } from "@working-theory/ui/primitives"` |
+| `ScrollArea` | Custom-styled scroll container built on @radix-ui/react-scroll-area. Exposes ScrollArea (Root + Viewport + Corner composite) and ScrollBar as separately composable sub-components. | `import { ScrollArea } from "@working-theory/ui/primitives"` |
+| `SearchInputTrigger` | It is NOT search-or hero-specific: every visual axis (height, width, corner radius, background, border, placeholder, shortcut hint) is a token-driven prop so the same control can be restyled per placement. It does not own a real &lt;input>; clicking it (or pressing the hinted shortcut) fires `onClick`, which the caller wires to open a Command palette. | `import { SearchInputTrigger } from "@working-theory/ui/primitives"` |
+| `SectionErrorBoundary` | Wraps any section in a render-error containment layer. When a child throws during render, the boundary catches the error, logs it, and renders `&lt;SectionSkeleton>` as the fallback. | `import { SectionErrorBoundary } from "@working-theory/ui/primitives"` |
+| `SectionSkeleton` | Minimal animated placeholder block. Used as the default fallback by SectionErrorBoundary and as a loading skeleton in suspense-enabled section consumers. Renders a single animated rectangle respecting an optional aspect-ratio and className. | `import { SectionSkeleton } from "@working-theory/ui/primitives"` |
+| `SegmentedControl` | A compact single-select pill group with radiogroup semantics. | `import { SegmentedControl } from "@working-theory/ui/primitives"` |
+| `SegmentedProgress` | Discrete N-segment progress indicator. Renders `max` equal-width rounded bars in a row; the first `value` segments render filled (brand fill token), the remainder render as unfilled track segments. Distinct from the continuous `Progress` primitive (a single sliding-fill track) — use SegmentedProgress for step/checklist-style progress such as an onboarding checklist or a multi-step wizard. | `import { SegmentedProgress } from "@working-theory/ui/primitives"` |
+| `Select` | Accessible dropdown select backed by @radix-ui/react-select. Exports the full Radix sub-component set: Select (Root), SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectLabel, SelectItem, SelectSeparator. | `import { Select } from "@working-theory/ui/primitives"` |
+| `Separator` | Thin divider line between content regions. | `import { Separator } from "@working-theory/ui/primitives"` · `packages/ui/src/primitives/Separator.tsx` |
+| `Sheet` | Slide-out panel anchored to any viewport edge. | `import { Sheet } from "@working-theory/ui/primitives"` |
+| `ShimmerText` | Mechanism (pure CSS, no client JS). All configurable values flow as CSS custom properties via the style prop so they are tunable at call-site without arbitrary Tailwind values. | `import { ShimmerText } from "@working-theory/ui/primitives"` |
+| `ShortcutTrigger` | Button-family primitive: a compact icon trigger with an optional keyboard-shortcut hint (e.g. ⌘K). | `import { ShortcutTrigger } from "@working-theory/ui/primitives"` |
+| `Skeleton` | Animated placeholder shown while content is loading. | `import { Skeleton } from "@working-theory/ui/primitives"` |
+| `Slider` | Range input built on @radix-ui/react-slider. Exposes the full Radix sub-component set (Root, Track, Range, Thumb) for composition, and provides a pre-composed &lt;Slider> default. | `import { Slider } from "@working-theory/ui/primitives"` |
+| `SplitButton` | A main action button paired with a dropdown trigger. *(weak)* | `import { SplitButton } from "@working-theory/ui/primitives"` |
+| `StatusBadge` | Colored circle + glyph status indicator. *(weak)* | `import { StatusBadge } from "@working-theory/ui/primitives"` |
+| `Surface` | Establishes a color-token context for its subtree. The `emphasis` variant marks the wrapper with `data-surface="emphasis"`, which remaps the theme-flipping semantic color tokens to their dark-palette values within the subtree (see the [data-surface="emphasis"] rule in @working-theory/theme/tokens.css). | `import { Surface } from "@working-theory/ui/primitives"` |
+| `Switch` | A toggleable on/off control built on @radix-ui/react-switch. | `import { Switch } from "@working-theory/ui/primitives"` |
+| `Table` | Semantic HTML table with token-driven styling. Exposes Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, and TableCaption as composable sub-components. | `import { Table } from "@working-theory/ui/primitives"` |
+| `Tabs` | Radix-backed tablist/tab/tabpanel with optional per-tab count badges and an optional "More ▾" overflow menu. | `import { Tabs } from "@working-theory/ui/primitives"` · `packages/ui/src/primitives/Tabs.tsx` |
+| `Text` | _no description in source — read `packages/ui/src/primitives/Text.tsx`_ | `import { Text } from "@working-theory/ui/primitives"` |
+| `Textarea` | Multi-line text input with variant styling. Supports default, warning, and error validation states and three size variants. Compose with &lt;Label> and &lt;Form> for accessible form fields. | `import { Textarea } from "@working-theory/ui/primitives"` |
+| `ThemeToggle` | Stateful 3-state theme owner. *(weak)* | `import { ThemeToggle } from "@working-theory/ui/primitives"` |
+| `ThemeToggleView` | 3-state icon segmented control. A presentational, controlled component. It renders what `value` says and calls `onChange` when the user picks a different mode. All theme persistence (cookies, DOM attribute writes) is the responsibility of the stateful owner {@link ThemeToggle}. | internal — compose from `packages/ui/src/primitives/ThemeToggleView.tsx` |
+| `TimePicker` | Time-of-day selector with 12h/24h formats. A dropdown of time slots (48 per day at the default 30-minute step), NOT an analog clock face. Composes the Select primitive — the generated slots render as Select options, inheriting Select's combobox/listbox a11y, keyboard, type-ahead, and styling (incl. the corner-radius fix). | `import { TimePicker } from "@working-theory/ui/primitives"` |
+| `Toast` | Radix-backed transient notification system. *(weak)* | `import { Toast } from "@working-theory/ui/primitives"` |
+| `Toaster` | Renders the toast viewport and maps queued toasts from `useToast` into individual `&lt;Toast>` instances. | `import { Toaster } from "@working-theory/ui/primitives"` |
+| `Toggle` | Toggle Primitive. *(weak)* | `import { Toggle } from "@working-theory/ui/primitives"` |
+| `Tooltip` | Radix-backed floating label anchored to a trigger element. | `import { Tooltip } from "@working-theory/ui/primitives"` |
+| `VisuallyHidden` | Renders its children so they are present in the DOM and the accessibility tree but visually hidden. Standardizes the ad-hoc `sr-only` className pattern previously hand-rolled across primitives (Dialog/Sheet/Toast close labels) and section headers. *(weak)* | `import { VisuallyHidden } from "@working-theory/ui/primitives"` |
+| `WorkingIndicator` | Renders the authentic Claude Code "working" indicator: a glyph that blooms frame-by-frame from a middle dot through increasingly complex Unicode star shapes to a full-star, then resets. Beside it sits a steady-colored label ("Thinking…" by default). | `import { WorkingIndicator } from "@working-theory/ui/primitives"` |
+
+---
+
+## Panels (7)
+
+Reusable layout containers that own their own interaction state (collapse, rail, drag-to-resize, off-canvas drawer below `lg`). Not page shells — composable containers that sit between primitives and blocks.
+
+Import: `import { X } from "@working-theory/ui/panels";` (or from the `@working-theory/ui` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `CardGrid` | The shared owner of how card-grid cells are arranged and separated — columns, gap, and the inter-cell SEPARATION treatment. Seven sections (BentoGrid, Items, Pricing, SocialProof, Stats, Testimonials, Team) currently hand-roll `grid gap-grid grid-cols-*`; this panel is the foundation they compose instead, the direct analogue of how `SectionFrame` collapsed 23× frame duplication. | `import { CardGrid } from "@working-theory/ui/panels"` |
+| `FixedPanel` | Collapsible layout-container primitive (Tier 2 — Panels). A three-state panel: expanded ↔ rail ↔ hidden. Controlled only — callers manage state via `state` + `onStateChange`. | `import { FixedPanel } from "@working-theory/ui/panels"` |
+| `FlowFrame` | The // frame: a full-viewport ground on the site `bg` token, two 50/50 regions (a persistent side panel + an active region) that stack below `md:` (side panel first, in DOM and visual order), and a bottom bar pinned to the VISIBLE viewport (`position: fixed`, safe-area aware) carrying a single continuous accent progress line, `leading` / `label` (center) / `trailing` slots, and a prop-controlled "Powered by Working Theory" line. *(weak)* | `import { FlowFrame } from "@working-theory/ui/panels"` |
+| `InvoiceDetail` | A single invoice's detail view, for the invoice surface (U4). Capability-bearing: binds a schema.org `Invoice` resource-payload fragment (imported from `@working-theory/schema`) — so a co-located `.text.ts` + `.text.test.ts` renderer is required and gated by `scripts/check-ax-parity.sh`. | `import { InvoiceDetail } from "@working-theory/ui/panels"` |
+| `ResizablePanel` | Drag-resizable layout-container primitive (Panels tier, Tier 2). Provides a resizable side panel container for layout composition. The panel width is controlled by the parent via `width` + `onWidthChange`/`onWidthChangeEnd`. The panel itself manages the drag interaction; the parent persists the committed width (e.g. via localStorage or server state). | `import { ResizablePanel } from "@working-theory/ui/panels"` |
+| `SectionFrame` | The shared frame the section tier composes instead of hand-rolling the `SectionErrorBoundary` + `&lt;section className="py-section bg-bg">` + `Container` plumbing (23× duplicated at time). | `import { SectionFrame } from "@working-theory/ui/panels"` |
+| `StickyColumn` | Makes one column of a two-column layout stick (`lg:sticky` with a top offset) while the sibling column scrolls — the HubSpot "left header sticks, right content scrolls" pattern. `lg`-only: below `lg` it is NOT sticky (normal flow, stacks). Consumed by SplitContentMedia; reusable by any two-column layout. | `import { StickyColumn } from "@working-theory/ui/panels"` |
+
+---
+
+## Shells (8)
+
+Route-level slot-frames — the outermost layout a page is placed into. They supply geometry and slots (nav / sidebar / main / footer), not content: you inject the real Nav, Footer and sidebar. A different package from every tier above: `@working-theory/templates`.
+
+Import: `import { X } from "@working-theory/templates/shells";` (or from the `@working-theory/templates` root barrel). Components marked *internal* are not re-exported — they are implementation details of a sibling in the same tier.
+
+| Component | What it does | How to use it |
+| --- | --- | --- |
+| `AdminShell` | @deprecated; use PortalShell with your own navItems. Internal admin dashboard layout shell. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. | `import { AdminShell } from "@working-theory/templates/shells"` |
+| `AppShell` | Shared authed-app base frame. Layout ownership: AppShell is the SINGLE owner of the authed sidebar frame layout. The `sidebar` prop is CONTENT (e.g. a &lt;SidebarNav>), never a layout component. Do NOT pass SidebarShell or FixedPanel as the sidebar — that nests two incompatible layout systems (a fixed-width shell vs a variable-width panel). | `import { AppShell } from "@working-theory/templates/shells"` |
+| `ArtifactEditorShell` | Chat + artifact-canvas split-view slot-frame. Recomposes the ploy.ai Ploy Editor capture: a chat-driven artifact editor whose split view is LEFT = chat pane (conversation + composer) and RIGHT = artifact canvas (toolbar + preview/code), behind a drag-resizable divider. A blank session is chat-only, full width, until an artifact exists — then the canvas panel slides in. | `import { ArtifactEditorShell } from "@working-theory/templates/shells"` |
+| `BlogShell` | Blog reading **slot-frame** (DOCS-UI-8). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (Nav/Footer) and content (the post meta rail + the reconciled BlogPost body) **fill** the slots — nothing is baked in. Peer to MarketingShell / DocsShell; see. *(weak)* | `import { BlogShell } from "@working-theory/templates/shells"` |
+| `DocsShell` | Documentation reading **slot-frame** (DOCS-UI-4). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (DocsSidebar) and content (DocsArticleHeader + MDXContent + ArticlePager + DocsFeedback) **fill** the slots — nothing is baked in. Peer to MarketingShell; see. *(weak)* | `import { DocsShell } from "@working-theory/templates/shells"` |
+| `MarketingShell` | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). *(weak)* | `import { MarketingShell } from "@working-theory/templates/shells"` |
+| `PortalShell` | Customer-facing portal (sidebar + branded top chrome + main);. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. *(weak)* | `import { PortalShell } from "@working-theory/templates/shells"` |
+| `WorkspaceShell` | Application sidebar shell (thin AppShell composition);. Props are intentionally identical to the old DashboardShellProps — no additions beyond what AppShell provides — so any fork using DashboardShell can swap the import without changes. *(weak)* | `import { WorkspaceShell } from "@working-theory/templates/shells"` |
+
+---
+
+## Weak descriptions
+
+These 30 components have a description that is accurate but does not do the job well: too short to match against, or long but spent on implementation. A capability search reaches them only if the searcher's word happens to be in it, so they are the most likely place for this catalog to repeat the failure it was built to fix. Read the source before concluding the capability is absent — and if you own one of these components, its header is the fix.
+
+| Component | Tier | What the source gives us |
+| --- | --- | --- |
+| `DocumentViewerClient` | sections | The interactive shell for DocumentViewer. Split out of DocumentViewer.tsx (which stays RSC) for the same reason AlertSection composes AlertSectionDismissIsland: interactivity is contained to one client island. |
+| `AgentContextCard` | blocks | Capability-bearing block that renders agent provenance. RSC note: no hooks or browser APIs — server-renderable by default. |
+| `PageHeader` | blocks | RSC. Page-level header composing the Breadcrumb primitive for the left-side wayfinding trail, a generic right-side `actions` slot, and an optional `switcher` slot for header-owned segment switching. Fills AppShell's `header` slot (DashboardShell and similar). No accent bar. No tab API. No named action props — the caller assembles whatever button/menu nodes it needs and passes them as `actions`. |
+| `PricingTierCardSeatControl` | blocks | Seat-count range picker for the Team tier card. Renders a Select primitive that lets the user choose an "Up to N seats" option from a caller-supplied list of numbers. The parent PricingTierCard stays a pure RSC; only this tiny island is hydrated. Pattern mirrors PageHeaderSwitcher.tsx: small "use client" island imported by an otherwise-server-rendered parent, keeping the client bundle minimal. |
+| `SinglePriceCard` | blocks | 2-column split card for the Pricing 'single-price-with-details' variant. |
+| `SocialIcons` | blocks | Horizontal row of social icon links. Renders brand icons (via Icon primitive + simple-icons paths) inside accessible Link primitives. Each platform link gets an aria-label. Shared by company-mission, simple-centered, and newsletter-below footer variants, and composed by TeamMemberCard for member social links. |
+| `Banner` | chrome | Site-wide announcement and consent banner chrome. |
+| `BannerConsentIsland` | chrome | Accept / Reject action cluster for the consent Banner. Isolated to "use client" so Banner stays RSC. The onAccept / onReject callbacks must be Server Actions when used inside an RSC tree; they may be regular functions in client contexts (Storybook, testing). |
+| `BannerDismissIsland` | chrome | Isolated to "use client" so Banner (Server Component) stays RSC. Mirrors the Nav / NavMobileMenu split: interactivity is contained here. Rendering: wraps its children in a relative-positioned div and absolutely places the × dismiss button at the end (RTL-safe: `end-4`) of the bar. |
+| `FloatingCta` | chrome | Persistent fixed corner action pill. |
+| `NavMobileMenu` | chrome | Client subcomponent for mobile hamburger state. Isolates "use client" to this narrow component so Nav (Server Component) stays clean. Renders a hamburger button + collapsible link list. Closes the menu automatically when the pathname changes (route navigation). |
+| `SidebarNav` | chrome | Application sidebar rail (nav + teams + user) for dashboard shells. Server Component (RSC). Renders the vertical sidebar rail for application-shell layouts. Used as the `sidebar` prop of DashboardShell. Wrap in a FixedPanel (panels tier) to get the expanded ↔ rail ↔ hidden state machinery. Independently reusable in future shells (settings, analytics, etc.). |
+| `SidebarNavRailItems` | chrome | Client boundary for the collapsed rail tooltip affordance. Isolated "use client" boundary so SidebarNav itself stays a Server Component. Renders icon-only nav links with Tooltip labels when the rail is collapsed. |
+| `AspectRatio` | primitives | Constrains content to a given width/height ratio. Thin re-export of @radix-ui/react-aspect-ratio. RSC-safe: no hooks or browser APIs — default server component. |
+| `CopyButton` | primitives | CopyButton Primitive. |
+| `Delta` | primitives | Sign-driven semantic indicator for numeric change. |
+| `Dialog` | primitives | Modal overlay composed from @radix-ui/react-dialog. |
+| `MoneyAmount` | primitives | Locale-aware currency display. |
+| `SplitButton` | primitives | A main action button paired with a dropdown trigger. |
+| `StatusBadge` | primitives | Colored circle + glyph status indicator. |
+| `ThemeToggle` | primitives | Stateful 3-state theme owner. |
+| `Toast` | primitives | Radix-backed transient notification system. |
+| `Toggle` | primitives | Toggle Primitive. |
+| `VisuallyHidden` | primitives | Renders its children so they are present in the DOM and the accessibility tree but visually hidden. Standardizes the ad-hoc `sr-only` className pattern previously hand-rolled across primitives (Dialog/Sheet/Toast close labels) and section headers. |
+| `FlowFrame` | panels | The // frame: a full-viewport ground on the site `bg` token, two 50/50 regions (a persistent side panel + an active region) that stack below `md:` (side panel first, in DOM and visual order), and a bottom bar pinned to the VISIBLE viewport (`position: fixed`, safe-area aware) carrying a single continuous accent progress line, `leading` / `label` (center) / `trailing` slots, and a prop-controlled "Powered by Working Theory" line. |
+| `BlogShell` | shells | Blog reading **slot-frame** (DOCS-UI-8). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (Nav/Footer) and content (the post meta rail + the reconciled BlogPost body) **fill** the slots — nothing is baked in. Peer to MarketingShell / DocsShell; see. |
+| `DocsShell` | shells | Documentation reading **slot-frame** (DOCS-UI-4). Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* and *where content goes*, owning **geometry only**. Chrome (DocsSidebar) and content (DocsArticleHeader + MDXContent + ArticlePager + DocsFeedback) **fill** the slots — nothing is baked in. Peer to MarketingShell; see. |
+| `MarketingShell` | shells | Public-facing marketing site **slot-frame**. Server Component (RSC default). A shell is a slot-defining frame: it carves out *where chrome goes* (top + bottom) and *where sections go* (the body), owning **geometry only**. Chrome (Nav/Footer) and sections **fill** the slots — nothing is baked into the component. See (first instance). |
+| `PortalShell` | shells | Customer-facing portal (sidebar + branded top chrome + main);. Thin composition of AppShell + SidebarNav. Converged from the hand-rolled layout in the prior MVP to match the AppShell pattern established by WorkspaceShell. |
+| `WorkspaceShell` | shells | Application sidebar shell (thin AppShell composition);. Props are intentionally identical to the old DashboardShellProps — no additions beyond what AppShell provides — so any fork using DashboardShell can swap the import without changes. |
+
+---
+
+## Undescribed components
+
+These 4 components carry no capability description recoverable from source: no section-registry entry, no substantive doc-comment header, no tier-barrel roster line. They are this catalog's blind spots — a capability search will not find them, so read the source before concluding AILK lacks something.
+
+| Component | Tier | Source |
+| --- | --- | --- |
+| `Container` | primitives | `packages/ui/src/primitives/Container.tsx` |
+| `Heading` | primitives | `packages/ui/src/primitives/Heading.tsx` |
+| `Link` | primitives | `packages/ui/src/primitives/Link.tsx` |
+| `Text` | primitives | `packages/ui/src/primitives/Text.tsx` |