web-design-guidelines

---
name: web-design-guidelines
description: Inspection visuelle et revue de code pour la conformité aux Web Interface Guidelines. Se déclenche sur « review my UI », « check accessibility », « audit design », « review UX », « fix the layout », « find design problems ». Supporte l'analyse statique du code et l'inspection visuelle dans le navigateur avec correction automatique.
license: MIT
---

# Web Interface Guidelines

Review and fix UI for compliance with Web Interface Guidelines through static code analysis and visual browser inspection.

## Scope of Application

- Static sites (HTML/CSS/JS)
- SPA frameworks: React / Vue / Angular / Svelte
- Full-stack frameworks: Next.js / Nuxt / SvelteKit
- Any web application with accessible source code

## Workflow Overview

```
Step 1: Information Gathering
    ↓
Step 2: Guidelines Fetch + Static Analysis
    ↓
Step 3: Visual Inspection (if URL provided)
    ↓
Step 4: Issue Fixing
    ↓
Step 5: Re-verification
    ↓
(Loop if issues remain)
```

---

## Step 1: Information Gathering

### 1.1 Determine Review Mode

| Input | Mode | Actions |
|-------|------|---------|
| File/pattern only | Static Analysis | Code review against guidelines |
| URL only | Visual Inspection | Browser-based visual review |
| URL + files | Full Review | Both static and visual analysis |

### 1.2 URL Confirmation (Visual Mode)

If visual inspection requested but no URL provided, ask:

> Please provide the URL of the website to review (e.g., `http://localhost:3000`)

### 1.3 Project Detection

Attempt automatic detection from workspace files:

| File | Detection |
|------|-----------|
| `package.json` | Framework and dependencies |
| `tailwind.config.*` | Tailwind CSS |
| `next.config.*` | Next.js |
| `nuxt.config.*` | Nuxt |
| `vite.config.*` | Vite |

### 1.4 Styling Method Identification

| Method | Detection | Edit Target |
|--------|-----------|-------------|
| Pure CSS | `*.css` files | Global or component CSS |
| SCSS/Sass | `*.scss`, `*.sass` | SCSS files |
| CSS Modules | `*.module.css` | Module CSS files |
| Tailwind CSS | `tailwind.config.*` | className in components |
| styled-components | `styled.` in code | JS/TS files |
| CSS-in-JS | Inline styles | JS/TS files |

---

## Step 2: Guidelines Fetch + Static Analysis

### 2.1 Fetch Latest Guidelines

Fetch fresh guidelines before each review:

```
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
```

Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.

### 2.2 Static Code Analysis

1. Read the specified files (or prompt user for files/pattern)
2. Check against all rules in the fetched guidelines
3. Collect findings with `file:line` references

---

## Step 3: Visual Inspection (Browser Mode)

### 3.1 Prerequisites

- Target website must be running (local dev server or remote)
- Browser automation available (Playwright MCP or cursor-browser-extension)

### 3.2 Page Inspection

1. Navigate to the specified URL
2. Capture screenshots
3. Retrieve DOM structure/snapshot
4. If additional pages exist, traverse through navigation

### 3.3 Viewport Testing

Test at the following viewports for responsive issues:

| Name | Width | Representative Device |
|------|-------|----------------------|
| Mobile | 375px | iPhone SE/12 mini |
| Tablet | 768px | iPad |
| Desktop | 1280px | Standard PC |
| Wide | 1920px | Large display |

### 3.4 Visual Inspection Checklist

#### Layout Issues

| Issue | Description | Severity |
|-------|-------------|----------|
| Element Overflow | Content overflows container or viewport | High |
| Element Overlap | Unintended overlapping of elements | High |
| Alignment Issues | Grid or flex alignment problems | Medium |
| Inconsistent Spacing | Padding/margin inconsistencies | Medium |
| Text Clipping | Long text not handled properly | Medium |

#### Responsive Issues

| Issue | Description | Severity |
|-------|-------------|----------|
| Non-mobile Friendly | Layout breaks on small screens | High |
| Breakpoint Issues | Unnatural transitions at breakpoints | Medium |
| Touch Targets | Buttons too small on mobile | Medium |

#### Accessibility Issues

| Issue | Description | Severity |
|-------|-------------|----------|
| Insufficient Contrast | Low contrast ratio text/background | High |
| No Focus State | Cannot see focus during keyboard nav | High |
| Missing alt Text | No alternative text for images | Medium |

#### Visual Consistency

| Issue | Description | Severity |
|-------|-------------|----------|
| Font Inconsistency | Mixed font families | Medium |
| Color Inconsistency | Non-unified brand colors | Medium |
| Spacing Inconsistency | Non-uniform spacing patterns | Low |

---

## Step 4: Issue Fixing

### 4.1 Issue Prioritization

| Priority | Criteria | Action |
|----------|----------|--------|
| P1 | Layout issues affecting functionality | Fix immediately |
| P2 | Visual issues degrading UX | Fix next |
| P3 | Minor visual inconsistencies | Fix if possible |

### 4.2 Identifying Source Files

1. **Selector-based Search**: Search codebase by class name or ID
2. **Component-based Search**: Identify components from element text/structure
3. **File Pattern Filtering**: `src/**/*.css`, `styles/**/*`, `src/components/**/*`

### 4.3 Fix Principles

1. **Minimal Changes**: Only make minimum changes necessary
2. **Respect Existing Patterns**: Follow existing code style
3. **Avoid Breaking Changes**: Be careful not to affect other areas
4. **Add Comments**: Explain reason for fixes where appropriate

---

## Step 5: Re-verification

### 5.1 Post-fix Confirmation

1. Reload browser (or wait for HMR)
2. Capture screenshots of fixed areas
3. Compare before and after

### 5.2 Regression Testing

- Verify fixes haven't affected other areas
- Confirm responsive display is not broken

### 5.3 Iteration

If issues remain after fix, return to Step 3. Limit to 3 fix attempts per issue before consulting user.

---

## Output Format

### Review Results Report

```markdown
# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target | {URL or files} |
| Framework | {Detected framework} |
| Styling | {CSS / Tailwind / etc.} |
| Review Mode | {Static / Visual / Full} |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Static Analysis Findings

{file:line format findings from guidelines check}

## Visual Inspection Findings

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}

### [P2] {Issue Title}
...

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}
```

---

## Usage Examples

### Static Analysis Only

```
Review my UI in src/components/
Check accessibility of my forms
Audit design of src/pages/
```

### Visual Inspection

```
Review the design at http://localhost:3000
Check the UI at http://localhost:5173/dashboard
Find layout problems on my site
```

### Full Review (Recommended)

```
Review my UI at localhost:3000 and fix issues in src/
Audit the design and fix responsive problems
```

---

## Best Practices

### DO

- Always save screenshots before making fixes
- Fix one issue at a time and verify each
- Follow the project's existing code style
- Confirm with user before major changes

### DON'T

- Large-scale refactoring without confirmation
- Ignore design systems or brand guidelines
- Fix multiple issues at once (difficult to verify)
- Skip re-verification after fixes

---

## Troubleshooting

### Style files not found

1. Check dependencies in `package.json`
2. Consider CSS-in-JS possibility
3. Ask user about styling method

### Fixes not reflected

1. Check if dev server HMR is working
2. Clear browser cache
3. Check CSS specificity issues

### Fixes affecting other areas

1. Rollback changes
2. Use more specific selectors
3. Consider CSS Modules or scoped styles