Menu
Use when building, styling, or theming UI components, pages, layouts, dashboards, charts, tables, or forms for SaaS products.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Consolidated view of the add-pro ecosystem - commands, skills, relationships and dependencies. Loaded by /add as source of truth.
Source of truth for ADD doc rules, depth floors, IDs, refs, validation gate. Load before any doc write.
Use when running agent-judged QA validation (read-PNG by default; the playwright plugin adds live driving) โ the Level C judge rubric, severity taxonomy, dual-judge (@ux-agent review โฅ @qa-agent) method, report schema/template, and the config.json/screens.json formats. Consumed by /add.qa and both judges.
Use when a state-materializing command starts or is asked to upgrade โ reads the setup receipt, compares the recorded contract against the shipped one, executes the declared upgrade deltas sequentially, and rewrites the receipt even on a verified-current no-op. Consumed by /add.qa-setup STEP 1.5 and STEP 11.
Internal skill for developing ADD framework artefacts (commands, skills, agents, scripts). Use when add-framework--plan analyzes viability of new framework features, when add-framework--build implements framework artefacts, or when creating/modifying commands, skills, or agents. Always use this skill before proposing or implementing changes to the framework itself.
Generate a code-free QA/E2E specification (reachability intent, UX acceptance criteria, functional E2E scenarios, capture states, target viewports, a11y expectations) from about.md + design.md + plan-*.md, and author the _tests/screens.json screen catalog by read-merge-write. Loaded by add.plan's qa-pipeline QA-Spec step.
| name | add-ux-design |
| description | Use when building, styling, or theming UI components, pages, layouts, dashboards, charts, tables, or forms for SaaS products. |
You are a UX designer-engineer, not a layout generator.
Your goal is to create memorable, high-craft SaaS interfaces that:
Use this skill when the request involves any of:
Trigger keywords: design, UI, UX, component, page, layout, dashboard, mobile, responsive, dark mode, animation, skeleton, empty-state, loading-state, onboarding, settings, billing, auth.
Do NOT load this skill for:
add-backend-developmentadd-database-development| File | Purpose |
|---|---|
{{skill:add-ux-design/design-direction.md}} | Design Thinking, Quality Score, Output Structure |
{{skill:add-ux-design/ux-laws-principles.md}} | UX Laws, Cognitive Load, Mental Models |
{{skill:add-ux-design/modern-patterns.md}} | Interaction patterns, visual trends, performance UX |
{{skill:add-ux-design/saas-patterns.md}} | SaaS surface patterns (Dashboard, Settings, Billing, etc.) |
{{skill:add-ux-design/ux-writing.md}} | Microcopy, error messages, empty states |
{{skill:add-ux-design/design-contract.md}} | Layout tree notation, component composition, Design Contract Dimensions |
{{skill:add-ux-design/critique-rubric.md}} | The 9-item critique rubric (@ux-agent critique mode only) |
| Library | Doc file |
|---|---|
| shadcn | {{skill:add-ux-design/shadcn-docs.md}} |
| tailwind | {{skill:add-ux-design/tailwind-v3-docs.md}} |
| motion | {{skill:add-ux-design/motion-dev-docs.md}} |
| recharts | {{skill:add-ux-design/recharts-docs.md}} |
| @tanstack/react-table | {{skill:add-ux-design/tanstack-table-docs.md}} |
| @tanstack/react-query | {{skill:add-ux-design/tanstack-query-docs.md}} |
| @tanstack/react-router | {{skill:add-ux-design/tanstack-router-docs.md}} |
| Group | Library โ purpose (install) |
|---|---|
| Core | shadcn/ui โ components; tailwindcss โ styling; motion โ animations |
| Data | recharts โ charts; @tanstack/react-table โ tables; @tanstack/react-query โ data fetching |
| UX | sonner โ toasts (npx shadcn add sonner); vaul โ mobile drawers (npx shadcn add drawer); cmdk โ command palette (npx shadcn add command); nuqs โ URL state; @tanstack/react-virtual โ 1000+ items |
Full details:
design-direction.md
Before writing code, ALWAYS define:
What action should this interface enable? Is it persuasive, functional, exploratory?
Minimal Clean | Editorial | Luxury Refined | Industrial Utilitarian | Playful | Data-Dense
โ ๏ธ Do NOT blend more than two tones.
"If this were screenshotted with the logo removed, how would someone recognize it?"
This anchor MUST be visible in the final UI.
| Dimension | Score 1-5 |
|---|---|
| Aesthetic Impact | How distinctive and memorable? |
| Context Fit | Does it suit the product/audience? |
| Implementation Feasibility | Can it be built cleanly? |
| Performance Safety | Will it remain fast/accessible? |
| Consistency Risk | Can it scale across screens? |
DQS = (Impact + Fit + Feasibility + Performance) โ Consistency Risk
| DQS | Action |
|---|---|
| 12-15 | Execute fully |
| 8-11 | Proceed with discipline |
| 4-7 | Reduce scope |
| โค3 | Rethink direction |
NEVER ship with DQS < 8.
Full details:
ux-laws-principles.md
| Law | Rule | Application |
|---|---|---|
| Fitts | Larger + closer = easier | Large CTAs, primary actions accessible |
| Hick | More options = slower decision | Max 5-7 visible items, progressive disclosure |
| Miller | 7ยฑ2 chunks | Group info into sections, not long lists |
| Jakob | Users expect patterns | Don't reinvent, follow conventions |
| Doherty | <400ms = flow state | Immediate feedback, optimistic UI |
| Peak-End | Memory = peak + end | Celebrate success, polish at the end |
| Aesthetic-Usability | Beautiful = easier | Invest in visual polish |
Full details:
modern-patterns.md
const handleLike = async () => {
setLiked(true)
try { await api.like(id) } catch { setLiked(false); toast.error("Failed") }
}
| Content Type | Recommendation |
|---|---|
| Feed/timeline | Infinite + virtualization |
| Search results | Pagination |
| Data tables | Pagination + page size selector |
| Gallery/cards | Load more button |
Full details:
saas-patterns.mdโ Dashboard, Settings, Billing, Onboarding, DataTables, Auth, Workspace, Navigation, Forms, Modal, Feedback.
Auto-detect SaaS context from keywords:
| Keywords | Pattern |
|---|---|
| dashboard, metrics, KPIs, analytics | Dashboard |
| settings, preferences, config, profile | Settings |
| billing, pricing, plans, subscription | Billing |
| onboarding, welcome, setup, wizard | Onboarding |
| list, table, CRUD, manage | DataTables |
| login, signup, auth, password | Auth |
| team, members, workspace, invite | Workspace |
| notifications, alerts | Feedback |
| form, input, create, edit | Forms |
| modal, dialog, popup, drawer | Modal |
Multiple contexts: "Team Settings" โ Settings + Workspace.
| Action | Response Time | Feedback Type |
|---|---|---|
| Click/tap | < 100ms | Visual change (scale, color) |
| Form submit | < 500ms show spinner | Disable button + spinner |
| Content load | > 300ms | Skeleton loader |
| Toast display | 3-5s auto-dismiss | Bottom-right (desktop) |
| Animation duration | 200-400ms | Ease-out for exits |
idle โ hover(scale-[1.02]) โ active(scale-[0.98]) โ loading(spinner+disabled) โ success(check)/error(shake) โ idle
| Type | When to Use |
|---|---|
| Spinner | Unknown duration < 4s |
| Progress bar | Known steps/percentage |
| Skeleton | Content placeholder |
| Percentage text | File uploads, long processes |
Full details:
modern-patterns.md
grid-cols, varied item sizesbg-white/10 backdrop-blur-md border border-white/20 shadow-lg shadow-black/5shadow-lg alone (pure black, looks dirty)className="shadow-lg shadow-primary/5"text-2xl md:text-3xl lg:text-4xl font-display font-boldtext-xl md:text-2xl font-display font-semiboldtext-sm md:text-base text-muted-foregroundtext-xs text-muted-foregroundp-4 md:p-6 lg:p-8, grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3p-8 sm:p-4 โ NEVERactive:scale-[0.98] or background change<Input className="text-base" /> (16px). Never text-sm on mobile inputs.| Element | Desktop | Mobile |
|---|---|---|
| Modals | Centered dialog | Bottom drawer (Vaul) |
| Navigation | Sidebar | Bottom nav (5 max) or hamburger |
| Tables | Full table | Cards or horizontal scroll |
| Filters | Inline dropdowns | Drawer/expandable |
| Forms | Inline submit | Sticky bottom + safe-area |
className="fixed bottom-0 inset-x-0 p-4 pb-safe" โ CSS padding-bottom: max(1rem, env(safe-area-inset-bottom))Full details:
ux-writing.md
Every component/page must handle ALL states โ Loading, Error, Empty, Success.
if (isLoading) return <Skeleton className="h-[200px]" />
if (error) return <ErrorState message="Failed to load data" action={<Button onClick={refetch}>Try again</Button>} />
if (!data?.length) return <EmptyState icon={<FileIcon />} title="No items yet" description="Create your first item to get started" action={<Button>Create Item</Button>} />
return <DataDisplay data={data} />
<Link prefetch onMouseEnter={() => prefetch(url)}><Image placeholder="blur" blurDataURL={tiny} />Iron Law: If the design could be mistaken for a template โ restart.
If you catch yourself doing ANY of the patterns below, STOP. Delete. Start over.
| Pattern | Why Bad | Fix |
|---|---|---|
| Default shadcn/Tailwind layout | Generic, forgettable | Define aesthetic direction first |
| Inter/Roboto/system fonts as display | AI clichรฉ, zero personality | Expressive display font + restrained body |
| Purple gradients on white | Most overused SaaS pattern | Subtle, token-based color story |
| Symmetrical, predictable sections | Looks auto-generated | Break grid intentionally |
| Gradients on long text | Hurts readability | Short titles only |
| Desktop-first breakpoints | Mobile afterthought | 320px base always |
| Centered modals on mobile | Bad touch UX | Vaul bottom drawers |
| Generic loading text | Feels slow | Contextual messages |
| No empty states | Confusing | Always design empty |
| Decoration without intent | Visual noise | Every flourish serves the aesthetic thesis |
| Default component styling without customization | Template feel | Customize tokens, spacing, type |
| Skipping Design Thinking "because it's small" | DQS missing | Run the phase always |
| Saying "I'll add personality later" | Later never comes | Intent goes in first |
| Copying a layout without adapting tone | Tone clash | Re-anchor to product tone |
| Blending 3+ aesthetic tones | Visual noise | Max 2 tones |
| Excuse | Reality |
|---|---|
| "It's just a simple page" | Simple pages still need aesthetic direction |
| "The user didn't specify a style" | Default to the project's established tone or define one |
| "shadcn defaults look fine" | Fine โ distinctive. Customize always. |
| "I'll polish it later" | Later never comes. Design intent goes in first. |
| "Mobile can wait" | Mobile-first is MANDATORY, not optional |
prefers-reduced-motion supportfocus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2motion-safe: variants, or guard with @media (prefers-reduced-motion: reduce)| Component | UX Rule | Implementation |
|---|---|---|
| Sidebar | Z-Pattern: LogoโNavโProfile | bg-background + border 1px subtle |
| KPI Cards | Value is hero, label is support | font-display for number, text-muted for label |
| Charts | Less is more - no excessive grid | Subtle grid, bg-popover tooltip |
| Navigation | Active visible but not invasive | text-primary + bg-primary/10 |
| Tables | Data > decoration | Subtle borders, hover row, actions right |
| Forms | Clear labels, inline errors | text-destructive errors, text-muted helpers |
| Buttons | Primary action obvious | One primary per view, rest secondary/ghost |
| Empty States | Guide, don't abandon | Illustration + headline + CTA |
When generating ANY frontend work, ALWAYS include:
/** Design Direction: Minimal Clean + Data-Dense | DQS: 12/15 | Differentiation: ... */<div className="min-h-screen bg-background">
<header className="sticky top-0 z-50 border-b bg-background/95 backdrop-blur">
<div className="container flex h-14 md:h-16 items-center px-4" />
</header>
<div className="container flex flex-col md:flex-row gap-6 p-4 md:p-6">
<aside className="hidden md:block w-64 shrink-0"><nav className="sticky top-20 space-y-2" /></aside>
<main className="flex-1 min-w-0 space-y-6" />
</div>
</div>
<Card className="group cursor-pointer transition-all hover:shadow-lg hover:shadow-primary/5 hover:border-primary/50">
<CardHeader><CardTitle className="group-hover:text-primary transition-colors">{title}</CardTitle></CardHeader>
</Card>
<motion.ul initial="hidden" animate="show"
variants={{ hidden: { opacity: 0 }, show: { opacity: 1, transition: { staggerChildren: 0.05 } } }}>
{items.map(item => (
<motion.li key={item.id} variants={{ hidden: { opacity: 0, y: 10 }, show: { opacity: 1, y: 0 } }}>{item.name}</motion.li>
))}
</motion.ul>
<div className="h-[200px] md:h-[300px] w-full">
<ResponsiveContainer width="100%" height="100%">
<LineChart data={data}>
<CartesianGrid strokeDasharray="3 3" className="stroke-muted" />
<XAxis dataKey="name" className="text-xs" tick={{ fill: 'hsl(var(--muted-foreground))' }} />
<Tooltip contentStyle={{ backgroundColor: 'hsl(var(--popover))', border: '1px solid hsl(var(--border))' }} />
<Line type="monotone" dataKey="value" stroke="hsl(var(--primary))" strokeWidth={2} dot={false} />
</LineChart>
</ResponsiveContainer>
</div>
The layout tree notation, component composition notation, and the canonical Design Contract Dimensions table (11 dimensions, each naming its verification method) live in {{skill:add-ux-design/design-contract.md}}. @ux-layout-agent loads it to author a spec; @qa-agent reads it to know which dimensions are computed-style-verified. Do not restate the table anywhere else.
The 9-item adversarial rubric @ux-agent runs in critique mode, its severity scale, and the empty-critique rule live in {{skill:add-ux-design/critique-rubric.md}}. It binds the CRITIC only โ authors deliberately do not pre-satisfy it.