Frontend Design Standards

Overview

AI-generated UI suffers from systematic failures: generic aesthetics, accessibility violations, div soup, small text, missing states, and brand blindness. This skill enforces production-quality standards that prevent the "AI look."

Core principle: Every component must pass accessibility, theming, responsiveness, and semantic HTML checks BEFORE considering the task complete.

Mandatory Checklist

Run through EVERY category for EVERY component. No exceptions.

1. Theme Compliance (Zero Hardcoded Colors)

FORBIDDEN - Tailwind color classes:

// WRONG - hardcoded colors
className="bg-gray-50 text-gray-900 border-gray-200"
className="bg-blue-600 text-white hover:bg-blue-700"
className="text-green-500 bg-red-100"

REQUIRED - Theme variables:

// CORRECT - uses theme system
className="bg-background text-foreground border-border"
className="bg-primary text-primary-foreground hover:bg-primary/90"
className="text-success bg-destructive/10"

FORBIDDEN - Hardcoded Hex Values:

// WRONG - magic numbers/colors
className="bg-[#F3F4F6] text-[#111827]"
style={{ backgroundColor: '#ff0000' }}

Verification:

# Find violations - any match is a failure
grep -rn "bg-gray\|bg-blue\|bg-green\|bg-red\|text-gray\|text-blue" --include="*.tsx"
grep -rn "#[0-9a-fA-F]\{3,6\}" --include="*.tsx"  # Catch hex codes

If a semantic color doesn't exist, ADD IT to the theme system - don't use raw Tailwind colors or Hex values.

2. Typography Standards (16px Minimum Body Text)

FORBIDDEN:

// WRONG - below 16px minimum for readable content
className="text-sm"  // 14px - TOO SMALL for body
className="text-xs"  // 12px - TOO SMALL for any readable content

ALLOWED uses of small text:

• Timestamps, metadata, captions:

  text-sm

  acceptable
• Legal disclaimers:

  text-xs

  acceptable
• Labels for inputs:

  text-sm

  acceptable

Body text, paragraphs, descriptions MUST be:

className="text-base"  // 16px - minimum
className="text-lg"    // 18px - preferred for long-form

Line height requirement:

// REQUIRED - 1.5 minimum for paragraphs
className="leading-relaxed"  // 1.625
className="leading-normal"   // 1.5

3. Semantic HTML (No Div Soup)

FORBIDDEN - Generic divs for semantic content:

// WRONG
<div className="navigation">
  <div onClick={handleClick}>Home</div>
</div>

REQUIRED - Proper semantic elements:

<nav aria-label="Main">

<main>

<article>

<section aria-labelledby="id">

<aside>

<footer>

<button type="button">

<button type="submit">

<a href="">

<Link>

<ul>/<ol>

<li>

<h1>

<h6>

Heading hierarchy rule: Never skip levels. After

<h2>

<h3>

<h4>

4. Accessibility Requirements

Skip link for keyboard users (on page layouts):

// REQUIRED at top of page layouts
<a
  href="#main-content"
  className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-background focus:text-foreground focus:ring-2 focus:ring-ring"
>
  Skip to main content
</a>
// ... later
<main id="main-content">

Every interactive element MUST have:

// Buttons with icons only
<button
  aria-label="Close dialog"  // REQUIRED for icon-only buttons
  type="button"
>
  <X className="h-5 w-5" />
</button>

// Toggle buttons
<button
  aria-expanded={isOpen}  // REQUIRED for expandable controls
  aria-controls="menu-id"  // REQUIRED - ID of controlled element
>

// Form inputs
<label htmlFor="email">Email</label>  // REQUIRED - visible label
<input
  id="email"
  aria-describedby="email-error"  // REQUIRED when error present
  aria-invalid={hasError}  // REQUIRED when validation fails
/>
<p id="email-error" role="alert">{error}</p>  // Announced to screen readers

Focus management:

// REQUIRED - visible focus indicator
className="focus:ring-2 focus:ring-ring focus:ring-offset-2"
className="focus-visible:outline-none focus-visible:ring-2"

Color contrast: Verify all text meets WCAG AA (4.5:1 for normal text, 3:1 for large text).

Images require alt text:

// Informative image
<img src="chart.png" alt="Sales increased 40% in Q3" />

// Decorative image (empty alt, not missing)
<img src="decorative-swoosh.svg" alt="" role="presentation" />

// WRONG - missing alt
<img src="product.jpg" />  // Screen readers say "image" with no context

5. Component States (No Happy Path Only)

Every component that loads data or accepts input MUST handle:

aria-busy="true"

role="alert"

role="status"

FORBIDDEN - Silent failures:

// WRONG - just logs to console
} catch (error) {
  console.error(error);
}

REQUIRED - User-visible feedback:

} catch (error) {
  setError("Failed to load. Please try again.");
}

// In render:
{error && (
  <div role="alert" className="text-destructive">
    {error}
    <button onClick={retry}>Retry</button>
  </div>
)}

6. Responsive Design Requirements

Touch target minimum:

// REQUIRED - 44px minimum for touch targets
className="min-h-[44px] min-w-[44px]"
// Or use padding to achieve:
className="p-3"  // 12px padding + content = ~44px

Mobile-first breakpoints:

// CORRECT - mobile first, add complexity upward
className="flex flex-col md:flex-row"
className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3"

// WRONG - desktop first with mobile overrides
className="flex flex-row sm:flex-col"  // Backwards

Required responsive considerations:

• Does navigation collapse to hamburger menu?
• Do touch targets meet 44px minimum?
• Does text remain readable without horizontal scroll?
• Do images have responsive sizing?

7. Brand Differentiation (Anti-Generic)

Before generating UI, ASK or DETERMINE:

1. Color personality: What emotions should colors evoke?
2. Typography character: Playful, professional, technical, luxurious?
3. Shape language: Sharp/angular or soft/rounded?
4. Density: Spacious/breathing or compact/efficient?
5. Motion: Bouncy/playful or subtle/refined?

If brand requirements are vague, DO NOT default to:

• Gray backgrounds with blue accents
• Inter/system font with slate text
• Standard 3-column feature grids
• Purple gradients

Instead, ask: "What makes this brand/product unique? What should users FEEL?"

8. Motion and Micro-interactions (Anti-Dead Interface)

AI-generated UIs often feel "static" or "dead." Consider:

// Add meaningful transitions
className="transition-colors duration-200"
className="transition-transform hover:scale-105"

// Loading feedback
className="animate-pulse"  // skeleton loading
className="animate-spin"   // spinner

Motion principles:

• Hover states on all interactive elements
• Transitions between states (not instant jumps)
• Loading indicators for async operations
• Success/error feedback animations

Don't overdo it: Subtle > flashy. Respect

prefers-reduced-motion

9. Code Validity (No Hallucinations)

AI sometimes generates non-existent CSS properties or imports libraries/components that aren't installed.

FORBIDDEN - Hallucinated/obsolete CSS:

/* These don't exist */
width: fit-parent;
text-fill-color: transparent;

/* Obsolete vendor prefixes for modern properties */
-webkit-border-radius: 8px;  /* Just use border-radius */

FORBIDDEN - Hallucinated Imports:

// WRONG - Do not import things that don't exist
import { Sparkles } from '@heroicons/react/solid'; // Check if 'solid' exists in your version
import { useMagicHook } from 'react-use'; // Check if 'react-use' is installed

Rule:

1. Check

   package.json

   before importing a 3rd party library.
2. Check file structure before importing local components (don't assume

   @/components/ui/card

   exists).
3. Check MDN if unsure about a CSS property.

10. Project Structure (Anti-Monolith)

AI tends to dump everything into a single file. This is unmaintainable.

FORBIDDEN - The "God Component":

• Single file > 250 lines (unless it's a complex data table).
• Defining multiple complex sub-components in the same file.
• Mixing heavy business logic (

  useEffect

  , data fetching) with UI rendering.

REQUIRED - Separation of Concerns:

1. Extract Types: Move interfaces to

   types.ts

   if shared, or top of file.
2. Extract Hooks: Move complex logic to

   useFeatureName.ts

   .
3. Extract Components: If a sub-component renders > 20 lines of JSX, move it to its own file.
4. Colocation: Keep related files together (e.g.,

   components/Feature/Feature.tsx

   ,

   components/Feature/useFeature.ts

   ).

Verification Checklist

Before marking any UI work complete, verify:

• Zero hardcoded Tailwind colors OR Hex codes (grep check passes)
• Body text uses

  text-base

  (16px) or larger
• Semantic HTML elements for all landmarks
• All interactive elements have accessible names
• Focus indicators visible on all interactive elements
• Loading, error, and empty states implemented
• Touch targets meet 44px minimum
• Mobile layout tested (or responsive classes verified)
• Brand differentiation considered (not generic gray/blue)
• Skip link present on page layouts

• aria-expanded

  on all toggle buttons
• All images have alt text (empty for decorative)
• Hover/transition states on interactive elements
• No hallucinated CSS properties or Imports (verify existence)
• No "God Components" (>250 lines) - extracted sub-components

Common Rationalizations

bg-muted

Red Flags - Stop and Reconsider

If you catch yourself doing ANY of these, STOP:

• Using

  bg-gray-*

  ,

  text-gray-*

  , or Hex codes (

  #F3F4F6

  )
• Importing libraries without checking

  package.json

• Creating "God Components" (>250 lines) without splitting
• Body text smaller than 16px (

  text-sm

  for paragraphs)
• Interactive elements without accessible names
• No loading or error state handling
• All buttons/cards look identical
• Can't explain what makes this design unique
• No semantic landmarks (

  <nav>

  ,

  <main>

  ,

  <article>

  )
• Skip link not implemented for keyboard users
• Assuming brand requirements instead of asking
• Using

  console.error()

  without user-visible feedback
• Missing

  aria-expanded

  on toggle buttons
• Using

  onClick

  on divs instead of buttons
• Images without alt attributes
• Using CSS properties you haven't verified exist
• No hover states or transitions on buttons/links

Quick Reference

Semantic Color Mapping

bg-background

bg-white

bg-gray-50

bg-card

bg-white

bg-gray-100

bg-primary

bg-blue-600

bg-indigo-500

bg-destructive

bg-red-500

bg-red-600

bg-muted

bg-gray-100

bg-slate-100

border-border

border-gray-200

text-foreground

text-gray-900

text-black

text-muted-foreground

text-gray-500

text-gray-600

Text Size Guide

text-4xl

text-6xl

leading-tight

text-2xl

text-3xl

leading-snug

text-lg

text-xl

leading-normal

text-base

leading-relaxed

text-sm

leading-normal

Essential ARIA Patterns

// Expandable content
<button aria-expanded={open} aria-controls="content-id">
<div id="content-id" hidden={!open}>

// Form error
<input aria-invalid={!!error} aria-describedby="error-id" />
<p id="error-id" role="alert">{error}</p>

// Loading content
<div aria-busy={loading} aria-live="polite">

// Dynamic announcements
<div role="status" aria-live="polite">{message}</div>