frontend-design-guidelines

Use real label elements tied to inputs via htmlFor, specific input types with autocomplete attributes, and inline error messages with aria-invalid and aria-describedby. Validate on blur or submit rather than every keystroke, and disable the submit button while the request is in flight.

shadcn/ui is the default choice because it provides accessible Radix-based primitives, themeable CSS variables, and owned source code you install per component. Pair it with lucide-react for icons and next/font for typography.

Wrap non-essential motion in a prefers-reduced-motion: no-preference media query or use Tailwind's motion-safe variant. Animate only transform and opacity, keep durations between 100 and 400 milliseconds, and never use transition: all.

Yes. The default stack is Next.js with Tailwind and shadcn/ui, but if the repository already uses a different stack, the rules instruct matching the existing setup rather than rewriting it. The accessibility, states, and contrast rules apply regardless of framework.

Common failures include muted placeholder text on muted backgrounds, small secondary text below 4.5:1, and ghost buttons on colored surfaces. Body text needs 4.5:1 contrast and large text or icons need 3:1; darken text or lighten backgrounds until it passes.

Skip the deep polish pass for internal admin tools, throwaway prototypes, and components that already work well. Apply only the zero-cost rules like accessibility and design tokens, and reserve taste-level refinement for first-impression surfaces and high-repetition interactions.