{/* invisible! */}
// FIX: Apply gradient directly on the section
```
#### If installation fails:
1. Check error message — usually a missing peer dependency
2. Try `npm install {missing-dep}` then retry
3. If component URL is wrong, search 21st.dev for the correct path
4. Last resort: fetch the component code via WebFetch and create files manually
### Phase 6: Page Composition
#### Layout Normalization (DO THIS FIRST)
Before composing, normalize the layout of all installed components so they play well together. 21st.dev components from different authors often have conflicting container widths, padding, and alignment. Fix this upfront:
1. **Pick one container width** for the entire page: `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8`
2. **Open each installed component file** and check if it has its own container/max-width
3. **Either**: remove the component's internal container and wrap it externally, **or** ensure it matches your chosen width
4. **Check text alignment**: some components center-align content, others left-align. Normalize.
5. **Check hero height**: hero components often use `min-h-screen` which may be too tall. Adjust to `min-h-[80vh]` or less if needed.
#### Composition Patterns
**Landing Page:**
```tsx
{/* sticky top-0 z-50 */}
{/* min-h-[80vh] — NOT min-h-screen */}
{/* py-20 bg-muted/50 */}
{/* py-16 */}
{/* py-20 bg-muted/50 */}
{/* py-16 */}
{/* py-20 bg-primary text-primary-foreground */}
```
**Dashboard:**
```tsx
{/* navigation items */}
{/* toolbar, breadcrumbs */}
{/* stat cards */}
{/* data table or content */}
```
**Auth Flow:**
```tsx
```
**Multi-page App Layout:**
```tsx
// app/layout.tsx
{children}
```
#### Spacing & Layout Rules
- Sections: `py-16 md:py-20 lg:py-24` (responsive vertical padding)
- Content width: `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8`
- Card grids: `grid gap-4 sm:grid-cols-2 lg:grid-cols-3`
- Alternating section backgrounds: use `bg-background` and `bg-muted/50`
#### Dark Mode Setup
21st.dev components use CSS variables with `dark:` prefixes. Ensure:
```tsx
// In layout.tsx or providers
import { ThemeProvider } from "next-themes"
{children}
```
Install next-themes: `npm install next-themes`
#### Font Setup
```tsx
import { Geist, Geist_Mono } from "next/font/google";
const geist = Geist({ variable: "--font-sans", subsets: ["latin"] });
const geistMono = Geist_Mono({ variable: "--font-mono", subsets: ["latin"] });
```
### Phase 7: Customization & Refinement
After installing components, customize them to fit the project:
1. **Content** — Replace placeholder text, images, and links with real content
2. **Colors** — Choose brand color intentionally (see Color Selection below)
3. **Typography** — Ensure consistent font sizes and weights
4. **Spacing** — Align padding/margin with the rest of the page
5. **Animations** — Add or tune transitions using Tailwind or framer-motion
6. **Responsiveness** — Test at mobile, tablet, and desktop breakpoints
#### Color Selection (CRITICAL — Avoid AI Purple Bias)
AI models have a strong bias toward purple/violet as the default brand color. This is because purple dominates tech/AI branding (Figma, Notion AI, Copilot) and shadcn/ui examples. Using purple every time is an obvious AI fingerprint — like using the Sparkles icon.
**Rule: NEVER default to purple.** Choose colors based on the product type and industry:
| Product / Industry | Recommended Primary | Avoid |
|---|---|---|
| Finance / Banking | Deep blue (`oklch(0.45 0.15 250)`), Navy, Teal | Purple, Neon |
| Health / Wellness | Green (`oklch(0.55 0.18 155)`), Teal, Soft blue | Red, Purple |
| E-commerce / Retail | Orange (`oklch(0.65 0.2 50)`), Coral, Amber | Muted grays |
| Developer tools | Emerald (`oklch(0.55 0.17 160)`), Cyan, Slate | Purple (overused) |
| Creative / Design | Rose (`oklch(0.6 0.18 10)`), Amber, Indigo | Plain blue |
| Education | Blue (`oklch(0.5 0.16 250)`), Teal, Green | Neon, Dark themes |
| Food / Restaurant | Warm red (`oklch(0.55 0.22 25)`), Orange, Olive | Cold blues |
| AI / Writing tools | Teal (`oklch(0.55 0.12 195)`), Blue-green, Slate | Purple (cliché!) |
| Enterprise / B2B | Slate blue (`oklch(0.5 0.1 255)`), Navy, Steel | Bright neons |
| Social / Community | Coral (`oklch(0.6 0.17 25)`), Sky blue, Warm pink | Dull grays |
**If the user specifies a brand color, use it.** If not, pick from the table above — but NEVER purple unless the user explicitly asks for it.
**How to apply the chosen color:**
```css
/* globals.css — example with teal for an AI writing tool */
:root {
--brand: oklch(0.55 0.12 195); /* Teal, NOT purple */
}
```
Then use `bg-brand`, `text-brand`, `border-brand/30` etc. throughout the site. Update hero gradients, CTA buttons, icon backgrounds, and accent colors to match.
#### Hero Visual Quality Checklist
Hero sections make or break the first impression. After installing a hero component, ensure:
- **Heading contrast**: On colored/gradient backgrounds, use solid `text-foreground` instead of gradient-text effects (`bg-clip-text text-transparent`) which can be too faint
- **Background gradients**: Apply gradients directly on the section element (`bg-gradient-to-b from-[color] via-[color] to-white`) — don't layer decorative gradient divs behind opaque parents
- **Product mockups**: For SaaS sites, build a realistic inline mockup (editor, dashboard, chat) instead of using a placehold.co image. Include window chrome (red/yellow/green dots), sidebar, content area, and status indicators. This dramatically improves perceived quality.
- **CTA styling**: Use `rounded-xl`, visible shadows (`shadow-lg`), and brand colors. Add hover effects (`hover:-translate-y-0.5 transition-transform`)
- **Radial glow accents**: Add subtle radial gradients using `rgba()` colors (not oklch) for depth behind hero content
- **Avoid AI-cliché icons**: NEVER use Sparkles/Stars/Wand icons — they instantly signal "AI-generated." Use minimal alternatives: a pulsing dot indicator, a small "NEW" badge, or just well-styled text. The goal is to look like a senior human designer made it, not an AI.
- **Avoid AI-cliché colors**: NEVER default to purple/violet. Choose colors from the Color Selection table based on the product type. Purple is the #1 AI color bias.
#### CSS Variable Theming
```css
/* globals.css */
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
--primary: 0 0% 9%;
--primary-foreground: 0 0% 98%;
/* ... customize these to match brand */
}
.dark {
--background: 0 0% 3.9%;
--foreground: 0 0% 98%;
/* ... dark variants */
}
}
```
### Phase 8: Verification (THOROUGH)
This phase catches the bugs that ruin the user's first impression. Do not skip any step.
#### Step 1: Build passes
```bash
npm run build
```
Fix any TypeScript or build errors before proceeding.
#### Step 2: Visual inspection (MOST IMPORTANT)
Run `npm run dev` and **actually look at every section** of the page:
1. **Take a screenshot** or use preview_screenshot — look at the full page from top to bottom
2. Check for these common problems:
- **Blank/white sections** — content exists in DOM but invisible? Check CSS variables, text color matches background
- **Content overflow** — text or elements going off-screen to the right? Check container width, remove `text-center` or adjust `max-w`
- **Giant blank spaces** — hero taking up too much vertical space? Reduce `min-h-screen` to `min-h-[80vh]`
- **Misaligned sections** — some sections centered, others left-aligned? Normalize container classes
- **Broken images** — placeholder URLs not loading? Replace with real images or remove
3. **Scroll through the entire page** — every section must be visible and properly styled
#### Step 3: Responsiveness
Test at 3 breakpoints using preview_resize or browser devtools:
- Mobile (375px): single column, readable text, no horizontal overflow
- Tablet (768px): proper grid transition
- Desktop (1280px): full layout as designed
#### Step 4: Interactions
- Click every button and link
- Test navbar dropdown/mobile menu
- Test any toggles or tabs
#### Step 5: Console check
No errors in browser console. Warnings about missing images or unused vars are acceptable.
**If any visual issue is found in Steps 2-3, fix it immediately before presenting to the user.** The most common fixes are: adjusting container width, fixing CSS variable colors, and reducing hero height.
## Advanced Patterns
### Component Dependency Chain
Some 21st.dev components depend on other components. The npx installer handles this automatically, but be aware:
- A `Dialog` component may install `Button` as a dependency
- If you've already customized `Button`, the dialog install might overwrite it
- Install from leaf components up, and keep track of what's been customized
### Mixing Authors Safely
When combining components from different authors:
1. Check that all use the same CSS variable naming (most shadcn-based ones do)
2. Normalize border-radius: pick one style and apply globally via CSS variables
3. Ensure animation timing is consistent (ease-in-out, duration-200)
4. Watch for conflicting Tailwind config extensions
### Building Component Variations
If 21st.dev doesn't have exactly what you need:
1. Find the closest match
2. Install it
3. Modify the source code directly (you own it!)
4. The component file is in your project — edit freely
## Updating Component Knowledge
**At the start of every build session**, refresh your knowledge of available components by browsing the relevant category pages on 21st.dev. The platform adds new components daily, so what was the best option last week might be surpassed by something better today.
This means: if you last browsed `https://21st.dev/s/hero` an hour ago, browse it again if you're starting a new build. Fresh data leads to better component choices.
## Error Recovery
| Problem | Solution |
|---------|----------|
| Component not found | Try alternative spellings, browse the parent category, or search with WebSearch |
| npx install fails | Check for missing peer deps, verify URL format, try `npm install` for deps first |
| Component looks wrong | Check if Tailwind config was updated, verify CSS variables are defined |
| Dark mode broken | Ensure ThemeProvider wraps the app, check CSS variable definitions |
| TypeScript errors | Check component's expected props, install missing @types packages |
| Styling conflicts | Check for conflicting Tailwind classes, CSS variable naming collisions |
| 21st.dev unreachable | Use WebSearch to find component names, construct install URLs from cached knowledge |
| Component too complex | Simplify by removing unused features from the source code |
| `render` prop errors | Component uses @base-ui/react pattern — convert to `asChild` pattern |
| Giant blank space | Hero/section using `min-h-screen` — reduce to `min-h-[80vh]` or remove |
| Content off-screen right | Container width mismatch — add `max-w-7xl mx-auto` wrapper |
| Invisible text | CSS variables undefined — check `globals.css` has all required color tokens |
| Faint/invisible cards | Background gradient too subtle — use `bg-card border border-border/60 shadow-sm` |
| Marquee cards hidden | Edge fade `w-1/3` too wide — reduce to `w-1/6` |
| Gradient not showing | Using `-z-10` behind parent `bg-background` — apply gradient directly on section |
| oklch gradient broken | oklch renders poorly in `radial-gradient()` — use `rgba()` hex values instead |
| Heading invisible on gradient | `bg-clip-text text-transparent` too faint — use solid `text-foreground` |
## MCP Setup (Optional)
For AI-powered component generation, set up the Magic MCP:
```bash
npx @21st-dev/cli@latest install claude --api-key
```
Get API key: https://21st.dev/settings/api-keys
Manual config in `.claude/settings.json`:
```json
{
"mcpServers": {
"@21st-dev/magic": {
"command": "npx",
"args": ["-y", "@21st-dev/magic@latest"],
"env": { "API_KEY": "your-api-key" }
}
}
}
```
MCP provides these tools:
- `21st_magic_component_builder` — Generate components from descriptions
- `21st_magic_component_inspiration` — Browse component ideas
- `logo_search` — Find company logos (via SVGL)