web-design-expert

Web Design Expert

Expert web designer creating distinctive visual systems for web applications.

Decision Points

Layout Approach Selection

IF content-heavy (blog, documentation, learning platform)
├─ 12-column grid system
├─ High text density with clear hierarchy
└─ Consistent gutters for readability

IF marketing/conversion focused (SaaS, e-commerce landing)
├─ Hero-section-first design
├─ Asymmetric layouts allowed for drama
└─ Large whitespace to guide attention

IF e-commerce/catalog heavy ├─ CSS Grid auto-fit for products ├─ Card-based layouts └─ Filter/search prominence

IF dashboard/app interface ├─ Sidebar + main content ├─ Data density prioritized └─ Navigation always accessible

IF editorial/magazine style ├─ Mixed grid systems ├─ Large images with pull quotes └─ Visual variety over consistency

### Color Palette Strategy

IF B2B/Enterprise audience ├─ Blue primary (trust, professional) ├─ Neutral-heavy palette └─ Minimal accent colors

IF Consumer/Lifestyle brand ├─ Warmer primaries (orange, green, purple) ├─ Seasonal accent options └─ Emotionally-driven choices

IF High-traffic/accessibility-critical ├─ 4.5:1 contrast minimum enforced ├─ Color-blind tested combinations └─ Dark mode variants required

### Visual Hierarchy Decision Tree

IF user goal = immediate action (signup, purchase) ├─ Hero CTA above fold (mandatory) ├─ Single primary action per page └─ Visual weight on conversion elements

IF user goal = content consumption ├─ Content preview/summary first ├─ Multiple engagement paths okay └─ Reading experience optimized

IF user goal = exploration (portfolio, catalog) ├─ Grid/gallery layout primary ├─ Quick scanning optimized └─ Thumbnail → detail flow

## Failure Modes

### **Design by Committee Syndrome**
- **Symptoms:** Multiple visual styles on same page, conflicting brand messages, no clear design system
- **Detection Rule:** If you see 3+ different button styles or font families on one page
- **Fix:** Establish design principles document, enforce single source of truth, get stakeholder buy-in on constraints

### **Decoration Over Function**
- **Symptoms:** Animations without purpose, visual elements that don't aid comprehension, slow loading due to graphics
- **Detection Rule:** If you can't explain why each visual element helps the user accomplish their goal
- **Fix:** Remove elements that don't serve user needs, justify every animation with user benefit

### **Mobile Afterthought Pattern**
- **Symptoms:** Horizontal scroll on mobile, tiny touch targets, desktop navigation on small screens
- **Detection Rule:** If mobile version requires zooming or horizontal scrolling to use
- **Fix:** Start mobile-first, test on actual devices, ensure 44px minimum touch targets

### **Low Contrast Accessibility Failure**
- **Symptoms:** Light gray text (#999) on white, poor readability in sunlight, user complaints about text visibility
- **Detection Rule:** If any text fails WCAG 4.5:1 contrast ratio when tested
- **Fix:** Use contrast checker tools, test in bright light conditions, provide high-contrast mode option

### **Information Architecture Collapse**
- **Symptoms:** Users can't find primary content, navigation doesn't match mental models, high bounce rates
- **Detection Rule:** If users can't complete primary task within 3 clicks or 30 seconds
- **Fix:** User journey mapping, card sorting for navigation, prominence for key actions

## Worked Examples

### Example 1: SaaS Dashboard Redesign
**Context:** B2B analytics platform, users spend 2+ hours daily in interface

**Decision Process:**
1. **Audience Analysis:** Power users who value efficiency over aesthetics
2. **Layout Choice:** Sidebar navigation (always accessible) + main content area
3. **Color Strategy:** Blue primary (#2563eb) for trust, minimal accents to reduce cognitive load
4. **Hierarchy:** Data tables get most space, actions are secondary but accessible

**Key Design Decisions:**
- Dense information display (8px spacing scale)
- High contrast text (#1f2937 on #ffffff)
- Consistent button sizing (40px height for easy clicking)
- Status indicators use semantic colors (green=good, red=alert)

**Outcome Validation:** 
- Task completion improved 23%
- User-reported "ease of use" increased
- Support tickets about navigation decreased 40%

### Example 2: E-commerce Product Page
**Context:** Fashion retailer, mobile-first audience (70% mobile traffic)

**Decision Process:**
1. **Traffic Pattern:** Mobile browsers, quick decision makers
2. **Layout Choice:** Single-column mobile, two-column desktop
3. **Visual Priority:** Product images > price > reviews > specifications
4. **Conversion Elements:** Add to cart sticky on mobile, prominent but not pushy

**Key Design Decisions:**
- Hero product image fills screen width on mobile
- Price in large, bold typography immediately visible
- Reviews summary above product details
- Size/color selectors with immediate visual feedback

**Novice vs Expert Approach:**
- **Novice would:** Put all product info above fold, use small product images
- **Expert catches:** Users need large images to evaluate fashion, price-conscious audience needs reviews validation early

**Measurable Results:**
- Mobile conversion rate increased 31%
- Average session duration increased (users exploring more products)
- Cart abandonment decreased 18%

## Quality Gates

- [ ] Primary user action is visually obvious within 3 seconds of page load
- [ ] All text passes WCAG AA contrast requirements (4.5:1 minimum)
- [ ] Mobile layout works on 320px width without horizontal scroll
- [ ] Touch targets are minimum 44px for interactive elements
- [ ] Brand colors are used consistently (same hex values across components)
- [ ] Visual hierarchy uses maximum 3 font weights and 4 sizes
- [ ] Page loads and is interactive within 3 seconds on 3G connection
- [ ] Navigation matches user mental model (confirmed by task completion rate >80%)
- [ ] Design works in both light and dark system preferences
- [ ] Components have hover, focus, and active states defined

## Validating a Design Plan

State the design's Quality Gate compliance as a structured plan (see
`schemas/design-plan.schema.json`) and check it deterministically instead of
eyeballing a mockup:

node scripts/design_audit.mjs --input plan.json

The auditor returns `{ pass, score, findings, recommendations }` and flags
the five failure modes above by name: design-by-committee (too many button
styles/font weights/sizes), decoration-over-function, mobile-afterthought
(320px horizontal scroll or sub-44px touch targets), low-contrast (below
4.5:1), and information-architecture collapse (nav that doesn't match the
user's mental model). See `examples/expected-output.md` for a passing and a
failing run side by side.

## References

| File | Load When |
| --- | --- |
| `references/layout-systems.md` | Need the grid decision tree, the 8px spacing scale, responsive breakpoints, or the mobile-first/consistency checklists. |
| `references/color-accessibility.md` | Need the minimum viable palette, color psychology table, dark-mode guidance, or the WCAG 2.1 AA checklist. |
| `references/tooling-integration.md` | Need to use 21st.dev or Figma MCP tools to go from design direction to code. |
| `templates/output-template.md` | Need a reusable design-plan template to fill in before auditing. |
| `examples/expected-output.md` | Need the shape of a finished design-plan audit, both passing and failing. |
| `schemas/design-plan.schema.json` | Need to validate a design plan's structure programmatically. |
| `scripts/design_audit.mjs` | Need deterministic scoring of a design plan against the Quality Gates and named failure modes. |
| `agents/openai.yaml` | Need a subagent descriptor for delegated design-plan generation. |

## NOT-FOR Boundaries

**Do NOT use this skill for:**
- Deep typography decisions (line-height calculations, character spacing) → use **typography-expert**
- Color theory mathematics or palette generation → use **color-theory-palette-harmony-expert** 
- Design system token architecture or CSS variables → use **design-system-creator**
- Retro or historical design styles → use **windows-3-1-web-designer**
- Native mobile app interface design → delegate to **native-app-designer**
- Detailed accessibility audits → use **accessibility-expert**
- Animation and micro-interaction specifications → use **motion-design-expert**

**Boundary indicators:**
- If user asks for specific font pairing recommendations → typography-expert
- If user needs HSL color calculations → color-theory-expert
- If user wants CSS architecture advice → design-system-creator
- If user needs WCAG compliance checklist → accessibility-expert

## Layout QA gate (mechanical — run before shipping)

Before calling any rendered page, artifact, dashboard, deck, or component done,
run the mechanical overflow/collision checker. It renders the page headlessly and
flags text-vs-text collisions, clipped/ellipsis-truncated elements, text escaping
its container, and horizontal page scroll — the visual defects a screenshot hides
and that only appear at a specific width or in one theme.

Resolve `layout-overflow-guard` from the active skill catalog before running it.
The command below shows the standard Claude install path; use the path reported
by your harness. If the skill is absent, install or sync it instead of skipping
this gate.

```bash
python3 ~/.claude/skills/layout-overflow-guard/scripts/check_layout.py <file-or-url> \
  --widths 1280,1100,860,720,390 --themes light,dark

You do not need to read check_layout.py — invoke it with the Bash tool and act on its report and exit code (non-zero = a defect). The script's source never enters your context; only its findings do. Drive it to zero violations across every width and both themes before you ship. Full detail: the layout-overflow-guard skill.

Skill Bundle Index

Every file in this skill, and when to open it. Auto-generated; run scripts/index_references.py --fix.

root

• CHANGELOG.md — Changelog — All notable changes to the web-design-expert skill will be documented in this file.
• README.md — Web Design Expert — Creates unique web visual systems: brand identity, color palettes, layout composition, and responsive UI patterns for web applications.

agents/

• agents/openai.yaml — openai (data/schema)

examples/

• examples/expected-output.md — Example Output: Web Design Plan Audit — Scenario: a SaaS marketing site redesign has been specified as a structured design plan (matching schemas/design-plan.schema.json) and is
• examples/sample-input.json — sample input (data/schema)

references/

• references/color-accessibility.md — Color & Accessibility — Color palettes, psychology, dark mode, and WCAG compliance.
• references/layout-systems.md — Layout Systems — Grid systems, spacing scales, and layout composition.
• references/tooling-integration.md — Design Tooling Integration — 21st.dev, Figma MCP, and component workflows.

schemas/

• schemas/design-plan.schema.json — design plan.schema (data/schema)

scripts/

• scripts/design_audit.mjs

templates/

• templates/output-template.md — Web Design Plan Template — [One-sentence description of the product/page this design plan covers.] Field notes: - primaryActionObviousWithin3s — true only if a fresh