Frontend design

Frontend Design

Expert guidance for creating beautiful, accessible, and responsive frontend designs using modern UI principles, color theory, and React+Tailwind CSS patterns.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

Color & Design:

• Choosing color palettes for applications
• Applying the 60-30-10 design rule
• Creating accessible color combinations
• Designing backgrounds, text, and accent colors
• Triggered on color selection, UI color palette design, gradient creation
• Ensuring WCAG contrast compliance

UI Components & Layouts:

• Creating React UI components with Tailwind CSS
• Building forms, modals, cards, badges, buttons, inputs, tabs, tables
• Implementing responsive design patterns
• Designing accessible UI components
• Working with states, variants, and animations

Design Review & Correction:

• Reviewing website design (local or remote)
• Checking UI for consistency issues
• Finding and fixing layout breakage
• Detecting responsive design problems
• Fixing accessibility violations
• "Review website design", "check UI", "fix layout", "find design problems"

Part 1: Color Theory & Palettes

Color Categories

• Hot Colors: Oranges, reds, and yellows - energizing, attention-grabbing
• Cool Colors: Blues, greens, and purples - calming, professional
• Neutral Colors: Grays and grayscale variations - balancing, sophisticated
• Binary Colors: Black and white - high contrast, stark

The 60-30-10 Rule

Golden Ratio for Color Balance:

Proportion	Role	Recommended Colors
60%	Primary/Dominant	Cool or light colors, neutrals
30%	Secondary	Complementary or analogous colors
10%	Accent	Complementary hot color for emphasis

Application in Code

/* Tailwind CSS CSS Variables Approach */
:root {
  /* 60% - Primary (backgrounds, large areas) */
  --color-primary-bg: #f5f7fa;
  --color-primary-text: #374151;

  /* 30% - Secondary (cards, sections) */
  --color-secondary-bg: #ffffff;
  --color-secondary-border: #e5e7eb;
  --color-secondary-text: #1f2937;

  /* 10% - Accent (buttons, highlights) */
  --color-accent-primary: #3b82f6;
  --color-accent-hover: #2563eb;
  --color-accent-text: #ffffff;
}

/* Implementing in Tailwind config */
module.exports = {
  theme: {
    extend: {
      colors: {
        // 60% - Primary
        primary: {
          bg: 'var(--color-primary-bg)',
          text: 'var(--color-primary-text)',
        },
        // 30% - Secondary
        secondary: {
          bg: 'var(--color-secondary-bg)',
          border: 'var(--color-secondary-border)',
          text: 'var(--color-secondary-text)',
        },
        // 10% - Accent
        accent: {
          primary: 'var(--color-accent-primary)',
          hover: 'var(--color-accent-hover)',
          text: 'var(--color-accent-text)',
        },
      },
    },
  },
};

Part 2: Accessibility (WCAG Compliance)

Web Content Accessibility Guidelines (WCAG 2.1 Level AA

Contrast Requirements

Element	Minimum Contrast Ratio	Recommended
Normal text (< 18pt)	4.5:1	7:1
Large text (18pt+) or bold	3:1	4.5:1
Graphical objects and UI components	3:1	Higher is better

Contrast Validation

// Calculate contrast ratio
function getContrastRatio(foreground: string, background: string): number {
  const lum1 = getLuminance(foreground);
  const lum2 = getLuminance(background);

  function getLuminance(hex: string): number {
    const rgb = hexToRgb(hex);
    const [r, g, b] = rgb.map(c => {
      c /= 255;
      return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
    });
    return 0.2126 * r[0] + 0.7152 * r[1] + 0.0722 * r[2];
  }

  const lighter = Math.max(lum1, lum2);
  const darker = Math.min(lum1, lum2);

  return (lighter + 0.05) / (darker + 0.05);
}

// Validate
const ratio = getContrastRatio('#3b82f6', '#ffffff');
console.log(ratio >= 4.5 ? '✅ WCAG AA compliant' : '❌ Not compliant');

Accessibility Best Practices

Color Independence

/* ❌ BAD - Color-only indication */
.success {
  color: green;
}
.error {
  color: red;
}

/* ✅ GOOD - Color + other visual indicator */
.success {
  color: #22c55e;
  border-left: 4px solid #22c55e;
  padding-left: 8px;
}
.error {
  color: #ef4444;
  border-left: 4px solid #ef4444;
  padding-left: 8px;
}

Focus States

/* Keyboard navigation needs visible focus */
button:focus-visible,
a:focus-visible,
input:focus-visible,
select:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

/* Tailwind */
<button className="focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">

ARIA Labels

// Icon-only buttons need labels
<button aria-label="Close dialog">
  <CloseIcon />
</button>

// Toggle buttons need pressed state
<button aria-pressed={isSelected}>
  {isSelected ? 'Selected' : 'Not selected'}
</button>

// Screen reader only text
<span className="sr-only">Required field</span>

Responsive Typography

/* Use relative units for scalability */
html {
  font-size: 100%;  /* Browser default usually 16px */
}

body {
  font-size: 1rem;      /* 16px */
  line-height: 1.5;      /* Readable line height */
}

/* Responsive scaling */
@media (min-width: 768px) {
  body {
    font-size: 1.125rem;  /* 18px on tablets+ */
  }
}

---

Part 3: Responsive Design

Mobile-First Approach

/* Base styles - mobile by default */
.container {
  width: 100%;
  padding: 1rem;
  display: block;  /* Column layout on mobile */
}

/* Tablet - 768px+ */
@media (min-width: 768px) {
  .container {
    max-width: 720px;
    display: grid;  /* Grid on tablet */
    grid-template-columns: 1fr 1fr;
  }
}

/* Desktop - 1024px+ */
@media (min-width: 1024px) {
  .container {
    max-width: 1200px;
    grid-template-columns: 1fr 1fr 1fr;
  }
}

/* Large desktop - 1280px+ */
@media (min-width: 1280px) {
  .container {
    max-width: 1400px;
  }
}

Tailwind Responsive Classes

// Mobile-first approach
<div className="
  container
  mx-auto
  px-4        /* 16px padding on all sizes */
  py-8
">
  <div className="
    grid
    grid-cols-1      /* 1 column on mobile */
    md:grid-cols-2  /* 2 columns on tablet */
    lg:grid-cols-3  /* 3 columns on desktop */
    gap-4
  ">
    {items.map(item => (
      <Card key={item.id}>{item.content}</Card>
    ))}
  </div>
</div>

Responsive Breakpoints (Tailwind Default)

Breakpoint	Width	Device
sm	640px	Small phones, portrait
md	768px	Tablets, small laptops
lg	1024px	Laptops, desktops
xl	1280px	Large desktops
2xl	1536px	Extra large displays

---

Part 4: UI Component Patterns

Button Component

const buttonVariants = {
  primary: 'bg-blue-600 hover:bg-blue-700 text-white',
  secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-900',
  danger: 'bg-red-600 hover:bg-red-700 text-white',
  ghost: 'hover:bg-gray-100 text-gray-700',
  outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50',
};

const buttonSizes = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-5 py-2.5 text-lg',
  xl: 'px-6 py-3 text-xl',
};

export function Button({
  variant = 'primary',
  size = 'md',
  disabled = false,
  isLoading = false,
  className = '',
  children,
  ...props
}) {
  return (
    <button
      disabled={disabled || isLoading}
      className={cn(
        // Base styles
        'rounded-lg font-medium transition-all',
        'focus:outline-none focus:ring-2 focus:ring-offset-2',
        'disabled:opacity-50 disabled:cursor-not-allowed',
        // Variant styles
        buttonVariants[variant],
        // Size styles
        buttonSizes[size],
        // Additional classes
        className
      )}
      aria-busy={isLoading}
      {...props}
    >
      {isLoading ? (
        <LoadingSpinner size="sm" className="mr-2" />
      ) : null}
      {children}
    </button>
  );
}

Card Component

export function Card({
  children,
  variant = 'default',
  hoverable = false,
  className = '',
  ...props
}) {
  const variants = {
    default: 'bg-white border border-gray-200',
    elevated: 'bg-white shadow-lg border border-gray-100',
    outlined: 'bg-transparent border-2 border-gray-300',
    // Interactive variants
    hover: 'hover:shadow-xl transition-shadow duration-200',
  };

  return (
    <div
      className={cn(
        'rounded-lg overflow-hidden',
        variants.default,
        variants[variant],
        hoverable && variants.hover,
        className
      )}
      {...props}
    >
      {children}
    </div>
  );
}

// Usage examples
<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p>Card content goes here.</p>
  </CardContent>
</Card>

Modal Component

export function Modal({
  isOpen,
  onClose,
  title,
  children,
  size = 'md',
}) {
  // Prevent body scroll when modal is open
  useEffect(() => {
    if (isOpen) {
      document.body.style.overflow = 'hidden';
    } else {
      document.body.style.overflow = 'unset';
    }

    return () => {
      document.body.style.overflow = 'unset';
    };
  }, [isOpen]);

  // Close on escape key
  useEffect(() => {
    const handleEscape = (e) => {
      if (e.key === 'Escape' && isOpen) {
        onClose();
      }
    };

    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  const sizes = {
    sm: 'max-w-md',
    md: 'max-w-2xl',
    lg: 'max-w-4xl',
    xl: 'max-w-6xl',
  };

  return createPortal(
    <div
      className="fixed inset-0 z-50"
      role="dialog"
      aria-modal="true"
      aria-labelledby={title}
    >
      <!-- Backdrop -->
      <div
        className="absolute inset-0 bg-black/50 backdrop-blur-sm"
        onClick={onClose}
      />

      <!-- Modal Container -->
      <div
        className="
          relative
          bg-white
          rounded-lg
          shadow-2xl
          mx-4
          my-8
          max-h-[calc(100vh-4rem)]
          overflow-y-auto
          {sizes[size]}
        "
      >
        <div className="flex items-center justify-between p-6 border-b">
          <h2 id="modal-title" className="text-2xl font-bold">
            {title}
          </h2>
          <button
            onClick={onClose}
            className="p-2 hover:bg-gray-100 rounded-full"
            aria-label="Close modal"
          >
            <CloseIcon />
          </button>
        </div>
        <div className="p-6">
          {children}
        </div>
      </div>
    </div>,
    document.body
  );
}

Form Component

export function FormField({
  label,
  error,
  hint,
  required = false,
  children,
}) {
  return (
    <div className="mb-4">
      <label className="block text-sm font-medium text-gray-700 mb-1">
        {label}
        {required && <span className="text-red-500 ml-1">*</span>}
      </label>
      {children}
      {hint && (
        <p className="mt-1 text-sm text-gray-500">{hint}</p>
      )}
      {error && (
        <p className="mt-1 text-sm text-red-600 flex items-center">
          <ExclamationIcon className="w-4 h-4 mr-1" />
          {error}
        </p>
      )}
    </div>
  );
}

// Usage
<FormField
  label="Email Address"
  error={errors.email}
  hint="We'll never share your email."
  required
>
  <input
    type="email"
    className="w-full px-3 py-2 border rounded-lg"
    {...register('email')}
  />
</FormField>

---

Component Review Rubric

Use this shared rubric for React, Next.js, Vite, and premium UI work.

1. Contract: props, state, events, errors, and data ownership are explicit.
2. States: loading, empty, error, success, disabled, and responsive states are represented.
3. Accessibility: semantics, keyboard path, focus order, contrast, and reduced-motion behavior pass inspection.
4. Craft: spacing, hierarchy, typography, motion, and visual density feel intentional rather than default.
5. Performance: rendering, bundle impact, image strategy, and hydration boundaries match the framework.

Anti-Patterns

• Starting from a generic template without adapting it: The output may look polished but still miss the real audience or medium.
• Ignoring final render or export review: Layout bugs often appear only after the asset is opened in its destination tool.
• Fixing content and presentation in one pass: It becomes hard to tell whether a problem is structural or visual.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Frontend Design guidance is tied to a concrete route, component, screen, or design artifact.
2. Pass/fail: Component states cover loading, empty, error, success, and responsive breakpoints where applicable.
3. Pass/fail: Accessibility, visual hierarchy, and interaction behavior are reviewed against the shared component rubric.
4. Pressure-test scenario: Review the component on a narrow mobile viewport, keyboard-only path, and slow-loading state.
5. Success metric: Zero generic UI approval; every approval cites rendered behavior or source evidence.

Part 5: Design Review Checklist

Visual Inspection Process

## Design Review Workflow

### Step 1: Information Gathering
- [ ] Understand target audience and use cases
- [ ] Identify design constraints (brand, accessibility)
- [ ] Review existing design system/component library
- [ ] Gather user feedback or pain points

### Step 2: Visual Inspection
- [ ] Capture screenshots of current implementation
- [ ] Review layout at multiple viewport sizes
- [ ] Test color contrast with accessibility tools
- [ ] Check spacing and alignment
- [ ] Verify hierarchy and readability

### Step 3: Issue Identification
- [ ] Document发现的问题s with severity ratings
- [ ] Group related issues together
- [ ] Prioritize by impact on UX

### Step 4: Issue Fixing
- [ ] Fix issues at source code level
- [ ] Test fixes across browsers and devices
- [ ] Verify accessibility improvements
- [ ] Get user/stakeholder validation

### Step 5: Re-verification
- [ ] Compare before/after results
- [ ] Ensure no regressions introduced
- [ ] Document changes made

Common Design Issues

Layout & Spacing Issues

/* Issue: Inconsistent spacing */
.bad {
  padding: 10px;    /* Magic number */
  margin: 5px;      /* Different from padding */
}

/* Fix: Consistent spacing scale */
.good {
  padding: 1rem;     /* 16px - using scale */
  gap: 0.5rem;      /* 8px - consistent with scale */
}

Color Contrast Issues

// Issue: Poor contrast
<button className="bg-blue-300 text-blue-100">
  Can't read this
</button>

// Fix: WCAG compliant
<button className="bg-blue-600 text-white">
  Readable
</button>

Typography Issues

/* Issue: Line height too tight */
.bad {
  line-height: 1;  /* Can be hard to read */
}

/* Fix: Comfortable reading */
.good {
  line-height: 1.6;  /* Recommended for body text */
}

Responsive Testing Checklist

## Responsive Testing

### Viewport Testing
- [ ] Mobile: 375px (iPhone SE)
- [ ] Mobile: 414px (iPhone Max)
- [ ] Tablet: 768px (iPad)
- [ ] Desktop: 1024px (Small laptop)
- [ ] Desktop: 1440px (Large desktop)
- [ ] Desktop: 1920px (Fullscreen)

### Design Elements to Check
- [ ] Navigation menu accessible on all sizes
- [ ] Text readable at all breakpoints
- [ ] Images scale correctly
- [ ] Forms usable without horizontal scroll
- [ ] Touch targets ≥ 44x44px on mobile
- [ ] No horizontal scrollbar

### Content Flow
- [ ] Content stacks vertically on mobile
- [ ] Content uses grid/multi-column on larger screens
- [ ] Important content above the fold on all sizes
- [ ] No content cut off or hidden

---

Part 6: Design System Integration

Design Tokens

// tokens.js - Centralized design tokens
export const tokens = {
  colors: {
    brand: {
      primary: '#3b82f6',
      secondary: '#6366f1',
      accent: '#f97316',
    },
    neutral: {
      50: '#f8fafc',
      100: '#f1f5f9',
      200: '#e2e8f0',
      300: '#cbd5e1',
      400: '#94a3b8',
      500: '#64748b',
      600: '#475569',
      700: '#334155',
      800: '#1e293b',
      900: '#0f172a',
      950: '#020617',
    },
  },
  spacing: {
    0: '0',
    1: '0.25rem',    /* 4px */
    2: '0.5rem',     /* 8px */
    3: '0.75rem',    /* 12px */
    4: '1rem',       /* 16px */
    5: '1.25rem',    /* 20px */
    6: '1.5rem',     /* 24px */
    8: '2rem',       /* 32px */
    10: '2.5rem',    /* 40px */
    12: '3rem',      /* 48px */
  },
  typography: {
    fontSizes: {
      xs: '0.75rem',   /* 12px */
      sm: '0.875rem',  /* 14px */
      base: '1rem',     /* 16px */
      lg: '1.125rem',  /* 18px */
      xl: '1.25rem',   /* 20px */
      '2xl': '1.5rem',  /* 24px */
      '3xl': '1.875rem', /* 30px */
      '4xl': '2.25rem',  /* 36px */
    },
    fontWeights: {
      normal: '400',
      medium: '500',
      semibold: '600',
      bold: '700',
    },
    lineHeights: {
      tight: '1.25',
      normal: '1.5',
      relaxed: '1.75',
    },
  },
  borderRadius: {
    none: '0',
    sm: '0.25rem',    /* 4px */
    DEFAULT: '0.375rem',  /* 6px */
    md: '0.5rem',     /* 8px */
    lg: '0.75rem',    /* 12px */
    xl: '1rem',       /* 16px */
    full: '9999px',
  },
  shadows: {
    sm: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
    DEFAULT: '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)',
    md: '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)',
    lg: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
  },
};

// Tailwind configuration with tokens
module.exports = {
  theme: {
    extend: {
      colors: tokens.colors,
      spacing: tokens.spacing,
      fontSize: tokens.typography.fontSizes,
      fontWeight: tokens.typography.fontWeights,
      lineHeight: tokens.typography.lineHeights,
      borderRadius: tokens.borderRadius,
      boxShadow: tokens.shadows,
    },
  },
};

---

Frontend Design Best Practices

Color & Visual Design

• Follow 60-30-10 rule for color balance
• Maintain contrast ratio ≥ 4.5:1 for normal text
• Use color for decoration, not sole indicator of meaning
• Document color palette and usage guidelines
• Test colorblind accessibility

Typography

• Use max-width for optimal reading length (~65-75 characters)
• Maintain consistent line height (1.5-1.75 for body text)
• Use relative font sizes (rem, em) for scalability
• Establish type scale and use consistently
• Ensure heading hierarchy is clear

Layout & Spacing

• Use consistent spacing scale (4px or 6px base)
• Ensure adequate white space for breathing room
• Align elements to grid for visual harmony
• Test responsive behavior at all breakpoints
• Maintain touch targets ≥ 44x44px on mobile

Accessibility

• Keyboard navigation works without mouse
• Focus states are clearly visible
• ARIA labels on icon-only buttons
• Form fields have associated labels
• Images have alt text (except decorative)
• Screen reader only text for visual-only info
• Skip navigation for reaching main content

Performance

• Optimize images (WebP, AVIF when supported)
• Use responsive images with srcset
• Implement code splitting for large bundles
• Lazy load offscreen images and components
• Minimize layout shifts (CLS) and paint issues (LCP)

---

References & Resources

Documentation

• Tailwind Component Patterns — Cards, forms, navigation, modals, tables, and skeleton loading patterns
• Accessibility Checklist — WCAG 2.2 checklist with React/HTML/ARIA code examples

Scripts

• Contrast Checker — Python WCAG contrast ratio checker with batch mode for CSS files

Examples

• Responsive Recipe Card — Complete React+Tailwind recipe card with responsive variants and states

---

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:frontend-design from this skill. Rebuild commands with python scripts/export-gemini-skill.py frontend-design and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END --> <!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Frontend Design skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

<!-- MCP:END -->

Related Skills

• premium-frontend-ui: Use it when the workflow also needs high-fidelity UI polish and interaction detail.
• web-design-reviewer: Use it when the workflow also needs browser-based UI review and responsive QA.
• stitch-design: Use it when the workflow also needs turning interface designs into implementation-ready assets.
• canvas-design: Use it when the workflow also needs visual composition and presentation-ready diagram work.