AI Design Playbook
A practical guide to designing AI features
Get started
Three steps to go from reading to shipping — browse the core chapters, test your instincts, then apply what you've learned to your own product.
Learn
Browse the core chapters — jobs, patterns, semantics, visuals, and interaction.
Test
Take the AI Design Quiz to check what you know.
Apply
Download the Skills and drop them into your own workflow.
Chapters
Focused chapters covering how an AI feature communicates, looks, and behaves — the semantics, visuals, and interaction patterns that make it trustworthy.
Semantics
Content strategy, microcopy, naming, and cues that distinguish AI from human content.
Visuals & Consistency
Component integrity, visual language, iconography, and color patterns for AI.
Interaction & Feedback
The AI interaction loop, loading patterns, and feedback mechanisms that make AI smarter.
Test your AI design knowledge
A three-level, self-graded quiz — thirty questions spanning transparency basics to advanced agentic patterns, drawn from the same checklist used throughout this playbook.
Start the AI Design Quiz
Takes about 10 minutes. No login required.
Semantics
How the feature communicates through language — content strategy, microcopy, naming, and the cues that distinguish AI from human content.
Affordances and control
Make every action explicit: accept, reject, edit, regenerate. Support iteration — let users refine without starting over. Enable graceful exit at any point. Offer granularity — let users control scope ("Rewrite just this paragraph" vs "Rewrite everything"). The goal is partnership, not automation overreach.
Give users tools to iteratively improve AI output — tone sliders, length controls, style presets, and regenerate buttons. Each refinement should feel like a conversation, not a restart. Users who refine output report 3x higher satisfaction.
Signifiers
Cues that distinguish AI content from user content. They should be present but not loud — a subtle sparkle icon, a light border, or a small label. Keep them consistent across all AI features. Signifiers should degrade after user edits: once a user modifies AI output, the "AI" label fades because it's now their content.
AI markers should follow a lifecycle: prominent when first generated → subtle after review → invisible after user edits. This respects user ownership while maintaining transparency during the review phase.
Content transparency
Always distinguish AI-generated from human-curated content. Show drafts as drafts — never present AI output as final without user approval. Be honest about uncertainty and confidence levels. Use visual badges, subtle borders, or labels like "AI-generated draft" to make provenance clear.
Design clear visual indicators (badges, icons, or color coding) to differentiate AI-generated and human-verified content. Assign confidence levels or accuracy scores. Allow users to filter or sort by verification status.
Microcopy and narration
Set expectations before every action — tell the user what the AI will do before it does it. Narrate the process during loading ("Analyzing your document...", "Generating suggestions..."). Frame results with context ("Based on your last 3 conversations"). Guide feedback with specificity — don't just ask "Was this helpful?" but "Did this match your tone?"
Gradually reveal AI capabilities as users become comfortable. Start with simple suggestions, then introduce advanced features. Reduces cognitive overload and builds confidence over time.
Feature naming
Pick a single umbrella brand for AI features (e.g. "[Product] AI") and keep individual feature names in title case: AI Drafts, AI Suggestions, AI Insights. Always prefer verbs over nouns — they communicate action. Be specific about what the AI does. Naming should get sign-off from design and product leadership before shipping.
Consistent naming reduces confusion. Users build mental models around feature names. Changes are expensive — get it right early. Use language that communicates capability without overpromising.
Conversation design
When AI communicates through dialog — chat, voice, or multi-turn interactions — the Conversation Design Institute's framework applies: set expectations early (tell users what AI can and can't do), maintain context across turns (reference previous messages naturally), support mixed-initiative (both user-led and AI-led turns), handle dead ends gracefully (always suggest a next step), and design repair strategies for when misunderstanding occurs.
Good conversations have rhythm. AI should know when to speak, when to listen, and when to ask for clarification. Repair strategies ("Did you mean X or Y?") are essential — they show the AI is paying attention, not just generating. The CDI recommends designing the "unhappy path" first: what happens when the AI misunderstands?
Visuals & Consistency
How the feature looks within your design system — component integrity, visual language, iconography, and color patterns for AI.
Design system integrity
Always check your existing component library first before creating anything new. Extend, don't fork. When a new AI-specific component is needed, document it immediately. Build your AI component system to be extensible from day one: atomic components can absorb confidence indicators, streaming containers, and adaptation signals without a full redesign.
AI features need specialized components (confidence badges, streaming text containers, suggestion cards). Design these as extensions of existing primitives, not new paradigms. This keeps the system cohesive while supporting AI-specific needs.
UX consistency
Similar AI behaviors should look similar across features. A suggestion in one part of the product should feel the same as a suggestion anywhere else. Build a shared interaction vocabulary — if "sparkle" means AI-generated in one place, it means AI-generated everywhere. Standardize the AI flow pattern across all features.
Create a consistent visual language for AI interactions: same icons for same actions, same animations for same states, same layouts for same patterns. Users build muscle memory around consistent patterns — breaking consistency breaks trust.
Iconography
Use a small, clear icon set for AI actions. The sparkle icon (✦) is the primary AI signifier — don't overload it for multiple meanings. Always pair icons with text labels; icons alone are ambiguous. Keep AI icons visually lightweight so they don't compete with primary actions.
Research shows icon-only interfaces increase error rates by 30%. For AI features where trust and clarity are paramount, always pair icons with labels. The label does the heavy lifting; the icon provides quick visual scanning.
Color and confidence
Use a subtle AI accent color — distinct enough to recognize, muted enough to not overwhelm. Never conflict with semantic colors (red = error, green = success). For confidence indicators, use a calibrated scale: green (high confidence, >85%), amber (medium, 60-85%), gray (low, <60%). Confidence colors should fade after the user accepts the suggestion.
One of the most important AI UX patterns of 2026. Show confidence as percentages, color-coded borders, or calibrated badges. Use consistent scales across all features. Always explain what factors influence the score. Show uncertainty ranges, not just point estimates.
Interaction & Feedback
How users interact with and respond to the AI — buttons, triggers, states, loading patterns, and the feedback loops that make AI smarter.
Buttons and CTAs
Clear action hierarchy: primary action = safest action. "Review suggestion" beats "Send now". Value-focused copy — tell users what they get, not what to do. Sentence case, no emoji, no exclamation marks. Provide keyboard shortcuts for power users (Cmd+Enter to accept, Esc to dismiss). Always include a "Not now" escape.
The default action should always be the safest one. "Review" not "Send". "Save draft" not "Publish". AI outputs are probabilistic — the UI should reflect this by making cautious actions prominent and irreversible actions require confirmation.
Triggers and inputs
Use explicit triggers for consequential actions — never auto-apply AI changes without consent. Progressive disclosure for complex inputs: start with a simple prompt, offer advanced options behind a toggle. Always show what context the AI can see ("Using your last 5 conversations and knowledge base"). The autonomy dial pattern lets users choose their comfort level from manual to fully automatic.
Let users control how much the AI does autonomously. From "suggest only" to "auto-apply with review" to "fully automatic." Pre-action: Intent Preview ensures the user defines the plan. In-action: Explainable Rationale maintains transparency. Post-action: Audit Trail provides a safety net.
States and notifications
Five core states: idle, loading, success, error, streaming. Errors must be specific — never "Something went wrong." Say what happened plainly and provide a recovery path. Show low confidence explicitly. For streaming, design for progressive text reveal with a stable layout that doesn't jump. Notify users of background AI completion without interrupting their current task.
Streaming reduces perceived wait time by 60% compared to batch responses. Design for stable layout during streaming — reserve space, use skeleton screens, and never let content jump. Show a subtle cursor or typing indicator. Allow users to stop generation mid-stream.
Loading and progress
Duration-based loading treatments: <1s — no loading state. 1-3s — subtle spinner. 3-10s — spinner + contextual messaging. 10-30s — progress bar + abort option + thought process. >30s — move to background + notification. Always show what the AI is doing, not just that it's busy. Skeleton screens reduce perceived wait by 40% vs spinners.
Replace generic spinners with stage-specific messaging: "Analyzing your document..." → "Generating suggestions..." → "Finalizing recommendations...". This builds trust and manages expectations. Users who see contextual loading messages rate AI as 25% more trustworthy.
For a fixed, repeatable chain of steps — not a branching flow — mark progress explicitly instead of leaving the user to infer it from a spinner. Every completed step stays visibly marked, not just the current one, so a user glancing back mid-process can see exactly how far the chain has gotten.
Feedback loops
Every AI interaction should include lightweight feedback — thumbs up/down, star ratings, or "Was this helpful?" Don't ask for feedback every single time; vary the frequency based on context. Collect both explicit feedback (ratings, corrections) and implicit signals (accepted, edited, dismissed). Feed corrections back into the system. Show users how their feedback improved results over time.
The feedback → learning → improvement cycle is what makes AI products get better. Provide consistent ways for users to submit corrections and ratings. Track acceptance rates as implicit feedback. Close the loop by showing users "AI has learned from your feedback" moments.
Explainability
Users don't need to understand how a model works — they need to understand why it did what it did and what they can do about it. Explainability is a design decision, not a technical footnote. Every AI output should answer two questions: Why this? and What can I change?
Explainability as a design layer
Explainability isn't a technical afterthought — it's a design decision. Users don't want a model architecture diagram; they want a plain-language reason for a recommendation. The goal is actionable understanding: enough context to accept, edit, or reject. Design explainability at three levels: inline (tooltips, "Why this?"), on-demand (expandable rationale panels), and deep (full audit trails for power users).
Do
- Show the top 2-3 factors behind a recommendation
- Use "Why this?" toggles that expand inline
- Phrase explanations as cause → effect ("Based on 3 similar campaigns that converted at 12%")
- Let users drill deeper if they want, but don't force it
Don't
- Show raw model scores or technical metrics
- Bury explanations behind multiple clicks
- Use vague language ("AI-powered recommendation")
- Assume users will trust output without context
Design three tiers of explanation: (1) Glanceable — a one-line reason shown inline, always visible. (2) On-demand — a "Why this?" panel with 2-3 contributing factors and data points. (3) Deep — a full audit trail with timestamps, data sources, and model version. Most users stay at tier 1; power users appreciate tier 3.
Confidence communication
Every AI output carries uncertainty. The interface must communicate this honestly — not to undermine the AI, but to calibrate user expectations. Overconfident AI erodes trust when it's wrong; appropriately uncertain AI builds trust over time. Match the confidence display to the stakes: a subject line suggestion can be casual; a revenue forecast needs precision.
Do
- Use calibrated visual scales: green (>85%), amber (60-85%), gray (<60%)
- Show ranges, not just point estimates ("Expected open rate: 18-24%")
- Explain what would increase confidence ("More data needed")
- Fade confidence indicators after user accepts
Don't
- Hide low confidence — surface it clearly
- Use confidence colors that clash with semantic colors (red/green)
- Show raw percentages without context
- Display confidence on trivial outputs where it adds noise
Confidence scores should map to real-world accuracy. If the AI says "85% confident," it should be right ~85% of the time. Miscalibrated confidence (saying 90% when accuracy is 60%) is worse than no confidence at all. Test calibration regularly and adjust thresholds per feature. Use text alternatives alongside color ("High confidence" not just a green dot).
Trust
Trust is the currency of AI products. It's earned incrementally — through honest errors, clear data disclosure, reliable escalation paths, and interfaces that never feel inescapable. Every AI feature should make the user feel in control, even when the AI is doing the heavy lifting.
Data transparency and consent
Users need to know what data the AI can see, how it's used, and what control they have. This isn't just compliance — it's a trust multiplier. Show context windows explicitly ("Using your last 5 conversations"), provide clear opt-out paths, and never process data without informed consent. Data transparency should be persistent and accessible, not buried in onboarding.
Do
- Show what data the AI is using ("Based on your contact list and last 30 days of messages")
- Provide granular data controls (per-feature, per-data-type)
- Allow users to delete their AI training data
- Surface data usage in context, not just in settings
Don't
- Process data silently without disclosure
- Use dark patterns to get consent (pre-checked boxes, confusing language)
- Make opting out harder than opting in
- Store data longer than needed without explanation
Always show what the AI can "see." Display a small, persistent indicator: "AI can access: your flows, contacts, and message history." Let users expand it to see specifics and toggle individual data sources on/off. When the AI accesses new data types, notify the user and ask for permission.
AI attribution and provenance
Users must always know whether content was human-created or AI-generated. Attribution should follow a lifecycle: prominent when first generated, subtle after user review, invisible after substantial edits. This respects user ownership while maintaining honesty during the review phase. For content that will be seen by end-users (subscribers, customers), AI provenance must persist.
Do
- Label AI-generated content clearly ("AI draft", "Suggested by AI")
- Fade attribution after user edits >30% of content
- Maintain provenance in audit logs even after UI labels fade
- Distinguish between AI-generated, AI-assisted, and human-created
Don't
- Present AI output as if the user wrote it
- Remove all attribution the moment a user clicks "Accept"
- Use the same label for very different levels of AI involvement
- Let AI attribution compete visually with primary content
AI markers follow a lifecycle: (1) Prominent — "AI-generated draft" badge when first created. (2) Subtle — small icon after user reviews and edits. (3) Invisible — removed from UI after substantial user modifications, but preserved in metadata. This pattern respects both transparency requirements and user ownership of their content.
Error honesty and recovery
When AI fails, the interface must be honest about it. Vague errors ("Something went wrong") destroy trust; specific errors ("Couldn't generate a subject line because the message body is empty") preserve it. Every error needs a recovery path — what the user can do next. For AI-specific failures (hallucinations, low-quality output), acknowledge the limitation directly.
Do
- Say what happened in plain language
- Provide a clear next step ("Try rephrasing" or "Add more context")
- Acknowledge when the AI doesn't know something
- Offer a human fallback for critical tasks
Don't
- Show generic error messages
- Pretend failures didn't happen (silently retrying without disclosure)
- Blame the user for AI limitations
- Let the user hit a dead end with no recovery option
When AI confidence drops below a threshold, automatically fall back to simpler, more reliable outputs. A text generator might fall back to templates. A classifier might show "Unsure — please review" instead of forcing a category. Design the degradation path explicitly — don't leave it to chance. Users should barely notice the transition.
Human escalation and override
No AI system should be a black box with no exit. Users need the ability to override any AI decision, escalate to a human when the stakes are high, and permanently opt out of specific AI features. The escalation path must be visible and frictionless — not hidden behind settings menus. For agentic workflows, build explicit checkpoints where the user reviews and approves before the AI proceeds.
Do
- Show "Override" or "Edit manually" on every AI output
- Provide one-click escalation to human support
- Remember user overrides and learn from them
- Build checkpoint gates into multi-step AI workflows
Don't
- Make the AI feel inescapable
- Require multiple steps to reach a human
- Ignore repeated overrides (if users keep correcting the AI, something is wrong)
- Auto-proceed past checkpoints without explicit user approval
For agentic AI that takes multi-step actions, insert mandatory review points before irreversible steps. Show what the AI plans to do, what data it will use, and what the expected outcome is. The user explicitly approves before the AI proceeds. This is the HITL (Human-In-The-Loop) pattern applied at the interaction design level.
Building trust over time
Trust with AI isn't binary — it's earned incrementally. New users need more transparency, more confirmation, and more conservative defaults. As users gain experience and the AI proves reliable, the interface can progressively reduce friction. This is the autonomy ladder: start supervised, earn independence. Track trust signals (acceptance rate, override frequency, feature adoption) to calibrate the experience per user.
Map the trust journey: (1) Suggest — AI recommends, user acts. (2) Auto-apply with review — AI acts, user confirms. (3) Fully autonomous — AI acts, user is notified. New features start at stage 1. Users graduate based on demonstrated comfort (high acceptance rates, low override frequency). Always allow users to dial back to a more supervised mode. The autonomy dial should be per-feature, not global.
AI & Agentic Jobs
Every AI feature performs one or more of 7 core jobs. Name the job first — the interaction pattern follows.
Anticipate
The design tension: being helpful early vs. being wrong loudly. Err on the side of showing your work.
Do
- Show confidence levels with every prediction
- Explain what data informed the forecast
- Offer alternative scenarios, not just the top pick
- Update predictions in real time as context changes
Don't
- Present predictions as facts
- Hide the reasoning behind projections
- Rely on thin data without flagging it
- Auto-act on a prediction without user consent
Surface relevant information before the user asks for it, based on behavioural patterns and context. The best anticipation feels like good timing, not surveillance.
Discover
The design tension: speed of retrieval vs. accuracy of understanding. Always show the AI's interpretation so users can course-correct.
Do
- Show how the AI interpreted the query
- Highlight matching context within results
- Offer one-click refinement suggestions
- Support conversational follow-up ("show me more like this")
Don't
- Return only exact keyword matches
- Show empty states without actionable next steps
- Require query syntax or special operators
Match user intent, not just keywords. Show what the AI understood and let users refine naturally. Zero-result states are a design opportunity, not a dead end.
Generate
The design tension: speed of creation vs. faithfulness to the user's voice. Always present output as a draft, never as done.
Do
- Frame output as a draft the user controls
- Offer tone, length, and style controls
- Show a clear "AI-generated" indicator
- Allow inline editing before any action
Don't
- Auto-send without explicit confirmation
- Override the user's established voice
- Present AI output as the user's own words
AI drafts, human decides. The output is always a suggestion — never a fait accompli. Users who can edit inline before sending report 3× higher satisfaction.
Connect
The design tension: surfacing enough context to be useful vs. overwhelming with information. Rank ruthlessly, show sources always.
Do
- Show clear source attribution for every reference
- Rank by relevance first, recency second
- Let users expand, verify, and pin useful context
- Display inline — not buried in popups or modals
Don't
- Show context without linking to the source
- Overwhelm with too many references at once
- Surface stale or irrelevant information
Right information, right moment, clear attribution. The best Connect experiences feel like having a teammate who always remembers the relevant detail.
Recommend
The design tension: being proactive vs. being intrusive. Recommendations should feel like a helpful nudge, never a pop-up ad.
Do
- Explain the reasoning behind each suggestion
- Allow one-tap dismissal and snooze
- Adapt frequency based on user behaviour
- Use subtle, non-blocking UI (banners, inline cards)
Don't
- Interrupt the user's current task with a modal
- Repeat a suggestion the user already dismissed
- Recommend without explaining why
- Use dark patterns to push acceptance
Anticipate needs without disrupting flow. The best recommendations arrive exactly when the user was about to look for them.
Enhance
The design tension: improving quality vs. respecting authorship. Every change should be visible, and the user should always be able to accept or reject each one.
Do
- Show a clear before/after comparison
- Allow partial acceptance — change-by-change
- Preserve the user's original meaning and voice
- Offer multiple refinement directions (shorter, friendlier, more formal)
Don't
- Replace content silently without showing the diff
- Change the meaning or intent of the original
- Auto-apply refinements without review
- Impose a voice that doesn't match the user's
Enhance what exists. Show every change. Let the user stay in control. Users who refine AI output report 3× higher satisfaction than those who accept or reject wholesale.
Organize
The design tension: automation speed vs. accuracy of classification. Let the AI sort, but always let humans correct.
Do
- Show why items were grouped together
- Let users rename, merge, or split clusters
- Provide easy override controls
- Display grouping confidence scores
Don't
- Auto-apply labels without letting users review
- Create opaque clusters with no explanation
- Hide the ability to manually re-categorize
Let AI find structure in unstructured data, but always let humans verify and adjust. The best Organize features feel like a smart filing system, not an opinionated robot.
Jobs in practice
Most features combine multiple jobs — that's by design. AI Drafts performs Generate + Connect (drafts a response while pulling knowledge base context). AI Insights does Recommend + Anticipate (suggests what to focus on based on patterns). Start by naming which jobs your feature performs, then design the interaction pattern for each through the 4-stage loop.
Design System
A nimble, agentic design system — fundamentals, primitives, tokens, and accessibility for any design feature or product, not just AI ones, built accessible by default and readable by both humans and coding agents.
The classic layer: color, type, layout, and spacing. Nothing here assumes AI — it's the same foundation you'd ship for any interface.
Colors
Values shown are light mode — every token flips automatically in dark mode.
Category accents mark what kind of content this is — they never carry AI judgment. Judgment tokens, below, are the only three allowed to do that.
Never invent a fourth hue for AI meaning, and never reuse a category accent (teal/violet/amber/rose) to carry it — these three are the only tokens allowed to say "the AI thinks this is fine / uncertain / wrong."
Typography
Two typefaces, one job each — nothing else is allowed in.
Mono is reserved for things meant to be copied or compared — token names, code, measurements. Everything a person reads in sentences stays in Instrument Sans, including inside components; mono in a sentence reads as a code smell.
One size scale, reused everywhere — no ad-hoc font sizes.
| Token | Size | Face | Used for |
|---|---|---|---|
| text/xl | 24px · 800 | Instrument Sans | Component / card titles |
| text/lg | 16-19px · 700 | Instrument Sans | Topic and job card titles |
| text/body | 13.5-14px · 400 | Instrument Sans | Card body copy |
| text/caption | 12-12.5px · 400 | Instrument Sans | Pattern callouts, captions |
| text/label | 10-11.5px · 700 · uppercase | Instrument Sans | EXAMPLE / section labels |
| text/mono | 11-12.5px · 400-600 | JetBrains Mono | Tokens, code blocks, table data |
Grid
A fixed three-column app shell, not a fluid content grid — the center column is the only one that reflows.
| Column | Width | Behavior |
|---|---|---|
| Left nav | 260px fixed | Collapses to a burger menu below the tablet breakpoint |
| Content | 840px max, centered | The reading column; padding steps down at each breakpoint |
| Right panel | 340px, resizable | The Ma chat panel; hidden below tablet unless explicitly opened |
Breakpoints
Two, not five — content-first layouts need fewer steps than marketing pages.
| Name | Value | What changes |
|---|---|---|
| tablet | ≤900px | Left nav becomes a burger menu; 3-col grids drop to 2 |
| phone | ≤500px | All grids drop to 1 column; content padding tightens to 16px |
Spacing
Card padding steps up in 2-4px increments.
Border
One border token, one weight — borders separate surfaces, they never carry meaning on their own.
| Token | Value | Used for |
|---|---|---|
| --border | 1px · rgba(fg, 0.15 light / 0.10 dark) | Card, swatch, table outlines |
| border/emphasis | 3px solid | Do/don't rule markers, status-colored only |
Radius
Radius scales with a component's visual weight.
Elevation
Three shadow steps, reserved for hover and active states — nothing sits elevated at rest.
Two tiers: components are the atoms — button, badge, chip, input, stage — single, not compounded. Patterns assemble those atoms into something a person actually uses — a card, a modal, a table, a form. AI-specific interaction patterns (safe defaults, checkpoint gates, recovery, autonomy) live on Interaction & Feedback, not here.
Button
Three weights sharing one shape: primary for the single safest action, default for neutral secondary actions, ghost for dismiss and escape hatches.
Badge
A small status pill — a dot plus a text label, never the dot alone — used everywhere the product signals confidence, state, or attribution. One component, three tiers, reused as-is instead of a new badge per feature.
| Tier | Modifier class | Token | Used for |
|---|---|---|---|
| Positive | .ex-badge-green | --status-positive | High confidence, success state |
| Warning | .ex-badge-amber | --status-warning | Medium confidence, error state, new AI-generated draft |
| Neutral | .ex-badge-gray | --fg-light | Low confidence, idle/loading state, reviewed draft |
Do
- Reuse these exact three tiers everywhere — never invent a fourth
- Fade or remove the badge once its signal goes stale (accepted, reviewed, resolved)
Don't
- Show a raw percentage or state with no text label
- Use red for error — that's reserved for destructive actions
Chip
A rounded-rect pill for longer text a badge is too small to hold — most often a persistent, expandable disclosure of exactly what an AI feature can see. Never a full oval, so multi-line text doesn't distort the shape.
Do
- Keep it persistent and visible, not buried in settings
- Notify the user when the AI gains access to a new data type
Don't
- Bury data access behind a "Learn more" link
- Let text wrap inside it — wrap the chip itself to a new line instead
Stage
One step in a row of steps, with the current or completed step marked active.
Input
The atomic text field — one line of user-editable content plus its focus and error states. Always paired with a visible label; a placeholder alone is not a label.
Do
- Pair every field with a visible label, not just a placeholder
- Show the error message inline, directly under the field
Don't
- Use placeholder text as the only label
- Clear the field's value when validation fails
Assembled from the components above — a specific job, not a generic container.
Card
The default container for one self-contained piece of content — a title, a short body, and at most one primary action. If it needs two unrelated actions or a second heading level, it's not a card anymore, it's a page.
Do
- Keep it to one title, one body, one primary action
- Let the title name the specific thing, not a category
Don't
- Stack two unrelated actions in the footer
- Nest a card inside another card
Modal
Interrupts the current task for one decision only — confirm, choose, or provide one piece of information — then gets out of the way. Never a destination in itself; if the content needs its own navigation, it belongs on a page.
Do
- Put the cancel/dismiss action first, reading left to right
- Close on Escape and on a scrim click
Don't
- Style the destructive action as the visually primary button
- Stack a second modal on top of an open one
Form
One labeled field plus its own inline help text — validation and constraints live next to the field they describe, never in a separate summary at the top or bottom.
Do
- Put help and error text directly under its own field
- Disable submit only when the reason is visible on screen
Don't
- Collect every error into a banner at the top of the form
- Clear a field's value when it fails validation
Table
Rows of comparable items, each with the same fields — the pattern for anything the user needs to scan, compare, or triage. Every status or confidence column reuses the Badge component instead of inventing a new indicator.
| Name | Status | Confidence ↓ |
|---|---|---|
| Refund request — Priya K. | Reviewed | 92% |
| Pricing question — unresolved | Awaiting approval | 67% |
| Bug report — triage | Idle | 41% |
Do
- Reuse Badge for every status or confidence column
- Show the active sort direction, never sort silently
Don't
- Mix a raw percentage in one row with a badge in another
- Let one wrapped cell stretch the whole row's height
Accessibility
Built to WCAG 2.1 AA — verified, not assumed.
| Token | Light | Dark | Level |
|---|---|---|---|
| --fg | 17.0:1 | 14.5:1 | AAA |
| --fg-light | 11.9:1 | 10.3:1 | AAA |
| --fg-faint | 7.5:1 | 5.7:1 | AA (AAA in light) |
| --status-positive | 6.2:1 | 10.5:1 | AA (AAA in dark) |
| --status-warning | 6.3:1 | 9.9:1 | AA (AAA in dark) |
| --status-negative | 6.8:1 | 6.9:1 | AA |
Machine-readable tokens
The same values above, as CSS custom properties — paste this into a prompt or drop the skill below into Claude Code / Cowork so an agent applies this system consistently instead of inventing new values.
Skills
Drop these into Claude Code or Cowork to get instant AI design reviews and content checks.
Available skills
Each .skill below is a zipped SKILL.md — a markdown file written for a coding agent to read directly, not a human-facing doc. Install one to get the same standards this playbook teaches applied automatically, instead of re-explaining them in every prompt.
AI content design guidelines
Naming conventions, product voice, and word-choice rules (say "adjusts," never "trains"), plus microcopy patterns for errors, loading states, confidence, and agentic checkpoints — the same rules used to write every example on this site.
AI feature review
Runs a feature through three frameworks in order: should this even use AI, a ~90-point pre-ship checklist across 12 categories (transparency, confidence, agentic UX, accessibility, design-system compliance...), then a structured report with a READY / SHIP WITH CONDITIONS / NOT READY verdict. Built to be run on a screenshot, spec, or live prototype.
Design system
The entire system documented on the Design System page — foundations, atomic components, composed patterns, and the AI-specific interaction patterns — written for an agent to apply directly, and for a human to reference when deciding what to reuse vs. add.
AI Design Quiz
Test your knowledge of AI feature design — transparency, user control, content, trust, and accessibility.
How well do you know AI design?
30 questions across 3 levels, drawn from the AI feature design checklist. Pick a level and see how you score.
Courses & Books
Curated resources to deepen your AI design practice, from foundations to advanced agentic patterns.