Brand book

• Neutral first, colour as a condiment. Surfaces and text come from the cool, blue-tinted neutral ramp. accent marks selection, focus and the one primary action per view; green, orange, red appear only as status, always beside a word.
• Hairlines, not boxes. Edges are 1px solid line (never alpha), or a ring baked into the shadow (shadow-card, shadow-btn). Don't add a border to something that already carries a ring shadow.
• Live, never a picture. Show real working components with realistic data; no screenshots of UI, no stock illustrations.
• Motion explains state. Things morph, roll and slide to show what changed, and every animation has a reduced-motion path.

• Sentence case everywhere: buttons, titles, menu items, table headers (“Start free trial”, “Biggest movers”). No title case, no all-caps except micro tags.
• Short and literal. Buttons are a verb plus object (“Delete project”, “Run tool”); confirmations say what happened (“Archived 12 files”) and offer the way back (“Undo”).
• Address the reader as “you”; the product speaks as “we” only in legal and support copy. Agents speak in first person in traces (“I should check inventory before…”).
• Numbers as digits with units: “412 articles”, “182 ms”, “+18.7%”. Use tabular numerals for anything that updates.
• No emoji, no exclamation marks, no filler adjectives. Em dashes are fine in descriptions.
• Errors say what to do: “Enter your email address”, “That email doesn't look right”.

• Ground: page behind everything; canvas for recessed working areas (chat canvas, card wells); surface for cards, inputs and menus; inset for wells inside a surface (code, table headers).
• Text: ink for primary text and icons; ink-2 for secondary text (≥5.2:1 on every ground); ink-3 only for placeholders, disabled labels and decoration — it is 2.7:1 and never the only carrier of meaning.
• Interaction: hover rows and quiet buttons with hover; pressed and ghost fills with hover-2; filled fields and pill buttons on field.
• Accent: accent for focus outlines, selection, progress and the accent button; accent-ink for accent-coloured text and links; accent-tint for selected rows and chips. Text on an accent fill uses on-accent.
• Status: green/green-tint success, orange/orange-tint warning, red/red-tint danger. On tints, set the label in ink or 13px-medium status colour.
• Tooltips and chart overlays are dark in both themes: tooltip-bg with tooltip-fg and tooltip-muted.
• Charts use series-1 (blue, in step with the accent) through series-4, in that order; never pick chart colours by hand.
• Primary actions are ink filled with canvas text . Use the accent button for at most one call to action per screen.
• Theme: set data-theme="dark" on <html>; every token has a tuned dark value — never invert or hard-code colours.

In code, every token is a Tailwind utility from src/styles/theme.css: bg-surface, text-ink-2, border-line, bg-accent-tint, fill-series-1, rounded-control, shadow-card, h-control-md, duration-fast, ease-standard. Tailwind's own colour palette is switched off, so only token colours exist.

• Inter (--font-body) for all interface text, with font-feature-settings: "cv11", "ss01" and -0.01em tracking. Body copy is body (14px/1.5). Controls, tabs and menu items use label (13px/500); compact rows label-sm (12.5px); metadata small (12px); counts and pills caption (11.5px).
• Geist (--font-display) for headings on marketing and landing surfaces only: display-hero (72px) once per page, display-1 (52px) page heroes, display-2 (36px) section headings, display-3/display-4 for blocks. Always weight 500, leading 1.1, tracking -0.03em.
• App screens use Inter headings: title (21px/600, -0.02em) for page titles, heading (17px/600) for card and dialog titles. Don't put Geist inside dense product UI.
• JetBrains Mono (--font-code) for code, file paths, tool calls and ID-like values: code (12.5px/20px), code-sm (12px/18px). Section numbers in galleries are 11px mono in ink-3.
• Headings balance (text-wrap: balance), paragraphs pretty. Use tabular numerals for counters, prices and tables.

• 4px base: space-1 4 · space-2 8 · space-3 12 · space-4 16 · space-6 24 · space-8 32 · space-16 64 · space-24 96.
• Small primitive cards pad 12px (space-3); cards and dialogs 16px (space-4); gaps between cards 16–24px.
• App shells: content max 960px for galleries and docs; marketing pages max 1120px with 32px gutters and 64–96px between sections.
• Control heights: control-height-sm 32px, control-height-md 36px (default), control-height-lg 40px.

• Radii: radius-chip 6px (chips, tags, kbd), radius-control 8px (inputs, selects, menu items, list rows), radius-card 10px (cards, tables, panels), radius-window 14px (dialogs, prompt bar, demo frames). Everything pressable is a pill — radius-button (rounded-button): buttons, calls to action, tabs, segmented controls, toggle and filter chips, pagination and icon buttons (icon-only buttons are circles). One exception: a button drawn as a keyboard key (an Esc cap beside a ⌘ K hint) keeps the key shape, radius-chip. Nest radii: an inner element is one step smaller than its container; pills inside pills stay pills.
• Shadows are smooth multi-layer stacks: shadow-btn secondary buttons, shadow-card resting cards, shadow-raised hovered or raised panels, shadow-overlay menus, popovers and dialogs, shadow-hairline a flat 1px ring, shadow-inset-field pressed-in fields. Layers that draw their own border use the ring-free shadow-floating (menus, popovers, sheets) and shadow-resting (button hover).
• In dark, elevation rings become faint white edges (already in the dark values); don't add borders to compensate.

• App and landing pages sit on page. The signature gallery background is .iris-stripes: a 1px diagonal stripe every 8px over stripe-bg, fixed to the viewport — use it only around a framed content sheet, never behind text.
• No gradients in product UI. The soft lavender-to-peach wash (gradient-from → gradient-to) is reserved for the SiteHeader/SiteFooter blocks.
• Imagery: real product screens or flat, neutral shapes in canvas/line-strong tones. No stock photos of people, no 3D blobs.

• Easing: --ease-out-strong and --ease-standard for most transitions; --ease-enter for things arriving; --ease-spring for transforms with --duration-spring. Durations: --duration-instant 120ms, --duration-fast 160ms (hover, colour), --duration-standard 240ms (layout), --duration-considered 480ms (page-level reveals).
• Press feedback: buttons press in with Motion's whileTap (0.96–0.985 by width); triggers of menus and popovers answer with colour only. Hover changes fill, never position.
• Disabled: filled buttons drop to 52% opacity; outlined controls keep their shape and fade only the label to ink-3.
• Loading states keep the control's width; text swaps morph rather than jump.
• Theme switches freeze transitions for one frame (.theme-switching), so the flip is a single repaint.
• Respect prefers-reduced-motion: transforms are skipped, fades shorten. Every component already does this — keep it in your own code.

• Keyboard focus draws a 2px solid accent outline, offset 2px (≥3:1 on every surface in both themes). Pointer focus draws nothing. Text fields show focus with their border and caret; menu items and options with their highlight fill.
• Status is never colour alone: pair green/orange/red with a word or icon.
• Give every icon-only button an aria-label; charts take a label that describes the data.
• Known source pairs below 4.5:1, kept exact: ink-3 on any ground; accent and on-accent (light) for small text; orange text on surface (light). Use them for marks, large or bold text only.

• lucide line icons (bundled), 14–18px, stroke 1.75–2, currentColor, round caps and joins. Size icons to the text they sit beside: 13–14px in 12–13px labels, 16px in controls, 18px in navigation.
• Custom glyphs are inline SVG paths in the same stroke style.
• No emoji in UI, no filled or duotone icon sets, no brand logos you don't have rights to. Sign-in blocks show Google, Apple and GitHub marks only as provider buttons.
• Iris UI has no logo mark yet: set the name in plain type — Geist 600, -0.035em — as the header and footer blocks do.

• Load in order: tokens.css, the fonts, components/bundle.css, React 19 and ReactDOM (components/lib/), then components/bundle.js. Everything is on window.Iris.
• Mount with ReactDOM.createRoot(el).render(React.createElement(Iris.Button, …)). Sub-parts are separate exports (Tabs, TabsList, TabsTrigger, TabsContent; Dialog, DialogTrigger, DialogContent…). Helper hooks are exported too (useToastStack, useDrawerItem).
• The AI-interface components (ApprovalCard, ThinkingState, StreamingText, ToolChips, …) render a full demo with no props; always pass your own data and labels in product code.
• Blocks are complete page sections; pass your own brand, copy and data — several have sample defaults. Start new landing pages from LandingProduct (marketing home) or LandingGallery (showcase).
• Each component's card lists when to use it, its props and gotchas; read it before using the component.