Prototype Builder Skill

Specialized knowledge for building Storybook prototypes that meet human-centric AI design standards.

When to Use

Creating new UI prototypes
Building Storybook stories
Implementing AI feature states
Designing interactive user flows

Design Principles

Trust Before Automation

New features start as suggestions, not automations
Show receipts (evidence) for every AI decision
Make confidence levels explicit
Graceful failure > silent failure

Emotional Design

Visceral: Does it look trustworthy at first glance?
Behavioral: Does it work predictably?
Reflective: Does user feel augmented, not replaced?

Persona Awareness

Reps fear: Surveillance, replacement, embarrassment
Managers fear: Losing touch, surveillance culture
RevOps fear: Ungovernable AI, lack of auditability

Creative Exploration (Required)

For each major component, create 2-3 directions:

Direction	User Control	Trust Required	Best Persona
Option A	Maximum	Low	New users, skeptics
Option B	Balanced	Medium	Most users
Option C	Minimal	High	Power users

Required AI States

Every AI feature needs ALL states:

State	Visual	Copy	Animation
Loading (short)	Spinner	None	Pulse
Loading (long)	Progress	"Analyzing..."	Transitions
Success	Check, muted	Affirming	Scale+fade 150ms
Error	Warning	Honest + solution	Gentle shake
Low Confidence	Muted, dotted	"I think..."	None
Empty	Illustration	Encouraging	Fade in

Required: Flow Stories

Every prototype MUST include interactive journey stories:

export const Flow_HappyPath: Story = {
  render: () => <ComponentJourney scenario="happy" />,
};

export const Flow_ErrorRecovery: Story = {
  render: () => <ComponentJourney scenario="error" />,
};

Prototype Type	Required Flows
Simple feature	1 (happy path)
AI feature	2 (happy + error)
Complex workflow	3+
Any feature	+ Discovery flow (how user finds this)
Any feature	+ Activation flow (first-time setup/onboarding)
AI feature	+ Day-2 flow (returning user, ongoing value)

Experience Flow Requirements

Every prototype MUST tell the full user story, not just show the feature:

Discovery flow - How does the user know this feature exists? Start from the user's natural context (e.g., dashboard, sidebar, notification), not from the feature itself.
Activation flow - What does first-time setup look like? Can the user enable/configure this without CSM assistance?
Day-2 flow - What does the returning user see? What value compounds over time?

export const Flow_Discovery: Story = {
  render: () => <ComponentJourney scenario="discovery" />,
};

export const Flow_Activation: Story = {
  render: () => <ComponentJourney scenario="first-time-setup" />,
};

export const Flow_Day2: Story = {
  render: () => <ComponentJourney scenario="returning-user" />,
};

Required: Interactive Demo + Walkthrough

Every version MUST include:

Interactive demo story (live click-through of the full experience)
Walkthrough story (step-by-step narration of the flow)

export const Demo_Clickthrough: Story = {
  render: () => <Demo />,
};

export const Walkthrough: Story = {
  render: () => <Walkthrough />,
};

Codebase Consistency (Required)

Prototypes must look and feel like they belong in the existing app. Before building any component:

Use What Already Exists

Check elephant-ai/web/src/components/primitives/ for available wrapped shadcn/ui components (the buffer layer). Use Button, Card, Badge, Sheet, Dialog, Select, Input, Tabs, etc. directly from this layer. Do NOT recreate these or use raw shadcn primitives from ui/.
Check existing domain folders in elephant-ai/web/src/components/ for patterns. If there's already a health-score/ folder with HealthScoreCard.tsx, reference how it structures props, handles states, and applies styles.
Check existing pages in elephant-ai/web/src/pages/ or elephant-ai/web/src/app/ for layout conventions. Match the same padding, spacing, header patterns, and content area structure.
Top-Level Navigation: If a new page or view requires top-level visibility, it MUST be added to the map in apps/web/src/components/navigation/top-nav-main.tsx.

Match Visual Patterns

Theme V2: Ensure prototypes use the .theme-v2 CSS class and @custom-variant v2 where necessary.
Card patterns: Follow the existing Card → CardHeader → CardContent structure with the same spacing (p-6, pt-0).
Semantic Colors: Use strict semantic tokens (success-*, destruction-*, warning-*, primary-*, secondary-*, muted-*) from the V2 Design System, not raw Tailwind colors like emerald/amber.
Typography: Use the same text size hierarchy (text-sm for body, text-xs for secondary, font-medium for labels).
Borders and shadows: Follow the existing border bg-card shadow-sm pattern for cards.
Icons: Use Lucide icons at the same sizes as existing components (h-4 w-4 inline, h-5 w-5 standalone).

When the Design System File May Be Stale

The .interface-design/system.md file is a snapshot. If a prototype looks inconsistent with the live app, check the actual source files — apps/web/src/index.css and the Storybook file color-system-v2-demo.stories.tsx are authoritative over the visual language, and the actual components in apps/web/src/components/primitives/ are authoritative over component structure.

Component Structure

Always use versioned folders. The initiative root should contain only index.ts and version folders (no loose components or views). All version-specific components (new or adapted AskElephant components) live inside the version folder:

prototypes/[Initiative]/
├── index.ts           # Re-exports latest
├── v1/
│   ├── Component.tsx
│   ├── Component.stories.tsx
│   ├── ComponentJourney.tsx
│   ├── Demo.tsx
│   ├── Demo.stories.tsx
│   ├── Walkthrough.tsx
│   ├── Walkthrough.stories.tsx
│   └── types.ts

Tech Stack

React 18 + TypeScript (strict)
Tailwind CSS
shadcn/ui wrappers from @/components/primitives/

Storybook Title Pattern

const meta = {
  title: "Prototypes/[Initiative]/v1/[ComponentName]",
  component: ComponentName,
};

For demo and walkthrough, use:

title: "Prototypes/[Initiative]/v1/Demo";
title: "Prototypes/[Initiative]/v1/Walkthrough";

Image Generation for Mockups (Cursor 2.4)

When a quick visual is needed before building full components, use image generation:

When to Generate Images

Early concept exploration - Before committing to code
Stakeholder communication - Quick visuals for feedback
Design exploration - Testing multiple directions rapidly
Architecture diagrams - Visualizing data flows or system design

How to Use

Describe the mockup in natural language:

"Generate an image of a dashboard showing user engagement metrics with a sidebar navigation, using a clean modern design with blue accent colors"

Best Practices

Reference existing design system colors/patterns in descriptions
Generated images save to assets/ by default
Use for exploration, not final implementation
Follow up with coded Storybook components for production

Example Prompts

Use Case	Prompt Example
Dashboard mockup	"A meeting insights dashboard with cards showing action items, sentiment trends, and speaker breakdown"
Mobile view	"Mobile-first meeting summary view with collapsible sections and swipe actions"
Error state	"Error message UI showing a failed CRM sync with retry option and helpful guidance"
Flow diagram	"User flow diagram from meeting recording to CRM update showing each step"

Anti-Patterns

🚩 Single option - Always explore 2-3 directions 🚩 Missing states - All AI states required 🚩 States without flows - Always include Flow_* stories 🚩 Missing interactive demo or walkthrough 🚩 Loose components/views at initiative root 🚩 Confident wrongness - Show uncertainty 🚩 Surveillance vibes - "Helps YOU" not "reports ON you" 🚩 Prototype starts at the feature, not at the user's natural entry point 🚩 No discovery flow - How does the user know this exists? 🚩 No activation/onboarding flow - First-time experience missing 🚩 No "day 2" story - What does the returning user see?

prototype-builder