styling-ui

name	styling-ui
description	Enforces design system using Tailwind CSS v4 and shadcn/ui. Use for: all styling, theming, responsive design, animations. DO NOT use for: component logic (use developing-nextjs), data fetching (use managing-convex).

Styling UI

Tailwind CSS v4 + shadcn/ui design system. Semantic tokens are mandatory.

Source of Truth

• Globals + Tokens: app/globals.css
• UI Primitives: components/ui/ (shadcn/ui)
• Class Merger: import { cn } from "@/lib/utils"

Mandatory Standards

Requirement	Correct	Incorrect
Class merging	cn("base", className)	className={...} only
Colors	bg-background, text-foreground	bg-white, text-black
Spacing	gap-4, p-6	gap-[18px], padding: 20px
Fonts	font-sans, font-brand, font-mono	font-family: Arial
Responsive	md:flex, lg:grid-cols-3	Fixed widths

Font System

Token	Font	Usage
font-sans	Geist	Default body/UI text
font-brand	Bricolage Grotesque	Headings, brand moments
font-mono	Geist Mono	Code, numbers, IDs

Color Tokens (oklch-based)

Use semantic tokens exclusively:

/* From app/globals.css */
--background       /* Page background */
--foreground       /* Primary text */
--card             /* Card surfaces */
--muted            /* Secondary backgrounds */
--muted-foreground /* Secondary text */
--primary          /* Brand color (orange ember) */
--accent           /* Hover highlights */
--destructive      /* Error states */
--border           /* Borders */

Animation Utilities

Class	Effect	Duration
animate-fade-in	Fade + slide up	0.6s
animate-scale-in	Pop in	0.3s
animate-shimmer	Loading shimmer	2s loop
animate-float	Levitation	6s loop
animate-pulse-glow	Attention glow	3s loop
animate-lightbulb-glow	Subtle glow	1.5s loop
animate-loading-bar	Progress bar	1.5s loop

Custom Utilities

Class	Purpose
glass-effect	Frosted glass panels (blur + transparency)
glass-effect-home	Dark glass for landing page
container	Centered content with responsive padding

Workflow: Style Component

- [ ] 1. Import `cn` from `@/lib/utils`
- [ ] 2. Use semantic HTML (`<main>`, `<section>`, `<article>`)
- [ ] 3. Apply `font-sans` (default) or `font-brand` for headings
- [ ] 4. Use tokens: `bg-card`, `text-foreground`, `border-border`
- [ ] 5. Layout with `flex`/`grid` and `gap-*`
- [ ] 6. Add responsive: mobile-first, then `md:`, `lg:` overrides
- [ ] 7. Add interactivity: `hover:bg-muted/50 transition-colors cursor-pointer`
- [ ] 8. Polish: animations, `glass-effect` where appropriate

Common Patterns

Card Component

<div className={cn(
  "rounded-lg border bg-card p-6 shadow-sm",
  "hover:shadow-md transition-shadow",
  className
)}>
  {children}
</div>

Interactive Button

<button className={cn(
  "px-4 py-2 rounded-md font-medium",
  "bg-primary text-primary-foreground",
  "hover:bg-primary/90 transition-colors",
  "focus-visible:ring-2 focus-visible:ring-ring"
)}>
  Click Me
</button>

Responsive Grid

<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
  {items.map(item => <Card key={item.id} />)}
</div>

Glass Panel

<div className="glass-effect rounded-xl p-6">
  {/* Content with frosted glass background */}
</div>

Breakpoints

Token	Width	Target
xs	480px	Mobile landscape
sm	640px	Large mobile
md	768px	Tablet
lg	1024px	Laptop
xl	1280px	Desktop
2xl	1536px	Large desktop
3xl	2000px	1440p monitors
4xl	2400px	2K monitors
5xl	3600px	4K monitors

Guardrails

• Never use hardcoded colors (#fff, rgb(...), bg-gray-100)
• Never use inline styles (style={{ padding: 20 }})
• Never create custom CSS files — use globals.css utilities only
• Always use cn() for className props to enable overrides
• Always test mobile-first, then add md: / lg: variants

Output Format

## Summary
Styled [component] with [pattern].

## Tokens Used
- Colors: `bg-card`, `text-foreground`
- Spacing: `p-4`, `gap-2`
- Animation: `animate-fade-in`

## Responsive
- Mobile: single column
- `md:`: 2 columns
- `lg:`: 3 columns

## Verification
- Dark mode tested ✅
- Mobile tested ✅