ui-ux-pro-max

name	ui-ux-pro-max
description	UI/UX design standards for this stack (Tailwind v4 + shadcn/ui). Use whenever creating or modifying any page, component, layout, or style — the goal is professional, consistent UI with zero AI slop.

UI/UX Pro Max

Generic AI-generated UI is recognizable and cheap-looking: purple gradient heroes, emoji bullet lists, inconsistent spacing, five shades of gray that almost match. This skill exists to prevent that. The bar is: a designer could have made this.

Component rules

• shadcn/ui first. Before writing any UI element, check src/components/ui/. Need a component that isn't there? Install it: npx shadcn@latest add <component> — never hand-roll a button, dialog, or dropdown that shadcn provides.
• Compose, don't fork. Build feature components in src/components/ out of the primitives in src/components/ui/. Don't edit the primitives except to extend variants via class-variance-authority.
• Use cn() from @/lib/utils for conditional classes — never string concatenation.

Design tokens, not raw values

• Colors: use the semantic tokens (bg-background, text-foreground, text-muted-foreground, bg-primary, border-border, bg-card...) — never raw palette classes like text-gray-500 or hex values. Tokens are what make dark mode work for free.
• Spacing: stick to the 4px scale (gap-2, gap-4, p-6, py-12...). Pick from a small set per page — three spacing values used consistently beat eight used randomly.
• Radius: use the token-driven rounded-lg/rounded-md/rounded-xl consistently; don't mix radii on sibling elements.
• Type scale: one h1 per page. Establish hierarchy with text-sm/base/lg/xl/ 3xl-5xl + font-medium/semibold/tracking-tight — not with color alone.

Anti-slop rules (hard bans)

• No decorative emoji in product UI. Icons come from lucide-react, sized size-4/size-5.
• No gradient text, no bg-gradient-to-r from-purple-500 to-pink-500 heroes.
• No placeholder copy like "Lorem ipsum" or "Your amazing app" — write real, specific copy.
• No centered-everything: use deliberate alignment; left-aligned text for reading.
• No drop shadows heavier than shadow-sm unless the element genuinely floats.
• No animation without purpose; if animating, use subtle transitions (transition-colors).

Layout & responsiveness

• Constrain content: max-w-* + mx-auto + horizontal padding (px-4 sm:px-6).
• Mobile-first: write base styles for small screens, add sm:/md:/lg: upward.
• Test both themes: every surface must look intentional in light AND dark mode.

Accessibility (non-negotiable)

• Interactive elements are <button>/<a> (or shadcn equivalents) — never clickable divs.
• Every image has meaningful alt (or alt="" if decorative).
• Every form input has a label. Focus states stay visible — never remove outlines without replacement (focus-visible:ring-*).
• Color contrast ≥ 4.5:1 for text; don't convey state by color alone.