secondsky/claude-skills / plugins/design-review/skills/design-review
design-review
Verified7-phase frontend design review with accessibility (WCAG 2.1 AA), responsive testing, visual polish. Use for PR reviews, UI audits, or encountering contrast issues, broken layouts, accessibility violations, inconsistent spacing, missing focus states.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.1 KB |
| assets/checklist-template.md | markdown | 9.5 KB |
| assets/review-report-template.md | markdown | 11.0 KB |
| references/accessibility-wcag.md | markdown | 22.6 KB |
| references/browser-tools-reference.md | markdown | 14.3 KB |
| references/code-health-patterns.md | markdown | 13.2 KB |
| references/design-principles-s-tier.mdexecutable | script | 9.1 KB |
| references/interaction-patterns.md | markdown | 15.7 KB |
| references/responsive-testing.md | markdown | 13.1 KB |
| references/visual-polish.md | markdown | 15.4 KB |
references/visual-polish.md
View on GitHub# Visual Polish & Design Principles
**Objective**: Assess aesthetic quality and visual consistency
**Standards**: S-Tier SaaS design (Stripe, Airbnb, Linear quality)
**Focus**: Typography, spacing, color, alignment, visual hierarchy
---
## Core Design Philosophy
### 1. Meticulous Craft
Aim for precision, polish, and high quality in every UI element. Details matter.
**What to look for:**
- Pixel-perfect alignment (no 1-2px misalignments)
- Consistent spacing throughout
- Crisp, high-quality images
- Smooth transitions and animations
### 2. Simplicity & Clarity
Strive for clean, uncluttered interfaces. Every element should have a purpose.
**Red flags:**
- Visual clutter (too many competing elements)
- Unclear information hierarchy
- Decorative elements without purpose
- Confusing labels or icons
### 3. Consistency
Maintain uniform design language across the entire interface.
**Check for:**
- Consistent button styles
- Uniform spacing scale
- Cohesive color palette
- Predictable interaction patterns
---
## Typography Hierarchy
### Font Scale Standards
**Establish clear distinction between levels:**
| Element | Size Range | Weight | Line Height | Use Case |
|---------|-----------|--------|-------------|----------|
| **H1** | 32-48px | Bold (700) | 1.2-1.3 | Page titles |
| **H2** | 24-32px | SemiBold (600) | 1.3 | Section headers |
| **H3** | 20-24px | SemiBold (600) | 1.4 | Sub-sections |
| **H4** | 18-20px | Medium (500) | 1.4 | Card titles |
| **Body** | 16-18px | Regular (400) | 1.5-1.7 | Main content |
| **Caption** | 14px | Regular (400) | 1.6 | Helper text |
| **Small** | 12px | Regular (400) | 1.6 | Metadata |
### Typography Checklist
- [ ] **Clear hierarchy**: H1 visually distinct from H2, H2 from H3, etc.
- [ ] **Consistent font family**: Ideally 1-2 fonts maximum (e.g., Inter, Manrope, system-ui)
- [ ] **Limited font weights**: 3-4 weights (Regular 400, Medium 500, SemiBold 600, Bold 700)
- [ ] **Generous line height**: 1.5-1.7 for body text (WCAG readability)
- [ ] **Appropriate line length**: 45-75 characters per line for readability
- [ ] **Readable font size**: 16px minimum for body text
### Common Typography Issues
**❌ Poor hierarchy:**
```css
h1 { font-size: 24px; font-weight: 600; }
h2 { font-size: 22px; font-weight: 600; }
/* Too similar - not clearly distinct */
```
**✅ Clear hierarchy:**
```css
h1 { font-size: 36px; font-weight: 700; line-height: 1.2; }
h2 { font-size: 24px; font-weight: 600; line-height: 1.3; }
/* Obvious visual distinction */
```
**❌ Too many font weights:**
```css
/* Using 6 different weights */
font-weight: 300; /* Light */
font-weight: 400; /* Regular */
font-weight: 500; /* Medium */
font-weight: 600; /* SemiBold */
font-weight: 700; /* Bold */
font-weight: 900; /* Black */
```
**✅ Limited, purposeful weights:**
```css
/* Stick to 3-4 weights */
body { font-weight: 400; } /* Regular - body text */
strong { font-weight: 600; } /* SemiBold - emphasis */
h1, h2 { font-weight: 700; } /* Bold - headings */
```
---
## Spacing & Layout
### Spacing Scale (8-Point Grid)
**Standard scale based on 8px base unit:**
| Token | Value | Use Case |
|-------|-------|----------|
| space-1 | 4px | Tight spacing (icon padding) |
| space-2 | 8px | Small gaps (list items) |
| space-3 | 12px | Default spacing (form fields) |
| space-4 | 16px | Standard spacing (paragraphs) |
| space-6 | 24px | Section spacing |
| space-8 | 32px | Large sections |
| space-12 | 48px | Major sections |
| space-16 | 64px | Page sections |
### Spacing Checklist
- [ ] **Consistent scale**: All spacing uses 8px multiples (8, 16, 24, 32, etc.)
- [ ] **No magic numbers**: Avoid random values like 17px, 23px
- [ ] **Design token usage**: Spacing values reference design tokens (var(--space-4))
- [ ] **Strategic white space**: Ample breathing room improves clarity
- [ ] **Visual grouping**: Related elements closer together (proximity principle)
### Common Spacing Issues
**❌ Inconsistent spacing:**
```css
.card-1 { padding: 17px; }
.card-2 { padding: 20px; }
.card-3 { padding: 16px; }
/* Random values - no system */
```
**✅ Consistent spacing scale:**
```css
.card-1 { padding: var(--space-4); } /* 16px */
.card-2 { padding: var(--space-4); } /* 16px */
.card-3 { padding: var(--space-4); } /* 16px */
/* Follows design system */
```
**❌ Cramped spacing:**
```css
.content {
padding: 8px;
margin-bottom: 4px;
}
/* Too tight - feels claustrophobic */
```
**✅ Generous spacing:**
```css
.content {
padding: var(--space-6); /* 24px */
margin-bottom: var(--space-4); /* 16px */
}
/* Breathing room */
```
---
## Color Palette & Usage
### Color System Structure
**1. Neutrals (Grays):**
- 5-7 steps from white to black
- Used for text, backgrounds, borders
- Example: gray-50, gray-100, gray-200, ..., gray-900
**2. Primary Brand Color:**
- Main brand color with shades (50-900)
- Used sparingly for CTAs and emphasis
- Example: blue-50, blue-100, ..., blue-900
**3. Semantic Colors:**
- **Success**: Green shades (success-50 → success-900)
- **Error/Destructive**: Red shades (error-50 → error-900)
- **Warning**: Yellow/Amber shades (warning-50 → warning-900)
- **Info**: Blue shades (info-50 → info-900)
### Color Checklist
- [ ] **Limited palette**: 1 primary + neutrals + semantic colors
- [ ] **Consistent application**: Same color for same purpose throughout
- [ ] **Design tokens**: Colors use CSS variables (var(--color-primary))
- [ ] **No hardcoded colors**: Avoid inline `#3b82f6` values
- [ ] **Semantic usage**: Red for errors, green for success, etc.
- [ ] **Accessibility**: All color combinations meet WCAG AA contrast (4.5:1)
### Common Color Issues
**❌ Random color values:**
```css
.button-1 { background: #3b82f6; }
.button-2 { background: #4a90e2; }
.button-3 { background: #2563eb; }
/* Three different blues - inconsistent */
```
**✅ Design token usage:**
```css
.button-1 { background: var(--color-primary-600); }
.button-2 { background: var(--color-primary-600); }
.button-3 { background: var(--color-primary-600); }
/* Consistent, reusable */
```
**❌ Poor semantic color usage:**
```css
.success { color: blue; }
.error { color: purple; }
/* Confusing - doesn't match expectations */
```
**✅ Semantic color usage:**
```css
.success { color: var(--color-success-600); } /* Green */
.error { color: var(--color-error-600); } /* Red */
/* Clear, expected meanings */
```
---
## Alignment & Grid
### Alignment Principles
**1. Everything on a grid:**
- Use 12-column grid system (or similar)
- Align elements to grid lines
- Consistent gutters between columns
**2. Visual alignment:**
- Left-align text for Western languages
- Right-align numbers in tables
- Center-align sparingly (headings, empty states)
**3. Optical alignment:**
- Sometimes perfect mathematical alignment looks wrong
- Adjust for visual balance (e.g., icons with text)
### Alignment Checklist
- [ ] **Grid-based layout**: Elements align to consistent grid
- [ ] **Consistent alignment**: Similar elements aligned the same way
- [ ] **No random positioning**: Avoid arbitrary offsets
- [ ] **Vertical rhythm**: Consistent vertical spacing pattern
- [ ] **Baseline alignment**: Text baselines align across columns
### Common Alignment Issues
**❌ Misaligned elements:**
```css
.card-1 { margin-left: 18px; }
.card-2 { margin-left: 16px; }
.card-3 { margin-left: 20px; }
/* Off by 1-2px - looks sloppy */
```
**✅ Precise alignment:**
```css
.card-1 { margin-left: var(--space-4); } /* 16px */
.card-2 { margin-left: var(--space-4); } /* 16px */
.card-3 { margin-left: var(--space-4); } /* 16px */
/* Perfectly aligned */
```
---
## Visual Hierarchy
### Hierarchy Techniques
**1. Size:** Larger = more important
**2. Weight:** Bolder = more emphasis
**3. Color:** Brighter/contrasting = more attention
**4. Position:** Top/left = seen first (Western UIs)
**5. Spacing:** More whitespace = more prominent
### Hierarchy Checklist
- [ ] **Primary action stands out**: Largest, boldest, or most colorful button
- [ ] **Secondary actions subordinate**: Smaller, ghost buttons, less emphasis
- [ ] **Eye naturally flows**: Most important → less important
- [ ] **Grouping through proximity**: Related items closer together
- [ ] **Contrast creates focus**: High contrast for important elements
### Visual Hierarchy Examples
**❌ Weak hierarchy (everything competes):**
```html
<button class="primary">Submit</button>
<button class="primary">Cancel</button>
<button class="primary">Save Draft</button>
<!-- All equally prominent - confusing -->
```
**✅ Strong hierarchy (clear priority):**
```html
<button class="primary">Submit</button> <!-- Large, blue, bold -->
<button class="secondary">Save Draft</button> <!-- Medium, gray -->
<button class="ghost">Cancel</button> <!-- Small, text-only -->
<!-- Clear visual priority -->
```
**✅ Using size, weight, and color:**
```css
/* Primary: Large, bold, colorful */
.btn-primary {
font-size: 18px;
font-weight: 600;
background: var(--color-primary-600);
color: white;
padding: 12px 24px;
}
/* Secondary: Medium, normal, muted */
.btn-secondary {
font-size: 16px;
font-weight: 500;
background: var(--color-gray-200);
color: var(--color-gray-800);
padding: 10px 20px;
}
/* Tertiary: Small, light, minimal */
.btn-tertiary {
font-size: 14px;
font-weight: 400;
background: transparent;
color: var(--color-gray-600);
padding: 8px 16px;
}
```
---
## Image Quality & Optimization
### Image Checklist
- [ ] **High resolution**: No pixelation or blurriness (2x or 3x for retina)
- [ ] **Correct aspect ratio**: Images not stretched or squashed
- [ ] **Appropriate file size**: Optimized (WebP, compressed JPG/PNG)
- [ ] **Responsive images**: Scale to container, maintain aspect ratio
- [ ] **Alt text**: Descriptive alt attributes for accessibility
- [ ] **Loading strategy**: Lazy loading for below-fold images
### Common Image Issues
**❌ Low-quality images:**
- Pixelated or blurry (too small for display size)
- Compressed artifacts (over-compressed JPG)
- Wrong file format (PNG for photos instead of JPG)
**❌ Incorrect aspect ratios:**
```css
img {
width: 300px;
height: 200px; /* Forces specific dimensions, stretches image */
}
```
**✅ Responsive images:**
```css
img {
max-width: 100%;
height: auto; /* Maintains aspect ratio */
display: block; /* Removes inline spacing */
}
```
**✅ High-resolution images:**
```html
<!-- Serve 2x image for retina displays -->
<img
src="image.jpg"
srcset="image.jpg 1x, image-2x.jpg 2x"
alt="Descriptive text"
>
```
---
## S-Tier Design Tactics
### Module-Specific Best Practices
#### Dashboard / Admin Interfaces
- [ ] **Clear information hierarchy**: Most important metrics prominent
- [ ] **Data visualization**: Charts and graphs for complex data
- [ ] **Consistent card styling**: Uniform card components
- [ ] **Scannable layouts**: Easy to find information quickly
- [ ] **Action clarity**: Obvious CTAs for common tasks
#### Data Tables
- [ ] **Readable typography**: Legible fonts, adequate size
- [ ] **Smart alignment**: Left-align text, right-align numbers
- [ ] **Clear headers**: Bold column headers
- [ ] **Row spacing**: Adequate height for scannability
- [ ] **Interactive controls**: Sorting, filtering, search
- [ ] **Zebra striping** (optional): Alternating row colors for dense tables
#### Forms & Configuration
- [ ] **Clear labels**: Unambiguous field labels
- [ ] **Helper text**: Descriptions where needed
- [ ] **Logical grouping**: Related fields grouped together
- [ ] **Progressive disclosure**: Advanced options collapsed by default
- [ ] **Visual feedback**: Immediate confirmation of changes
- [ ] **Sensible defaults**: Pre-filled where appropriate
#### Empty States
- [ ] **Helpful illustration or icon**: Visual interest
- [ ] **Clear message**: What's missing and why
- [ ] **Call to action**: Button or link to add content
- [ ] **Avoid generic**: "No data" → "No projects yet. Create your first project!"
---
## Design System Components
### Core Components Checklist
Each component should have consistent states:
- **Default**: Normal resting state
- **Hover**: Mouse over (subtle feedback)
- **Active/Pressed**: Clicking/tapping
- **Focus**: Keyboard focus (visible outline)
- **Disabled**: Non-interactive (visually muted)
#### Buttons
- [ ] Primary, secondary, tertiary/ghost, destructive variants
- [ ] Consistent sizing (height, padding, font size)
- [ ] Clear visual hierarchy
- [ ] All states implemented (hover, active, focus, disabled)
- [ ] Icon support (left icon, right icon, icon-only)
**Example:**
```css
/* Primary: Bold, colorful */
.btn-primary {
background: var(--color-primary-600);
color: white;
min-height: 44px;
padding: 12px 24px;
border-radius: var(--radius-md);
}
.btn-primary:hover {
background: var(--color-primary-700);
}
.btn-primary:focus-visible {
outline: 2px solid var(--color-primary-600);
outline-offset: 2px;
}
.btn-primary:disabled {
background: var(--color-gray-300);
color: var(--color-gray-500);
cursor: not-allowed;
}
```
#### Form Inputs
- [ ] Consistent height (44px minimum for accessibility)
- [ ] Clear labels associated with inputs
- [ ] Placeholder text (lighter, not relied upon)
- [ ] Error states with validation messages
- [ ] Focus states visible
- [ ] Helper text for complex fields
#### Cards
- [ ] Consistent padding
- [ ] Subtle elevation/border
- [ ] Hover states for interactive cards
- [ ] Responsive (stacks on mobile)
---
## Quick Visual QA Checklist
### Typography ✓
- [ ] Clear hierarchy (H1 > H2 > H3)
- [ ] Readable font size (16px minimum body)
- [ ] Limited font families (1-2 max)
- [ ] Adequate line height (1.5+ for body)
### Spacing ✓
- [ ] Consistent scale (8px multiples)
- [ ] No magic numbers
- [ ] Design token usage
- [ ] Ample white space
### Color ✓
- [ ] Limited palette
- [ ] Semantic usage (red=error, green=success)
- [ ] Design tokens (no hardcoded colors)
- [ ] WCAG AA contrast (4.5:1 minimum)
### Alignment ✓
- [ ] Grid-based layout
- [ ] Precise alignment (no 1px offsets)
- [ ] Consistent positioning
- [ ] Vertical rhythm
### Visual Hierarchy ✓
- [ ] Primary actions stand out
- [ ] Eye flows naturally
- [ ] Related items grouped
- [ ] Contrast creates focus
### Images ✓
- [ ] High quality (no pixelation)
- [ ] Correct aspect ratios
- [ ] Responsive scaling
- [ ] Alt text present
---
## Triage Priorities
**[Blocker]:**
- Illegible text
- Broken images
- Layout completely broken
**[High]:**
- Obvious visual inconsistencies
- Poor hierarchy (all elements equal weight)
- Inconsistent spacing breaking rhythm
**[Medium]:**
- Minor alignment issues
- Inconsistent color usage
- Spacing could be tighter
**[Nitpick]:**
- Slight font weight preference
- Minor aesthetic details
- Personal style preferences
---
## Tools & Resources
### Design Inspiration
- **Stripe**: https://stripe.com
- **Linear**: https://linear.app
- **Airbnb**: https://airbnb.com
- **Vercel**: https://vercel.com
### Design Systems
- **Tailwind CSS**: https://tailwindcss.com
- **shadcn/ui**: https://ui.shadcn.com
- **Radix UI**: https://www.radix-ui.com
- **Material Design**: https://material.io
### Typography
- **Practical Typography**: https://practicaltypography.com
- **Type Scale Generator**: https://typescale.com
### Color
- **Tailwind Color Palette**: https://tailwindcss.com/docs/customizing-colors
- **Coolors**: https://coolors.co (palette generator)
- **Adobe Color**: https://color.adobe.com
---
**Remember:** Visual polish is about consistent attention to detail. Small improvements compound into exceptional user experiences.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |