AI Design OS
The intelligence layers that turn this library into a system an AI can reason about: Component Intelligence (when to use/avoid), a Pattern Library, a Layout Rules Engine, and a strict Token System. Source of truth: src/lib/design-os.ts (summarised for the model in AGENTS.md).
Component Intelligence
When to use / avoid each component, its priority and emotional tone.
Trigger an action or move a flow forward.
✓ The single main action on a screen · Submitting a form · Confirming in a sheet · On-dark surfaces use the on-dark / on-dark-secondary variants (e.g. ActionDeck)
✕ Navigating between screens (use RoundButton/Header) · Inline text links · on-dark variants on a light background (use primary/secondary)
Icon-only action in toolbars, headers and sheets.
✓ Header/back/close actions · Compact icon-only controls
✕ A primary text CTA (use Button)
Label and group a section of content.
✓ Above every home/onboarding section · When a section needs a 'View all' CTA
✕ As the page title (use Header center)
Show status, category or a count as a small badge.
✓ Status (in-progress/completed) · Type/category tag · Risk/severity
✕ Clickable filters (use SelectorPill) · Long text
Toggle a quick filter on a glass surface.
✓ Quick filters above a grid/list · Single- or multi-select chips
✕ Primary actions · Showing static status (use Pill)
Compact glass selector/filter in a header or toolbar.
✓ Filter a list (date range, segment) · Toolbar selector
✕ A form field (use SelectField)
Switch between 2–3 mutually exclusive views.
✓ Tab-like view switch (Chat/Activity) · A small set of modes
✕ Many options (use SelectField) · An on/off setting
Collect typed or selected input in a form.
✓ Forms, KYC, settings · Anything the user must fill in
✕ Filtering (use Dropdown/SelectorPill)
Toggle a single boolean choice (opt-in / agree / multi-select).
✓ Consent / agree toggles · Multi-select option lists · A standalone yes/no in a form
✕ Mutually-exclusive choices (use RadioGroup) · Segmented either/or (use Switch)
Pick exactly one option from a short list.
✓ Single-select within a form · 2–5 mutually-exclusive options
✕ Multi-select (use Checkbox) · Filtering (use SelectorPill) · Many options (use SelectField)
Flip a single on/off setting inline (pill track + sliding knob).
✓ A binary on/off preference in settings/forms · Cash-on-delivery, notifications, store visibility
✕ Choosing between 2–3 views (use Switch) · Multi-select (use Checkbox) · Single-select from a list (use RadioGroup)
A focused task, form or preview without leaving the screen.
✓ Quick form · Preview + confirm · Contextual actions
✕ Full screen navigation (use a route) · Trivial confirmations
Represent a generated AI artifact and its progress.
✓ Artifacts / collections grid · Encouraging resume/continue
✕ Generic content cards (use Card)
Present one or more KPIs/metrics on a glass surface.
✓ Performance metrics (orders, GMV, spends) · Single / double / triple metric tiles · Customer star ratings
✕ Long tabular data · Narrative content (use Card)
Show completion or budget consumption as a light→solid gradient bar.
✓ Budget / spend usage · Step or goal completion · Inside a DataCard metric
✕ Indeterminate loading without a value · Ratings (use DataCard ratings)
Show progress across a few ordered milestones on a horizontal track.
✓ Go-live / onboarding progress · A 3–5 step linear journey toward a goal
✕ A long task list (use a vertical timeline of cards) · A single percentage (use ProgressBar)
Surface a rotating stack of priority notifications with a clear next step.
✓ 'Action Needed' on home/onboarding · A small set of urgent items
✕ A long, browsable list (use a feed of Cards)
Surface a notification (blue, stacked) or an activity item (white).
✓ Activity feed item · Notification deck · Icon + content row
✕ Artifacts (use ArtifactCard) · Form sections
A decorative blue gradient surface for a prominent, high-priority card.
✓ The single hero / next-step card on a screen · Strategy summary highlight · Stacked notification deck (back / middle / front)
✕ Routine content (use Card white) · More than one focal card per screen
Group tasks under an expandable strategy header.
✓ Weekly strategy · Grouped multi-step work
✕ A single standalone item (use ListCard)
A task/strategy item with a status header and action row.
✓ Pending/ongoing tasks · Steps inside a strategy
✕ Notifications (use Card)
Capture a 1–5 star rating from the user.
✓ Feedback / NPS prompts · Rate-your-experience sheets
✕ Displaying an existing rating (use DataCard ratings) · Multi-select (use Checkbox/SelectorPill)
A glass card with the section title inset in its header, wrapping related content.
✓ A self-contained section block (Recent conversation, Your journey) · When the title belongs inside the card, not above it
✕ A header above separate cards (use SectionTitle) · A single metric (use DataCard)
Offer a one-tap callback from a human POC, pinned at the bottom of a screen.
✓ Onboarding help ('Call <POC>') · An assistance prompt floating above the nav
✕ Mid-content rows (use Card) · Anything not pinned directly above BottomNav
A calm, muted inline aside (Info icon + secondary text) under a card/section.
✓ A passive contextual note ('This was discussed…') · A subtle 'why' under a value or list
✕ Warnings/errors (use a Pill / field error) · Primary content
The body of a ListCard — text, an image/media row, or a key/value table.
✓ Inside a ListCard · Showing AWBs, price tables, or media tied to a task
✕ Standalone (it always lives inside a ListCard)
Summarise a channel strategy with stats and a schedule.
✓ Home strategy summary · Channel performance recap
✕ Generic cards
Top app-bar: identity, back, title and screen actions.
✓ Top of every screen
✕ Inline section labels (use SectionTitle)
Primary navigation + 'ask anything' entry point.
✓ Home and main browsing screens
✕ Modal / single-task flows
Compose and send a chat message.
✓ The chat screen input
✕ Forms (use TextField)
Show one chat message (AI or user).
✓ A conversation thread
✕ Notifications (use Card)
Inline report/file attachment delivered inside an AI chat bubble.
✓ AI finished generating a report from chat · Linking a chat message to its Collections artifact
✕ Generic links (use a ghost Button) · Status badges (use Pill)
Represent a person or brand as an avatar.
✓ Header identity · Story ring entry point
✕ Decorative imagery
Animated AI presence — swirling brand-gradient petals around the Orbit + Wheel core (motion ref: AI.mov, Figma 7541:8373). Variants: bloom-to-orbit / bloom-to-gear intros, contained (gradient-flow Lottie inside the orb circle, static gear, no stroke), ambient loop, halo (light-painting ring of blurred violet/blue/peach strands around the Orbit + Wheel core — coreless for the pure ring; multiply-blended for white surfaces — motion ref: 2026-07-15 recording), aura (breathing ripple ring — icy-blue rings, magenta/violet rim, ember pool at the inside-bottom — that inhales into a glowing violet bloom every ~2.8s; the Orbit disc + Wheel sit STATIC in the centre, coreless for the pure hollow ring; multiply-blended for white surfaces — motion ref: 2026-07-15, 1.43 PM recording), pulse (Figma 7693:8511 hero — concentric ice/sky/azure pulse discs around the gradient AI icon ai.svg; dotted rings + arcs drift, crescent slides, stack breathes, thin ring ripples out — motion ref: 2026-07-16, 3.04 PM recording; coreless drops the icon).
✓ Hero of an onboarding / landing screen introducing the AI (intro variants) · An 'AI is thinking / working' focal state · Empty states where the AI is the protagonist
✕ Inline in lists or cards (too heavy — use an icon) · As a generic loading spinner for non-AI tasks (use ProgressBar/shimmer) · More than one per screen
Pattern Library
Proven compositions — which components, in which layout.
Every screen's skeleton.
frame → Header → main (scroll) → BottomNav | sticky footer
A labelled, scannable block in a feed.
SectionTitle → content (cards / deck / list)
Drive attention + continuation on urgent items.
SectionTitle → ActionDeck
Collect a few inputs without leaving context.
BottomSheet → TextField / SelectField ×N → Button footer (secondary + primary)
Browse generated artifacts and resume them.
Header → SelectorPill filters → grid of ArtifactCard → BottomSheet preview
A stacked deck of notifications with depth.
BlueCardBackground (back/middle) → Card (blue, front)
Grouped, expandable multi-step work.
CollapsibleCard → ListCard → ListContent → Pill
Two-party chat with a composer.
Header (Switch center) → ChatBubble ×N → ChatBar (sticky)
Layout Rules Engine
Explicit layout intelligence — the biggest fix for inconsistent AI UI.
- • 16px horizontal padding (px-4) on content
- • 24px between sections (space-y-6); 12px between sibling cards (gap-3)
- • Exactly one primary (gradient) CTA visible per screen
- • Max 2 hierarchy levels inside a single card
- • Sticky Header with a white divider; bottom interaction is sticky
- • Respect safe-area insets (top + bottom)
- • Style only with tokens — never invent spacing, radius, shadow or colour
Chat-style screen built around a single thread + composer.
- • Single primary CTA
- • Bottom-sticky interaction (ChatBar)
- • Max 2 hierarchy levels
- • 16px horizontal padding
- • Messages cap at 80% width
Scrollable feed of labelled sections (home / onboarding).
- • Each section starts with a SectionTitle
- • 24px section spacing, 12px card gap
- • White cards on the surface-app background
- • Sticky Header + BottomNav
Data entry — standalone or inside a sheet.
- • Label-on-top fields, 16px field gap
- • Group related fields; one section = one decision
- • Footer = secondary + single primary
- • Inline validation, never a blocking alert
Browsable 2-column grid of uniform cards.
- • 2 columns, 12px gap, uniform card size
- • Quick filters (SelectorPill) directly under the header
- • Tap a card → detail/preview sheet
Bottom sheet overlaying the current screen.
- • Floats 4px off the left/right/bottom; grows up to 4px from the top
- • Sticky header (grabber + back/close) and sticky footer
- • Body scrolls below the header — content never overlaps the close
- • Footer = secondary + single primary
Token System
The only allowed values. AI never invents spacing, radius, shadow or colour.
Use only this step scale (Tailwind units). No arbitrary px gaps.
1 (4px)tight — icon ↔ label2 (8px)intra-group2.5 (10px)card inner padding (compact)3 (12px)card gap / grid gap4 (16px)screen gutter (px-4), card padding5 (20px)comfortable block padding6 (24px)section spacingMap element → radius. No arbitrary radii except the frame/sheet.
rounded-md (6px)pills / small chipsrounded-lg (8px)inputs, buttons, footer buttonsrounded-xl (12px)thumbnails, inner tilesrounded-2xl (16px)cardsrounded-3xl (24px)large / feature cards, section blocksrounded-[20px]bottom sheetrounded-[44px]phone framerounded-fullpills, avatars, round buttonsUse the elevation utilities, not arbitrary box-shadows.
shadow-glassglass pills / buttons — 0 10 20 /.1shadow-cardresting white card — 0 10 20 /.05shadow-lifthover lift — 0 14 28 /.08shadow-sheetbottom sheet — 0 0 70 /.1shadow-inset-glassglass top sheen — inset 0 1 1 white/.5Use the colour tokens (see AGENTS.md). Never hardcode hexes.
text-primarytext-secondarybrand-primarysurface-appsurface-mutedborder-dividersuccess / success-light / success-softdanger / danger-light / danger-softwarning-default / warning-light / warning-amberaccent-tealaccent-violet / accent-violet-lightUse the type-* utilities (Geist). Never set ad-hoc font sizes.
type-h1SemiBold 20/24type-h2SemiBold 16/20type-h3Medium 13/18type-body-1Regular 13/18type-body-2Regular 12/16type-captionMedium 10/14 UPPERCASEUse the gradient utilities.
bg-gradient-primary#4066f1 → #5b7df4 (primary actions)bg-gradient-grey-dark#1d2025 → #3c3f45 (dark surfaces)bg-gradient-grey-light#e8ebf9 → #f8f9ffbg-gradient-ice#f6fcff → #d9f4ff// src/lib/design-os.ts — machine-readable manifest
import { COMPONENTS, PATTERNS, LAYOUT_RULES, TOKENS } from "@/lib/design-os";
// Component Intelligence — every component carries:
{
purpose: "Trigger an action or move a flow forward.",
useWhen: ["The single main action on a screen", "Submitting a form"],
avoidWhen: ["Navigating between screens", "Inline text links"],
priority: "high",
emotionalTone: ["confident", "clear"],
pairsWith: ["BottomSheet", "ListCard"],
}
// Pipeline:
// Product intent → layout archetype → pattern → components → tokens → UI