qodex-ai/ai-agent-skills/component-interface-design

Shadcn UI Designer

Core Design Prompt

When designing any UI, apply this philosophy:

"Design a modern, clean UI following Shadcn principles: apply minimalism with ample white space and simple sans-serif typography; use strategic, subtle shadows for depth and hierarchy; ensure accessibility with high-contrast neutrals and scalable elements; provide beautiful defaults for buttons, cards, and forms that compose modularly; incorporate fluid, non-intrusive animations; maintain a professional palette of soft grays, whites, and minimal accents like purple; output as responsive, customizable React code with Tailwind CSS."

Design Rules

1. Typography Rule

• Limit to 2-3 font weights and sizes per screen
• Use Inter or system fonts for consistency

<h1 className="text-2xl font-semibold">Title</h1>
<p className="text-sm text-muted-foreground">Description</p>

2. Spacing Rule

• 4px-based scale: 4px, 8px, 16px, 24px, 32px
• Tailwind utilities: p-1, p-2, p-4, p-6, p-8

<div className="p-6 space-y-4">
  <div className="mb-8">...</div>
</div>

3. Color Rule

• Base on OKLCH for perceptual uniformity
• Use 50-950 scale grays (background, foreground, muted)
• Subtle accents at 10% opacity to avoid visual noise

<Card className="bg-card text-card-foreground border-border">
  <Button className="bg-primary text-primary-foreground">Action</Button>
  <div className="bg-primary/10">Subtle accent</div>
</Card>

4. Shadow Rule

• 3 levels only:
• shadow-sm: Subtle lift (0 1px 2px) - for cards
• shadow-md: Medium depth (0 4px 6px) - for dropdowns
• shadow-lg: High elevation (0 10px 15px) - for modals

<Card className="shadow-sm hover:shadow-md transition-shadow">

5. Animation Rule

• 200-300ms durations
• ease-in-out curves for transitions
• Subtle feedback only (hovers, state changes) - no decorative flourishes

<Button className="transition-colors duration-200 hover:bg-primary/90">
<Card className="transition-transform duration-200 hover:scale-105">

6. Accessibility Rule

• ARIA labels on all interactive elements
• WCAG 2.1 AA contrast ratios (4.5:1 minimum)
• Keyboard-focus styles matching hover states
• Semantic HTML structure

<button
  aria-label="Submit form"
  className="focus:ring-2 focus:ring-primary focus:outline-none"
>
  Submit
</button>

Workflow

1. Interview User (if details not provided)

• Scope: Full page, section, or specific component?
• Type: Dashboard, form, card, modal, table?
• Target file: Where should this be implemented?
• Requirements: Features, interactions, data to display?

2. Design & Implement

1. Match existing design - align with current UI patterns in the app
2. Build UI first - complete visual interface before adding logic
3. Modular components - break large pages into focused, reusable pieces
4. Apply all 6 rules above strictly
5. Verify accessibility - keyboard navigation, contrast, ARIA labels
6. Test responsiveness - mobile, tablet, desktop

3. Component Structure Pattern

import { Button } from "@/components/ui/button"
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
export function MyComponent() {
  return (
    <div className="container mx-auto p-6 space-y-6">
      <header>
        <h1 className="text-2xl font-semibold">Page Title</h1>
      </header>
      <main className="grid gap-4">
        <Card className="shadow-sm">
          <CardHeader>
            <CardTitle>Section</CardTitle>
          </CardHeader>
          <CardContent>
            {/* Content */}
          </CardContent>
        </Card>
      </main>
    </div>
  )
}

4. Quality Checklist

Before completing, verify:

• [ ] Uses shadcn/ui components where applicable
• [ ] 2-3 font weights/sizes max per screen
• [ ] 4px-based spacing throughout
• [ ] Theme color variables (no hardcoded colors)
• [ ] 3 shadow levels max, strategically applied
• [ ] Animations 200-300ms with ease-in-out
• [ ] ARIA labels on interactive elements
• [ ] WCAG AA contrast ratios (4.5:1 min)
• [ ] Keyboard focus styles implemented
• [ ] Mobile-first responsive design
• [ ] Modular, reusable code structure

Common Patterns

Dashboard Page

<div className="container mx-auto p-6 space-y-6">
  <header className="space-y-2">
    <h1 className="text-2xl font-semibold">Dashboard</h1>
    <p className="text-sm text-muted-foreground">Overview of metrics</p>
  </header>
  <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
    {stats.map(stat => (
      <Card key={stat.id} className="shadow-sm">
        <CardHeader className="pb-2">
          <CardTitle className="text-sm font-medium text-muted-foreground">
            {stat.title}
          </CardTitle>
        </CardHeader>
        <CardContent>
          <div className="text-2xl font-semibold">{stat.value}</div>
        </CardContent>
      </Card>
    ))}
  </div>
</div>

Form Pattern

<form className="space-y-6">
  <div className="space-y-4">
    <div className="space-y-2">
      <Label htmlFor="name">Full Name</Label>
      <Input id="name" placeholder="John Doe" />
    </div>
    <div className="space-y-2">
      <Label htmlFor="email">Email</Label>
      <Input id="email" type="email" placeholder="john@example.com" />
    </div>
  </div>
  <Button type="submit" className="w-full transition-colors duration-200">
    Submit
  </Button>
</form>

Data Table Pattern

<Card className="shadow-sm">
  <CardHeader>
    <CardTitle className="text-xl font-semibold">Recent Orders</CardTitle>
  </CardHeader>
  <CardContent>
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Order ID</TableHead>
          <TableHead>Customer</TableHead>
          <TableHead>Status</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {orders.map(order => (
          <TableRow key={order.id} className="hover:bg-muted/50 transition-colors">
            <TableCell className="font-medium">{order.id}</TableCell>
            <TableCell>{order.customer}</TableCell>
            <TableCell>
              <Badge variant="default">{order.status}</Badge>
            </TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  </CardContent>
</Card>

Best Practices

• Match existing design - new designs align with current UI screens and components
• UI-first approach - complete visual interface before adding business logic
• Modular code - small, focused, reusable components (avoid monolithic pages)
• Token efficiency - concise, well-structured code
• Consistency - follow existing color, spacing, and typography patterns
• Composability - build with shadcn's philosophy of small components that work together

Common Shadcn Components

• Layout: Card, Tabs, Sheet, Dialog, Popover
• Forms: Input, Textarea, Select, Checkbox, Radio, Switch, Label
• Buttons: Button, Toggle, ToggleGroup
• Display: Badge, Avatar, Separator, Skeleton, Table
• Feedback: Alert, Toast, Progress
• Navigation: NavigationMenu, Dropdown, Command

References

• Shadcn UI
• Tailwind CSS v4
• WCAG 2.1