UI First Builder

Create beautiful, functional UI immediately. No questions. No waiting.

<core_principle>

The First-Prompt Promise

User describes idea → User sees working UI → Same prompt, no follow-up needed

This is what makes Lovable magical. We replicate it here. </core_principle>

<defaulttoaction> NEVER ask:

"How many pages do you want?" → Infer from description, start with essential pages
"What color scheme?" → Read root DESIGN.md (the design contract); if absent,

trigger design identity generation first (design-craft two-pass → DESIGN-TEMPLATE.md). The identity file is how we decide without asking — distinctive per project.

"What features do you need?" → Infer standard features for this app type
"Should it be responsive?" → ALWAYS responsive, mobile-first

ALWAYS do:

Create complete, working pages
Include realistic mock data (based on language setting in CLAUDE.md)
Add hover states and transitions
Make it look professional immediately

</defaulttoaction>

<component_architecture>

File Structure (Next.js 16 App Router)

src/
├── app/
│   ├── layout.tsx        # Root layout with providers
│   ├── page.tsx          # Home/Dashboard
│   ├── globals.css       # Tailwind + custom styles
│   └── [feature]/
│       └── page.tsx      # Feature pages
├── components/
│   ├── ui/               # shadcn/ui components
│   ├── layout/           # Header, Sidebar, Footer
│   ├── features/         # Feature-specific components
│   └── shared/           # Reusable components
├── lib/
│   ├── utils.ts          # cn() helper
│   └── mock-data.ts      # Realistic mock data
├── stores/               # Zustand stores
└── types/                # TypeScript types

</component_architecture>

<shadcn_components>

shadcn/ui Components to Use

Always Available (assume installed)

Button, Card, Input, Label, Textarea
Dialog, Sheet, Dropdown Menu, Popover
Table, Tabs, Avatar, Badge, Separator
Select, Checkbox, Radio Group, Switch
Toast (sonner), Calendar, Date Picker
Command (for search), Skeleton (loading)

Usage Pattern

import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Input } from "@/components/ui/input"

DO NOT use components that don't exist

No custom components pretending to be shadcn
Stick to official shadcn/ui component list

</shadcn_components>

Mock Data Guidelines

Mock data language depends on project language setting in CLAUDE.md.

✅ GOOD Mock Data (English - Default)

const mockUsers = [
  { id: 1, name: "John Smith", email: "[email protected]", role: "Admin" },
  { id: 2, name: "Sarah Johnson", email: "[email protected]", role: "User" },
  { id: 3, name: "Michael Davis", email: "[email protected]", role: "Editor" },
]

const mockProducts = [
  { id: 1, name: "House Blend Drip Coffee", price: 4.50, stock: 45 },
  { id: 2, name: "Matcha Green Tea Latte", price: 5.25, stock: 32 },
  { id: 3, name: "Hot Chocolate", price: 3.75, stock: 28 },
]

const mockStats = {
  totalRevenue: 15842,
  ordersToday: 47,
  newCustomers: 12,
  conversionRate: 3.2,
}

❌ BAD Mock Data (Lazy/Obvious)

// NEVER DO THIS
const users = [
  { name: "Test User", email: "[email protected]" },
  { name: "User 1", email: "[email protected]" },
]

const products = [
  { name: "Product A", price: 100 },
  { name: "Lorem Ipsum", price: 999 },
]

Mock Data Location

Always create: src/lib/mock-data.ts Export typed data for components to import </mockdatarules>

<styling_rules>

Styling Guidelines

Color Philosophy

Source of truth: root DESIGN.md tokens — every color traces to one
Cards: solid surface with subtle shadow (bg-card shadow-sm border)
Text: never pure black — use the DESIGN.md text token
Accent: ONE brand accent from DESIGN.md, never a raw palette default
Avoid: everything in design-craft/AVOID-LIST.md (gradients-by-default, neon, glassmorphism)

Spacing System

Page padding: p-4 md:p-6 lg:p-8
Card padding: p-4 md:p-6
Component gap: gap-4 or gap-6
Section margin: mb-6 or mb-8

Typography

Headings: text-2xl font-semibold (page title), text-lg font-medium (section)
Body: text-sm or text-base
Muted: text-slate-500 or text-muted-foreground
NO Inter everywhere - use system font stack (already in Tailwind)

Responsive Pattern

// Mobile-first, always
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
  {/* Cards */}
</div>

<div className="flex flex-col md:flex-row gap-4">
  {/* Layout items */}
</div>

</styling_rules>

<page_templates>

Common Page Patterns

Dashboard Page

export default function DashboardPage() {
  return (
    <div className="p-4 md:p-6 space-y-6">
      {/* Stats Row */}
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
        <StatCard title="Today's Revenue" value="$12,450" change="+12%" />
        <StatCard title="Orders" value="47" change="+5%" />
        {/* ... */}
      </div>
      
      {/* Main Content */}
      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
        <Card className="lg:col-span-2">
          {/* Chart or Table */}
        </Card>
        <Card>
          {/* Recent Activity */}
        </Card>
      </div>
    </div>
  )
}

List/Table Page

export default function ListPage() {
  return (
    <div className="p-4 md:p-6 space-y-4">
      {/* Header with Search + Add Button */}
      <div className="flex flex-col md:flex-row md:items-center justify-between gap-4">
        <h1 className="text-2xl font-semibold">Products</h1>
        <div className="flex gap-2">
          <Input placeholder="Search..." className="w-full md:w-64" />
          <Button>Add Product</Button>
        </div>
      </div>
      
      {/* Table */}
      <Card>
        <Table>
          {/* ... */}
        </Table>
      </Card>
    </div>
  )
}

Form Page

export default function FormPage() {
  return (
    <div className="p-4 md:p-6 max-w-2xl mx-auto">
      <Card>
        <CardHeader>
          <CardTitle>Add New Product</CardTitle>
        </CardHeader>
        <CardContent>
          <form className="space-y-4">
            {/* Form fields */}
            <div className="flex justify-end gap-2">
              <Button variant="outline">Cancel</Button>
              <Button>Save</Button>
            </div>
          </form>
        </CardContent>
      </Card>
    </div>
  )
}

</page_templates>

<interaction_states>

Always Include These States

Loading State

// Use Skeleton from shadcn
<Skeleton className="h-4 w-full" />
<Skeleton className="h-32 w-full" />

Empty State

<div className="flex flex-col items-center justify-center py-12 text-center">
  <Package className="h-12 w-12 text-slate-300 mb-4" />
  <h3 className="text-lg font-medium">No items yet</h3>
  <p className="text-slate-500 mb-4">Start by creating your first item</p>
  <Button>Add New Item</Button>
</div>

Hover/Active States

// Cards
<Card className="hover:shadow-md transition-shadow cursor-pointer">

// List items  
<div className="hover:bg-slate-50 transition-colors">

// Buttons already have states from shadcn

</interaction_states>

<output_checklist>

Before Completing, Verify:

All pages render without errors
Mock data looks realistic (per language setting)
Responsive design works (mobile → desktop)
All buttons have hover states
No "Lorem ipsum" or "Test" placeholder text
shadcn/ui components used correctly
TypeScript types defined for all data
File structure follows convention
npm run dev will work immediately

</output_checklist>

<anti_patterns>

What NOT To Build

❌ Don't Create

Complex nested routing before basic pages work
Custom design system (use shadcn)
Authentication flow before main UI
API routes before UI exists
Database schema before seeing UI needs

❌ Don't Style

Gradient backgrounds on light mode
Neon/bright accent colors
Pure black (#000) text
Inconsistent spacing
Different fonts per section

❌ Don't Assume

User has specific components installed (ask shadcn to add)
Complex state management needed first
User wants to see architecture diagram
User needs explanation before seeing UI

</anti_patterns>

ui-first-builder

Installation

Similar popular skills

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md