---
name: frontend-design-playbook
description: Build frontends that don't look like AI slop by assembling and adapting components from the best free libraries instead of inventing UI from scratch. Use when the user wants to build or redesign a web UI, needs component recommendations, wants their app to look professionally designed, asks how to make AI-generated frontends look good, or needs the right component for a specific job (forms, tables, dashboards, AI/chat interfaces, marketing pages). Contains the full component map of shadcn/ui, COSS UI, and Beautiful UI, the transitions.dev motion library, the endpoints to fetch any component's live code, and the integration rules that keep a UI coherent. Also use when the user asks about animations, transitions, or micro-interactions for a web UI.
---

# The frontend design playbook

AI-generated UI looks like slop for one reason: the agent invents components from scratch instead of using the ones professional designers already built. The fix isn't becoming a designer. It's working like a builder with a parts catalog: know what exists, pick the right part, fetch its real code, and adapt it to the app's foundation. This skill is that catalog plus the assembly rules.

The libraries here are free to use, and each has a distinct job:

- **shadcn/ui** — the foundation. The default component system for React/Tailwind apps; everything else layers on top of it. MIT.
- **COSS UI** (coss.com/ui) — the polished app layer. Cal.com's design system, built on Base UI. Denser, production-tuned components; the evolution of Origin UI. MIT. Note: early development, expect occasional breaking changes.
- **Beautiful UI** (beautifului.dev) — the AI-interface layer. Twenty extremely crafted components for agent products: chat, thinking states, approvals, streaming. MIT. If the app has an AI feature, this is where its UI comes from.
- **transitions.dev** — the motion layer. A curated collection of reusable CSS transitions with proper motion tokens and reduced-motion guards built in, plus its own official agent skill. Free tier is copy/CLI-accessible; a Pro tier exists behind sign-in.

## Rule zero: never invent what already exists

Before writing any component from scratch, check the maps below. If the component (or something close) exists, fetch its real code and adapt it. Hand-rolled versions of solved components (dialogs, comboboxes, date pickers, data tables) are where accessibility bugs, jank, and the slop look come from. Scratch-building is reserved for genuinely novel interactions.

## The component maps

### shadcn/ui — the foundation (ui.shadcn.com)

Layout & structure: Sidebar, Resizable, Separator, Scroll Area, Aspect Ratio, Card, Sheet, Drawer, Tabs, Collapsible, Accordion.
Navigation: Navigation Menu, Menubar, Breadcrumb, Pagination, Command (cmd-k palette), Dropdown Menu, Context Menu.
Forms & input: Form (react-hook-form + zod wiring), Input, Textarea, Select, Combobox, Checkbox, Radio Group, Switch, Slider, Input OTP, Label, Button, Toggle, Toggle Group, Calendar, Date Picker, Field.
Feedback & status: Alert, Alert Dialog, Dialog, Sonner (toasts), Progress, Skeleton, Badge, Tooltip, Hover Card, Popover, Spinner, Empty.
Data display: Table, Data Table (TanStack wiring), Chart (Recharts wiring), Avatar, Carousel, Typography.

When to reach for it: everything structural, every form, and any time no other library has a better version. Its blocks (ui.shadcn.com/blocks) also ship full sections: dashboards, login pages, sidebars.

### COSS UI — the polished app layer (coss.com/ui)

Full set: Accordion, Alert, Alert Dialog, Autocomplete, Avatar, Badge, Breadcrumb, Button, Calendar, Card, Checkbox, Checkbox Group, Collapsible, Combobox, Command, Context Menu, Date Picker, Dialog, Drawer, Empty, Field, Fieldset, Form, Frame, Group, Input, Input Group, Kbd, Label, Menu, Meter, Number Field, OTP Field, Pagination, Popover, Preview Card, Progress, Radio Group, Scroll Area, Segmented Control, Select, Separator, Sheet, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toast, Toggle, Toggle Group, Toolbar, Tooltip. Plus hooks (useMediaQuery, useCopyToClipboard) and particles: pre-assembled patterns like auth forms and tables.

When to reach for it: dense application UIs (dashboards, settings, admin panels) where the Cal.com-style tighter polish beats shadcn's defaults, and for components shadcn lacks or does less well: Autocomplete, Number Field, Segmented Control, Meter, Toolbar, Kbd, Frame, Input Group. Caution: it's built on Base UI, shadcn on Radix; both can live in one app, but pick ONE library as the base for each surface rather than alternating per-component, or focus/portal behaviors and design language drift.

### Beautiful UI — the AI-interface layer (beautifului.dev)

Full set, numbered as the site lists them: Loading State (pixel-grid loaders with elapsed time), Thinking (expandable reasoning/search/coding traces), Streaming Text (streamed answers with inline sources and follow-ups), Approval Card (human-in-the-loop questions before acting), Tool Chips (tool calls as compact chips), Task Rows (live agent task status), Chat (tabbed chat panel with composer), Prompt Bar (composer with @ sources, / commands, model picker, dictation), Recommendation Card (suggestion with confidence meter), Context Cards (retrieved knowledge chunks with sources), Diff Table (AI-proposed edits in tabular data), Records Table (CRM-style grid), Filter Table (status chips reorganizing live data), Sidebar Nav (collapsible workspace/chat nav), Search (command search with empty state), Flowchart (workflow trigger/condition canvas), Insight Cards (paged insights with live charts), Code Block (line-numbered listing and diff), Fine-tune Card (inspector-style property controls), Selection Actions (highlight-to-rewrite).

When to reach for it: any AI-native surface. Never hand-roll a thinking state, streaming answer, approval flow, or tool-call display; these twenty solve exactly those problems and are the difference between an AI product that looks like a demo and one that looks like a product.

### transitions.dev — the motion layer (transitions.dev)

Free transitions, each a self-contained CSS snippet with semantic custom properties, namespaced classes, and a prefers-reduced-motion guard: Card resize (smooth size change), Number pop-in (digit flip with blur and stagger), Notification badge (diagonal slide with spring), Text states swap (blur crossfade between texts), Menu dropdown (origin-aware open/close), Modal open/close (scale-based), Panel reveal, Page side-by-side (forward/back navigation), Icon swap (scale and blur), Success check (confirmation with SVG path draw), Avatar group hover (spring with neighbor falloff), Error state shake (validation shake with auto-revert). More exist behind the Pro sign-in.

When to reach for it: every micro-interaction in the app. These snippets ARE the "one motion language" rule made concrete: adopt its motion tokens as the project's single motion system and pull every transition from here instead of improvising easings per component. The reduced-motion guards ship included, so accessibility comes along.

Important: this library has no open-source license on its code, so its snippets are used in projects (that's what the site offers them for) but never redistributed inside other products, skill files, or component packs. Fetch per project; don't bundle.

The maps above say what exists; the code always comes fresh from the source:

- **shadcn/ui:** `npx shadcn@latest add [component]` installs into the project with dependencies. Raw component JSON lives at `https://ui.shadcn.com/r/[component-name].json` (fetchable directly). The shadcn MCP server (`npx shadcn@latest mcp init`) gives agents browse/search/install over this and any shadcn-compatible registry, and `https://ui.shadcn.com/llms.txt` indexes the docs for agents.
- **COSS UI:** agent-readable docs index at `https://coss.com/ui/llms.txt`; each component's docs and code at `https://coss.com/ui/docs/components/[component-name]`; install commands are on each component page, and the repo is `github.com/cosscom/coss` (components under apps/ui, MIT).
- **Beautiful UI:** copy-paste from `https://www.beautifului.dev/` (each numbered component links to its code); license at `https://www.beautifului.dev/license` (MIT).
- **transitions.dev:** copy buttons on `https://transitions.dev/` emit the full snippet; CLI: `npx transitions-pro add [name]` (free, no account) and `npx transitions-pro list` to see everything; best of all, install its official agent skill with `npx skills add Jakubantalik/transitions.dev`, which gives the agent per-transition reference files maintained by the author and always in sync with the site. When this playbook and that skill are both installed, motion questions defer to that skill's references.

Workflow for the agent: identify the need → find it in the maps → fetch that component's current code → adapt it to the project's foundation (next section). Fetch only what the task needs, never the whole library.

## The integration rules (this is where taste lives)

Grabbing good components and still producing slop is possible; it happens when parts don't agree with each other. These rules keep the assembly coherent:

1. **One foundation, declared once.** The project picks its base (usually shadcn) and its accent libraries, and that decision is written down in the repo (a DESIGN.md or a comment block in the global CSS) so every future session makes the same choice. Mixing three libraries' versions of the same component across one app is the fastest route back to slop.
2. **Tokens before components.** Before importing anything, set the design tokens: the neutral scale, ONE accent color, the radius value, the font pair (one for UI, optionally one for display), spacing rhythm. Every fetched component gets re-pointed at these tokens on arrival. A library component with its default palette dropped into an app with different tokens is what "AI-built" looks like.
3. **Adapt on arrival, not later.** The edit pass happens the moment a component lands: swap colors to the project's variables, match the radius, match the spacing scale, strip variants the app won't use. Components adapt to the app; the app never bends to a component.
4. **Density is a decision.** Marketing pages breathe (generous spacing, larger type); app surfaces are dense (COSS-style tight spacing, smaller type, more per screen). Pick per surface and hold it. Half-dense screens read as unfinished.
5. **One motion language.** Animations come from one source and one duration/easing scale, and transitions.dev is the designated source: adopt its tokens, pull its snippets, and stop hand-writing easings. Mixing one library's spring physics with another's linear fades is subliminal slop. Default stance: less motion than feels fun; transitions under ~200ms; animate only entrances, exits, and state changes that need explaining. Most UIs need fewer animations than builders want to add.
6. **Contrast and hierarchy over decoration.** If a screen looks bland, the fix is almost never a gradient; it's stronger type hierarchy (size/weight jumps), more whitespace, or one deliberate accent. Delete decoration before adding it.
7. **States are part of the component.** Every interactive element ships with hover, focus-visible, disabled, loading, error, and empty states, and the fetched libraries include them; deleting them in adaptation is a regression. Empty states (shadcn's Empty, Beautiful UI's search empty state) are designed, not blank.
8. **Dark mode from the tokens.** If the app supports it, both modes come from the same token layer on day one. Retrofitting is where inconsistency creeps in.
9. **Accessibility rides along for free — don't break it.** These libraries' keyboard navigation, focus management, and ARIA are the hard-won part. Adaptations touch classes and tokens, not the structural markup and handlers.
10. **Steal composition, not components, from elsewhere.** Inspiration sites and other products inform layout and feel; the code still comes from the three libraries. Screenshot-and-clone of someone's actual design is off the table; pattern-level learning is the whole game.

## Assembly recipes

- **SaaS dashboard:** shadcn Sidebar + Data Table + Chart + Card; COSS Segmented Control, Number Field, and Meter for the dense controls; Sonner for toasts; skeletons on every async region.
- **AI product:** shadcn foundation; Beautiful UI Chat or Prompt Bar as the core surface, Thinking + Tool Chips + Streaming Text for the response area, Approval Card for human-in-the-loop, Task Rows for background work; Context Cards when retrieval is visible.
- **Marketing/landing page:** shadcn primitives with the density dialed open, one display font, one accent, generous whitespace; the copy carries it, so fewer components, larger type.
- **Internal tool/admin:** COSS UI as the surface layer (its density suits it), shadcn Data Table for the grids, Command for power-user navigation.
- **Forms anywhere:** shadcn Form wiring (validation included) or COSS Field/Fieldset; never hand-rolled validation UI.

## Running this skill

When the user asks to build a UI: establish or read the foundation (tokens, base library, density) first, then map every screen element to a component from the maps, fetch the live code for each, adapt to the tokens, and only scratch-build what the maps genuinely lack. When the user brings existing slop to fix: diagnose against the integration rules (usually it's mixed foundations, default palettes, no hierarchy, or motion soup), then re-map the screen to real components and rebuild surface by surface. When the user asks "which component for X": answer from the maps with the specific library and name, and note the fetch command. Always tell the user which library each piece came from: the MIT libraries (shadcn, COSS UI, Beautiful UI) want their attribution traveling with the code, and transitions.dev snippets are used in the project but never redistributed onward.