Storybook structure

How Gremorie organises components across its two editions (NG and RX). The same tree applies in both — only the underlying implementation differs. This mirrors the Kalvner DS standard captured in the vault knowledge base and the Vercel AI Elements layout.

The 8-section tree

Every Gremorie Storybook (NG, RX, and the public docs site) lays out the sidebar in this exact order:

Welcome -> Showcase -> Foundations -> Tokens -> Primitives -> Patterns -> Layouts -> Blocks

Each section that lists 3+ items begins with an Overview page (a GPS before the list).

Storybook
|
+-- Welcome
|
+-- Showcase                              top-level, single page
|
+-- Foundations
|   +-- About
|   +-- Principles
|   +-- Architecture
|   +-- Accessibility
|   +-- Contributing
|
+-- Tokens
|   +-- Overview
|   +-- Primitive       (Colors, Spacing, Radius, Shadow, Typography, Motion)
|   +-- Semantic        (UI intents, per theme if multi-theme)
|   +-- Chart           only when the product has dataviz
|       +-- Sequential
|       +-- Categorical
|       +-- Divergent
|       +-- Status
|       +-- Comparison
|
+-- Primitives                            9 functional categories
|   +-- Overview
|   +-- Containers
|   +-- Typography
|   +-- Forms
|   +-- Display
|   +-- Data
|   +-- Feedback
|   +-- Navigation
|   +-- Overlays
|   +-- AI              2 sub-categories from Vercel AI Elements
|       +-- Chatbot     (18 conversational components)
|       +-- Code        (15 dev-agent / code-tool components)
|
+-- Patterns                              flat up to ~12, AI grouped at end
+-- Layouts
+-- Blocks

The 9 Primitives categories

Validated against Material UI, Atlassian ADS, Polaris, Mantine, Chakra, and Radix Primitives. Components are organised by what they do, not what they look like.

AI is one of the nine categories, not a special case. The Angular edition opens with the AI category (PromptInput, Conversation, Message); broader categories ship as the registry grows.

The AI category: Chatbot + Code

Two sub-categories that mirror Vercel AI Elements.

Primitives / AI / Chatbot (18)

Conversational UI components:

Attachments, ChainOfThought, Checkpoint, Confirmation, Context, Conversation, InlineCitation, Message, ModelSelector, Plan, PromptInput, Queue, Reasoning, Shimmer, Sources, Suggestion, Task, Tool.

Primitives / AI / Code (15)

Dev-agent and code-tool components:

Agent, Artifact, CodeBlock (streaming), Commit, EnvironmentVariables, FileTree, JsxPreview, PackageInfo, Sandbox, SchemaDisplay, Snippet, StackTrace, Terminal, TestResults, WebPreview.

Why the split

1. Mirrors AI Elements. Tracking and updates align with the upstream reference.
2. Distinct use cases. Chatbot is conversational UI; Code is dev tooling. Search behaviour differs.
3. Focused audit surface. 33 components flat under Primitives/AI/ is too dense; two lists are navigable.
4. Justified asymmetry. Other categories (Forms, Display) have no pre-existing canonical split. AI does, so we honour it.

Disambiguating edge cases

Tokens: three coexisting types

The Tokens layer has three types in parallel, each with a distinct purpose.

Primitive Tokens — Tokens/Primitive/

Raw colours (50-950) and non-colour scales (Spacing, Radius, Shadow, Typography, Motion). No usage semantics — these are raw values.

Semantic Tokens — Tokens/Semantic/

UI intents: --primary, --foreground, --background, --accent. Each semantic token references a primitive. Supports multi-theme (one section per theme).

Chart Color Schemes — Tokens/Chart/

Only when the product has dataviz (charts, dashboards, analytics). Full palettes for encoding data, in 5 canonical groups:

The first three are academic consensus since the 1990s (ColorBrewer). Status and Comparison are product-DS standard. Cyclical and Highlight are optional; add only when there's a real use case.

CSS variable naming

Why Chart is a peer of Primitive and Semantic

Chart palettes are not UI intents — they're encoding palettes. Mixing them with Semantic Colors (primary, foreground) pollutes both. Separating keeps the intent obvious: UI styling looks at Tokens/Semantic/Colors, charts look at Tokens/Chart/.

Overview pages — the rule

Every section listing 3 or more items gets an Overview page. Two types of Overview exist with different content shapes.

Level Overview

Primitives/Overview, Patterns/Overview, Tokens/Chart/Overview, Primitives/AI/Overview. Narrative for the layer:

1. What this layer is — definition in one sentence + example
2. When to create / use — admission rule
3. How it relates to the other layers — dependency flow

Category Overview

Primitives/Forms/Overview, Primitives/AI/Chatbot/Overview, Primitives/AI/Code/Overview. Practical, transversal patterns:

1. What defines this category
2. Shared patterns (props, ARIA, behaviours)
3. List of components with short descriptions
4. When to use X vs Y inside the category
5. Anti-patterns specific to the type

Showcase

A single page that demonstrates components applied in real context. Lives at the top level next to Welcome. Possible content shapes:

• Vignettes - multiple compact mini-apps in cards
• Dense dashboard - one rich application
• Combination — dashboard at top, vignettes below

Showcase uses only documented components and semantic tokens. With multi-theme support, Showcase must respond to the theme selector.

storySort.order for AI sub-categories

To preserve Chatbot then Code inside AI, the storySort in preview.ts:

storySort: {
  order: [
    'Welcome',
    'Showcase',
    'Foundations',
    ['About', 'Principles', 'Architecture', 'Accessibility', 'Contributing'],
    'Tokens',
    ['Overview', 'Primitive', 'Semantic', 'Chart'],
    'Primitives',
    [
      'Overview',
      'Containers',
      'Typography',
      'Forms',
      'Display',
      'Data',
      'Feedback',
      'Navigation',
      'Overlays',
      'AI',
      ['Overview', 'Chatbot', 'Code'],
    ],
    'Patterns',
    ['Overview', '*', 'AI'],
    'Layouts',
    ['Overview', '*'],
    'Blocks',
    ['Overview', '*'],
  ],
}

Counter-cases and limits

• Product Storybook, not DS. Doesn't need this hierarchy.
• Very small DS (under 15 primitives). Categorisation is overhead; stay flat, migrate when it grows.
• Category with fewer than 3 components. No category Overview.
• Blocks not yet authored. Omit the section until the first block lands.
• Empty AI category. Don't create an empty Overview.
• AI but only Chatbot or only Code. Use only the present sub-category.
• Chart Tokens without dataviz. Don't add the layer.
• Showcase needs curation. A stale Showcase misleads.
• An Overview with no content is worse than no Overview.

Sources

• Vercel AI Elements — canonical AI catalogue
• ColorBrewer 2.0 — sequential / diverging / qualitative
• AWS Cloudscape Data Vis Colors
• IBM Carbon Data Visualization
• Atlassian Design System, Material UI, Polaris, Mantine