design-layout-principles

<core_philosophy> These designers share fundamental beliefs:

The Dynamic:

• Steve says “get the spacing and hierarchy right first”
• Rauno says “now sweat every detail”
• Mariana says “try something unexpected”
• Emil says “but only if it serves the user”
• Paco says “and make it fast” </core_philosophy>

<audit_workflow>

Step 1: Context Reconnaissance

Before auditing code, gather project context:

• Check CLAUDE.md or README for project type
• Review existing UI patterns and design system
• Identify target audience (productivity tool vs consumer app vs marketing site)

Step 2: Layout Gap Analysis

Proactively search the codebase for design philosophy violations:

Spacing & Layout Gaps

# Hardcoded pixel values (should use spacing tokens)
grep -r "margin:\s*[0-9]" --include="*.css" --include="*.tsx"
grep -r "padding:\s*[0-9]" --include="*.css" --include="*.tsx"
grep -r "gap:\s*[0-9]" --include="*.css" --include="*.tsx"

Color Gaps

# Hardcoded colors (should use color tokens)
grep -r "#[0-9a-fA-F]\{3,6\}" --include="*.css" --include="*.tsx"
grep -r "rgb\(a\?\)(" --include="*.css" --include="*.tsx"

Interaction Gaps

# Interactive elements missing states
grep -r "onClick" --include="*.tsx" -l  # Then check for :hover/:focus
grep -r "cursor:\s*pointer" --include="*.css"  # Should have hover state

Transition Gaps

# Style changes without transitions
grep -r ":hover\|:focus\|:active" --include="*.css" -A5  # Check for transition

Typography Gaps

# Hardcoded font sizes (should use type scale)
grep -r "font-size:\s*[0-9]" --include="*.css" --include="*.tsx"

Accessibility Gaps

# Interactive elements without accessible names
grep -r "<button" --include="*.tsx" | grep -v "aria-label"
grep -r "<img" --include="*.tsx" | grep -v "alt="

Z-Index Gaps

# Arbitrary z-index values (should use layering system)
grep -r "z-index:\s*[0-9]" --include="*.css" --include="*.tsx"

Gap Analysis Output

Document findings in categories:

• Token violations — Hardcoded values that should use design tokens
• State gaps — Missing hover, focus, active, or disabled states
• Transition gaps — Abrupt style changes without smooth transitions
• Accessibility gaps — Missing ARIA attributes, labels, or keyboard support
• Consistency gaps — Patterns that differ from established design system

Step 3: Designer Weighting

Weight perspectives based on project stage:

Step 4: Full Audit

Read the audit checklist first, then the designer reference files matching your context weighting:

Required reading order:

1. audit-checklist.md — Structured criteria for review
2. references/steve-schoger.md — Foundation (always first)
3. Additional designer files based on weighting

Step 5: Structured Output

Present findings with:

1. Quick Summary — 2-3 sentence overall assessment
2. Per-Designer Sections — Using their voice and specific recommendations
3. Combined Recommendations — Prioritized with severity indicators
4. Designer Reference Summary — Which principles were most relevant </audit_workflow>

<output_format>

UI Craft Audit: {Component/Page Name}

Quick Summary

{2-3 sentences on overall state and key issues}

Steve Schoger (Fundamentals)

{Specific feedback on spacing, hierarchy, typography, color}

Rauno Freiberg (Polish)

{Specific feedback on details, consistency, soul}

Mariana Castilho (Experimentation)

{Opportunities for unexpected delight, component transformation}

Emil Kowalski (Restraint)

{Animation timing, necessity check, speed recommendations}

Paco Coursey (Performance)

{Keyboard support, accessibility, interaction polish}

Combined Recommendations

Critical (Must Fix):

• {Issue with specific fix}

Important (Should Fix):

• {Issue with specific fix}

Nice to Have:

• {Enhancement opportunity} </output_format>

<reference_index>

Reference Files

All in references/:

Designer Philosophies

Technical Deep-Dives

<quick_reference>

Designer Voice Quick Reference

Steve: “The hierarchy is unclear — everything competes for attention. Make the secondary text gray-500 instead of gray-700. Increase section spacing from 16px to 24px.”

Rauno: “The toggle switches lack satisfying feedback. Add a subtle scale animation (0.95 → 1.0) on press. Consider a subtle background color shift on hover.”

Mariana: “This layout is functional but predictable. Consider progressive disclosure for advanced settings. What if toggling a setting briefly highlighted its effect?”

Emil: “The section expand animation (300ms) feels sluggish. Reduce to 150ms or use instant toggle. Do you need animation on the toggle? Sometimes instant is better.”

Paco: “No keyboard navigation. Add Tab focus with visible ring. The save button should have an :active state that feels ‘pressed.'” </quick_reference>