Web Design Reviewer

Web Design Reviewer

Use this skill for visual QA and source-level fixes after a page is already running. This is not the right skill for functional automation or regression suites.

• 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.

• Reviewing a live page for layout or spacing defects
• Checking responsive behavior at a few critical widths
• Comparing a page to a design system or visual target
• Tracing a visible issue back to CSS, Tailwind classes, or component structure

Recommended Workflow

1. Open the page with a browser-capable MCP client such as Playwright MCP. 2. Capture the current state before editing. 3. Test desktop and mobile widths. 4. Fix the source code, then re-check the same viewports.

Playwright MCP Mapping

These tool names are current in the Playwright MCP server used by Codex:

• browser_navigate to open the page
• browser_snapshot to inspect accessible structure
• browser_take_screenshot for before and after captures
• browser_resize for responsive review
• browser_console_messages and browser_network_requests to catch front-end breakage

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 Web Design Reviewer 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.

Review Checklist

• [ ] No overflow or clipped content at target widths
• [ ] Interactive controls remain visible and reachable
• [ ] Text contrast and focus states are acceptable
• [ ] Repeated components use consistent spacing, typography, and color
• [ ] Fixes were verified visually after the code change

References & Resources

Documentation

• Visual Checklist - High-signal items for layout, contrast, spacing, and responsive review
• Framework Fixes - Typical fix locations for CSS, Tailwind, CSS modules, and component styles

Scripts

• CSS Risk Audit - Scan CSS and front-end source for risky fixed widths, viewport traps, and overflow patterns

<!-- 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:web-design-reviewer from this skill. Rebuild commands with python scripts/export-gemini-skill.py web-design-reviewer and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: Playwright MCP

• Fallback prompt: "Use the Web Design Reviewer 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."
• Use Playwright CLI, browser devtools, screenshots, and manual responsive checks when MCP browser tools are unavailable.
• Capture console or network issues with the browser or terminal before proposing visual fixes.

<!-- MCP:END -->

Related Skills

• frontend-design: Use it when the workflow also needs UI composition and front-end design direction.
• premium-frontend-ui: Use it when the workflow also needs high-fidelity UI polish and interaction detail.
• 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.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

All notable changes to this skill will be documented in this file.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Documented the preferred MCP server surface for this skill and a local no-MCP fallback workflow.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

• Rewrote the skill around the current Playwright MCP tool names used for visual review

Added

• scripts/css-risk-audit.py for lightweight CSS and front-end risk scanning before or after visual review

[2026-03-01] — Activation Fix

Fixed

• Added "Not for automated E2E testing" disambiguation to prevent overlap with web-testing on screenshot prompts
• Clarified visual inspection language: added "visually", "diagnosing", "UI layout/design"

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

Framework-specific Fix Guide

This document explains specific fix techniques for each framework and styling method.

---

Pure CSS / SCSS

Fixing Layout Overflow

/* Before: Overflow occurs */
.container {
  width: 100%;
}

/* After: Control overflow */
.container {
  width: 100%;
  max-width: 100%;
  overflow-x: hidden;
}

Text Clipping Prevention

/* Single line truncation */
.text-truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Multi-line truncation */
.text-clamp {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

/* Word wrapping */
.text-wrap {
  word-wrap: break-word;
  overflow-wrap: break-word;
  hyphens: auto;
}

Spacing Unification

/* Unify spacing with CSS custom properties */
:root {
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
}

.card {
  padding: var(--spacing-md);
  margin-bottom: var(--spacing-lg);
}

Improving Contrast

/* Before: Insufficient contrast */
.text {
  color: #999999;
  background-color: #ffffff;
}

/* After: Meets WCAG AA standards */
.text {
  color: #595959; /* Contrast ratio 7:1 */
  background-color: #ffffff;
}

---

Tailwind CSS

Layout Fixes

{/* Before: Overflow */}
<div className="w-full">
  <img src="..." />
</div>

{/* After: Overflow control */}
<div className="w-full max-w-full overflow-hidden">
  <img src="..." className="w-full h-auto object-contain" />
</div>

Text Clipping Prevention

{/* Single line truncation */}
<p className="truncate">Long text...</p>

{/* Multi-line truncation */}
<p className="line-clamp-3">Long text...</p>

{/* Allow wrapping */}
<p className="break-words">Long text...</p>

Responsive Support

{/* Mobile-first responsive */}
<div className="
  flex flex-col gap-4
  md:flex-row md:gap-6
  lg:gap-8
">
  <div className="w-full md:w-1/2 lg:w-1/3">
    Content
  </div>
</div>

Spacing Unification (Tailwind Config)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      spacing: {
        '18': '4.5rem',
        '22': '5.5rem',
      },
    },
  },
}

Accessibility Improvements

{/* Add focus state */}
<button className="
  bg-blue-500 text-white
  hover:bg-blue-600
  focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2
">
  Button
</button>

{/* Improve contrast */}
<p className="text-gray-700 bg-white"> {/* Changed from text-gray-500 */}
  Readable text
</p>

---

React + CSS Modules

Fixes in Module Scope

/* Component.module.css */

/* Before */
.container {
  display: flex;
}

/* After: Add overflow control */
.container {
  display: flex;
  flex-wrap: wrap;
  overflow: hidden;
  max-width: 100%;
}

Component-side Fixes

// Component.jsx
import styles from './Component.module.css';

// Before
<div className={styles.container}>

// After: Add conditional class
<div className={`${styles.container} ${isOverflow ? styles.overflow : ''}`}>

---

styled-components / Emotion

Style Fixes

// Before
const Container = styled.div`
  width: 100%;
`;

// After
const Container = styled.div`
  width: 100%;
  max-width: 100%;
  overflow-x: hidden;
  
  @media (max-width: 768px) {
    padding: 1rem;
  }
`;

Responsive Support

const Card = styled.div`
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1.5rem;
  
  @media (max-width: 1024px) {
    grid-template-columns: repeat(2, 1fr);
  }
  
  @media (max-width: 640px) {
    grid-template-columns: 1fr;
    gap: 1rem;
  }
`;

Consistency with Theme

// theme.js
export const theme = {
  colors: {
    primary: '#2563eb',
    text: '#1f2937',
    textLight: '#4b5563', // Improved contrast
  },
  spacing: {
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
  },
};

// Usage
const Text = styled.p`
  color: ${({ theme }) => theme.colors.text};
  margin-bottom: ${({ theme }) => theme.spacing.md};
`;

---

Vue (Scoped Styles)

Fixing Scoped Styles

<template>
  <div class="container">
    <p class="text">Content</p>
  </div>
</template>

<style scoped>
/* Applied only to this component */
.container {
  max-width: 100%;
  overflow: hidden;
}

.text {
  /* Fix: Improve contrast */
  color: #374151; /* Was: #9ca3af */
}

/* Responsive */
@media (max-width: 768px) {
  .container {
    padding: 1rem;
  }
}
</style>

Deep Selectors (Affecting Child Components)

<style scoped>
/* Override child component styles (use cautiously) */
:deep(.child-class) {
  margin-bottom: 1rem;
}
</style>

---

Next.js / App Router

Global Style Fixes

/* app/globals.css */
:root {
  --foreground: #171717;
  --background: #ffffff;
}

/* Prevent layout overflow */
html, body {
  max-width: 100vw;
  overflow-x: hidden;
}

/* Prevent image overflow */
img {
  max-width: 100%;
  height: auto;
}

Fixes in Layout Components

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="min-h-screen flex flex-col">
        <header className="sticky top-0 z-50">
          {/* Header */}
        </header>
        <main className="flex-1 container mx-auto px-4 py-8">
          {children}
        </main>
        <footer>
          {/* Footer */}
        </footer>
      </body>
    </html>
  );
}

---

Common Patterns

Fixing Flexbox Layout Issues

/* Before: Items overflow */
.flex-container {
  display: flex;
  gap: 1rem;
}

/* After: Wrap and size control */
.flex-container {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}

.flex-item {
  flex: 1 1 300px; /* grow, shrink, basis */
  min-width: 0; /* Prevent flexbox overflow issues */
}

Fixing Grid Layout Issues

/* Before: Fixed column count */
.grid-container {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
}

/* After: Auto-adjust */
.grid-container {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 1.5rem;
}

Organizing z-index

/* Systematize z-index */
:root {
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-modal-backdrop: 300;
  --z-modal: 400;
  --z-tooltip: 500;
}

.modal {
  z-index: var(--z-modal);
}

Adding Focus States

/* Add focus state to all interactive elements */
button:focus-visible,
a:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

/* Customize focus ring */
.custom-focus:focus-visible {
  outline: none;
  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.5);
}

---

Debugging Techniques

Visualizing Element Boundaries

/* Use only during development */
* {
  outline: 1px solid red !important;
}

Detecting Overflow

// Run in console to detect overflow elements
document.querySelectorAll('*').forEach(el => {
  if (el.scrollWidth > el.clientWidth) {
    console.log('Horizontal overflow:', el);
  }
  if (el.scrollHeight > el.clientHeight) {
    console.log('Vertical overflow:', el);
  }
});

Checking Contrast Ratio

// Use Chrome DevTools Lighthouse or axe DevTools
// Or check at the following site:
// https://webaim.org/resources/contrastchecker/

Visual Inspection Checklist

This document is a comprehensive checklist of items to verify during web design visual inspection.

---

1. Layout Verification

Structural Integrity

• [ ] Header is correctly fixed/positioned at the top of the screen
• [ ] Footer is positioned at the bottom of the screen or end of content
• [ ] Main content area is center-aligned with appropriate width
• [ ] Sidebar (if present) is positioned correctly
• [ ] Navigation is displayed in the intended position

Overflow

• [ ] Horizontal scrollbar is not unintentionally displayed
• [ ] Content does not overflow from parent elements
• [ ] Images fit within parent containers
• [ ] Tables do not exceed container width
• [ ] Code blocks wrap or scroll appropriately

Alignment

• [ ] Grid items are evenly distributed
• [ ] Flex item alignment is correct
• [ ] Text alignment (left/center/right) is consistent
• [ ] Icons and text are vertically aligned
• [ ] Form labels and input fields are correctly positioned

---

2. Typography Verification

Readability

• [ ] Body text font size is sufficient (minimum 16px recommended)
• [ ] Line height is appropriate (1.5-1.8 recommended)
• [ ] Characters per line is appropriate (40-80 characters recommended)
• [ ] Spacing between paragraphs is sufficient
• [ ] Heading size hierarchy is clear

Text Handling

• [ ] Long words wrap appropriately
• [ ] URLs and code are handled properly
• [ ] No text clipping occurs
• [ ] Ellipsis (...) displays correctly
• [ ] Language-specific line breaking rules work correctly

Fonts

• [ ] Web fonts load correctly
• [ ] Fallback fonts are appropriate
• [ ] Font weights are as intended
• [ ] Special characters and emoji display correctly

---

3. Color & Contrast Verification

Accessibility (WCAG Standards)

• [ ] Body text: Contrast ratio 4.5:1 or higher (AA)
• [ ] Large text (18px+ bold or 24px+): 3:1 or higher
• [ ] Interactive element borders: 3:1 or higher
• [ ] Focus indicators: Sufficient contrast with background

Color Consistency

• [ ] Brand colors are unified
• [ ] Link colors are consistent
• [ ] Error state red is unified
• [ ] Success state green is unified
• [ ] Hover/active state colors are appropriate

Color Vision Diversity

• [ ] Information conveyed by shape and text, not just color
• [ ] Charts and diagrams consider color vision diversity
• [ ] Error messages don't rely solely on color

---

4. Responsive Verification

Mobile (~640px)

• [ ] Content fits within screen width
• [ ] Touch targets are 44x44px or larger
• [ ] Text is readable size
• [ ] No horizontal scrolling occurs
• [ ] Navigation is mobile-friendly (hamburger menu, etc.)
• [ ] Form inputs are easy to use

Tablet (641px~1024px)

• [ ] Layout is optimized for tablet
• [ ] Two-column layouts display appropriately
• [ ] Image sizes are appropriate
• [ ] Sidebar show/hide is appropriate

Desktop (1025px~)

• [ ] Maximum width is set and doesn't break on extra-large screens
• [ ] Spacing is sufficient
• [ ] Multi-column layouts function correctly
• [ ] Hover states are implemented

Breakpoint Transitions

• [ ] Layout transitions smoothly when screen size changes
• [ ] Layout doesn't break at intermediate sizes
• [ ] No content disappears or duplicates

---

5. Interactive Element Verification

Buttons

• [ ] Default state is clear
• [ ] Hover state exists (desktop)
• [ ] Focus state is visually clear
• [ ] Active (pressed) state exists
• [ ] Disabled state is distinguishable
• [ ] Loading state (if applicable)

Links

• [ ] Links are visually identifiable
• [ ] Visited links are distinguishable (if needed)
• [ ] Hover state exists
• [ ] Focus state is clear

Form Elements

• [ ] Input field boundaries are clear
• [ ] Placeholder text contrast is appropriate
• [ ] Visual feedback on focus
• [ ] Error state display
• [ ] Required field indication
• [ ] Dropdowns function correctly

---

6. Images & Media Verification

Images

• [ ] Images display at appropriate size
• [ ] Aspect ratio is maintained
• [ ] High resolution display support (@2x)
• [ ] Display when image fails to load
• [ ] Lazy loading behavior works

Video & Embeds

• [ ] Videos fit within containers
• [ ] Aspect ratio is maintained
• [ ] Embedded content is responsive
• [ ] iframes don't overflow

---

7. Accessibility Verification

Keyboard Navigation

• [ ] All interactive elements accessible via Tab key
• [ ] Focus order is logical
• [ ] Focus traps are appropriate (modals, etc.)
• [ ] Skip to content link exists

Screen Reader Support

• [ ] Images have alt text
• [ ] Forms have labels
• [ ] ARIA labels are appropriately set
• [ ] Heading hierarchy is correct (h1→h2→h3...)

Motion

• [ ] Animations are not excessive
• [ ] prefers-reduced-motion is supported (if possible)

---

8. Performance-related Visual Issues

Loading

• [ ] Font FOUT/FOIT is minimal
• [ ] No layout shift (CLS) occurs
• [ ] No jumping when images load
• [ ] Skeleton screens are appropriate (if applicable)

Animation

• [ ] Animations are smooth (60fps)
• [ ] No performance issues when scrolling
• [ ] Transitions are natural

---

Priority Matrix

---

Verification Tools

Browser DevTools

• Elements panel: DOM and style inspection
• Lighthouse: Performance and accessibility audits
• Device toolbar: Responsive testing

Accessibility Tools

• axe DevTools
• WAVE
• Color Contrast Analyzer

Automation Tools

• Playwright (screenshot comparison)
• Percy / Chromatic (Visual Regression Testing)