ui-styling

• shadcn/ui: https://ui.shadcn.com/llms.txt
• Tailwind CSS: https://tailwindcss.com/docs

Use when:

• Building UI with React-based frameworks (Next.js, Vite, Remix, Astro)
• Implementing accessible components (dialogs, forms, tables, navigation)
• Styling with utility-first CSS approach
• Creating responsive, mobile-first layouts
• Implementing dark mode and theme customization
• Building design systems with consistent tokens
• Generating visual designs, posters, or brand materials
• Rapid prototyping with immediate visual feedback
• Adding complex UI patterns (data tables, charts, command palettes)

Component Layer: shadcn/ui

• Pre-built accessible components via Radix UI primitives
• Copy-paste distribution model (components live in your codebase)
• TypeScript-first with full type safety
• Composable primitives for complex UIs
• CLI-based installation and management

Styling Layer: Tailwind CSS

• Utility-first CSS framework
• Build-time processing with zero runtime overhead
• Mobile-first responsive design
• Consistent design tokens (colors, spacing, typography)
• Automatic dead code elimination

Visual Design Layer: Canvas

• Museum-quality visual compositions
• Philosophy-driven design approach
• Sophisticated visual communication
• Minimal text, maximum visual impact
• Systematic patterns and refined aesthetics

Component + Styling Setup

Install shadcn/ui with Tailwind:

```bash

npx shadcn@latest init

```

CLI prompts for framework, TypeScript, paths, and theme preferences. This configures both shadcn/ui and Tailwind CSS.

Add components:

```bash

npx shadcn@latest add button card dialog form

```

Use components with utility styling:

```tsx

import { Button } from "@/components/ui/button"

import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"

export function Dashboard() {

return (

)

}

```

Alternative: Tailwind-Only Setup

Vite projects:

```bash

npm install -D tailwindcss @tailwindcss/vite

```

```javascript

// vite.config.ts

import tailwindcss from '@tailwindcss/vite'

export default { plugins: [tailwindcss()] }

```

```css

/ src/index.css /

@import "tailwindcss";

```

Comprehensive component catalog with usage patterns, installation, and composition examples.

See: references/shadcn-components.md

Covers:

• Form & input components (Button, Input, Select, Checkbox, Date Picker, Form validation)
• Layout & navigation (Card, Tabs, Accordion, Navigation Menu)
• Overlays & dialogs (Dialog, Drawer, Popover, Toast, Command)
• Feedback & status (Alert, Progress, Skeleton)
• Display components (Table, Data Table, Avatar, Badge)

Theme configuration, CSS variables, dark mode implementation, and component customization.

See: references/shadcn-theming.md

Covers:

• Dark mode setup with next-themes
• CSS variable system
• Color customization and palettes
• Component variant customization
• Theme toggle implementation

ARIA patterns, keyboard navigation, screen reader support, and accessible component usage.

See: references/shadcn-accessibility.md

Covers:

• Radix UI accessibility features
• Keyboard navigation patterns
• Focus management
• Screen reader announcements
• Form validation accessibility

Core utility classes for layout, spacing, typography, colors, borders, and shadows.

See: references/tailwind-utilities.md

Covers:

• Layout utilities (Flexbox, Grid, positioning)
• Spacing system (padding, margin, gap)
• Typography (font sizes, weights, alignment, line height)
• Colors and backgrounds
• Borders and shadows
• Arbitrary values for custom styling

Mobile-first breakpoints, responsive utilities, and adaptive layouts.

See: references/tailwind-responsive.md

Covers:

• Mobile-first approach
• Breakpoint system (sm, md, lg, xl, 2xl)
• Responsive utility patterns
• Container queries
• Max-width queries
• Custom breakpoints

Config file structure, custom utilities, plugins, and theme extensions.

See: references/tailwind-customization.md

Covers:

• @theme directive for custom tokens
• Custom colors and fonts
• Spacing and breakpoint extensions
• Custom utility creation
• Custom variants
• Layer organization (@layer base, components, utilities)
• Apply directive for component extraction

Canvas-based design philosophy, visual communication principles, and sophisticated compositions.

See: references/canvas-design-system.md

Covers:

• Design philosophy approach
• Visual communication over text
• Systematic patterns and composition
• Color, form, and spatial design
• Minimal text integration
• Museum-quality execution
• Multi-page design systems

Python automation for component installation and configuration generation.

shadcn_add.py

Add shadcn/ui components with dependency handling:

```bash

python scripts/shadcn_add.py button card dialog

```

tailwind_config_gen.py

Generate tailwind.config.js with custom theme:

```bash

python scripts/tailwind_config_gen.py --colors brand:blue --fonts display:Inter

```

1. Component Composition: Build complex UIs from simple, composable primitives
2. Utility-First Styling: Use Tailwind classes directly; extract components only for true repetition
3. Mobile-First Responsive: Start with mobile styles, layer responsive variants
4. Accessibility-First: Leverage Radix UI primitives, add focus states, use semantic HTML
5. Design Tokens: Use consistent spacing scale, color palettes, typography system
6. Dark Mode Consistency: Apply dark variants to all themed elements
7. Performance: Leverage automatic CSS purging, avoid dynamic class names
8. TypeScript: Use full type safety for better DX
9. Visual Hierarchy: Let composition guide attention, use spacing and color intentionally
10. Expert Craftsmanship: Every detail matters - treat UI as a craft

Component Library

• references/shadcn-components.md - Complete component catalog
• references/shadcn-theming.md - Theming and customization
• references/shadcn-accessibility.md - Accessibility patterns

Styling System

• references/tailwind-utilities.md - Core utility classes
• references/tailwind-responsive.md - Responsive design
• references/tailwind-customization.md - Configuration and extensions

Visual Design

• references/canvas-design-system.md - Design philosophy and canvas workflows

Automation

• scripts/shadcn_add.py - Component installation
• scripts/tailwind_config_gen.py - Config generation

Form with validation:

```tsx

import { useForm } from "react-hook-form"

import { zodResolver } from "@hookform/resolvers/zod"

import * as z from "zod"

import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form"

import { Input } from "@/components/ui/input"

import { Button } from "@/components/ui/button"

const schema = z.object({

email: z.string().email(),

password: z.string().min(8)

})

export function LoginForm() {

const form = useForm({

resolver: zodResolver(schema),

defaultValues: { email: "", password: "" }

})

return (

)

}

```

Responsive layout with dark mode:

```tsx

```

• shadcn/ui Docs: https://ui.shadcn.com
• Tailwind CSS Docs: https://tailwindcss.com
• Radix UI: https://radix-ui.com
• Tailwind UI: https://tailwindui.com
• Headless UI: https://headlessui.com
• v0 (AI UI Generator): https://v0.dev