539 lines
16 KiB
Markdown
539 lines
16 KiB
Markdown
---
|
|
description: Comprehensive frontend design review to prevent generic aesthetics and ensure distinctive, accessible, engaging interfaces using shadcn/ui and Tailwind CSS
|
|
---
|
|
|
|
# Design Review Command
|
|
|
|
<command_purpose> Perform comprehensive frontend design reviews focusing on typography, colors, animations, component customization, and accessibility. Prevents "distributional convergence" (Inter fonts, purple gradients, minimal animations) and guides toward distinctive, branded interfaces. </command_purpose>
|
|
|
|
## Introduction
|
|
|
|
<role>Senior Frontend Design Architect with expertise in shadcn/ui, Tailwind CSS, accessibility (WCAG 2.1 AA), and distinctive design patterns</role>
|
|
|
|
**Design Philosophy** (from Claude Skills Blog):
|
|
> "Think about frontend design the way a frontend engineer would. The more you can map aesthetic improvements to implementable frontend code, the better Claude can execute."
|
|
|
|
**Core Problem**: LLMs default to generic patterns (Inter fonts, purple gradients, minimal animations) due to distributional convergence. This command identifies and fixes these patterns.
|
|
|
|
## Prerequisites
|
|
|
|
<requirements>
|
|
- Tanstack Start project with Vue 3 components
|
|
- shadcn/ui component library installed
|
|
- Tailwind 4 CSS configured
|
|
- Vue files (`.react`) in `components/`, `pages/`, `layouts/`
|
|
- (Optional) shadcn/ui MCP server for accurate component guidance
|
|
</requirements>
|
|
|
|
## Main Tasks
|
|
|
|
### 1. Project Analysis
|
|
|
|
<thinking>
|
|
First, I need to understand the project structure and identify all frontend files.
|
|
This enables targeted design review of components, pages, and configuration.
|
|
</thinking>
|
|
|
|
#### Immediate Actions:
|
|
|
|
<task_list>
|
|
|
|
- [ ] Scan for Vue components in `components/`, `pages/`, `layouts/`, `app.react`
|
|
- [ ] Check `tailwind.config.ts` or `tailwind.config.js` for custom theme configuration
|
|
- [ ] Check `app.config.ts` for shadcn/ui configuration
|
|
- [ ] Check `app.config.ts` for global UI customization
|
|
- [ ] Identify which components use shadcn/ui (`Button`, `Card`, etc.)
|
|
- [ ] Count total Vue files to determine review scope
|
|
|
|
</task_list>
|
|
|
|
#### Output Summary:
|
|
|
|
<summary_format>
|
|
📊 **Project Scope**:
|
|
- X Vue components found
|
|
- Y shadcn/ui components detected
|
|
- Tailwind config: Found/Not Found
|
|
- shadcn/ui config: Found/Not Found
|
|
- Review target: Components + Configuration
|
|
</summary_format>
|
|
|
|
### 2. Multi-Phase Design Review
|
|
|
|
<parallel_tasks>
|
|
|
|
Run design-focused analysis in 3 phases. Focus on preventing generic patterns and ensuring accessible, distinctive design.
|
|
|
|
**Phase 1: Autonomous Skills Validation (Parallel)**
|
|
|
|
These skills run autonomously to catch generic patterns:
|
|
|
|
1. ✅ **shadcn-ui-design-validator** (SKILL)
|
|
- Detects Inter/Roboto fonts
|
|
- Detects purple gradients
|
|
- Detects missing animations
|
|
- Validates typography hierarchy
|
|
- Checks color contrast
|
|
|
|
2. ✅ **component-aesthetic-checker** (SKILL)
|
|
- Validates component customization depth
|
|
- Checks for default props only
|
|
- Ensures consistent design system
|
|
- Validates spacing patterns
|
|
- Checks loading states
|
|
|
|
3. ✅ **animation-interaction-validator** (SKILL)
|
|
- Ensures hover states on interactive elements
|
|
- Validates loading states on async actions
|
|
- Checks for smooth transitions
|
|
- Validates focus states
|
|
- Ensures micro-interactions
|
|
|
|
**Output**: List of generic patterns detected across all components
|
|
|
|
**Phase 2: Deep Agent Analysis (Parallel)**
|
|
|
|
Launch specialized agents for comprehensive review:
|
|
|
|
4. Task frontend-design-specialist(all Vue files, Tailwind config)
|
|
- Identify generic patterns (fonts, colors, animations)
|
|
- Map aesthetic improvements to code
|
|
- Provide specific Tailwind/shadcn/ui recommendations
|
|
- Prioritize by impact (P1/P2/P3)
|
|
- Generate implementable code examples
|
|
|
|
5. Task shadcn-ui-architect(all Vue files with shadcn/ui components)
|
|
- Validate component selection and usage
|
|
- Check prop usage vs available (via MCP if available)
|
|
- Validate `ui` prop customization depth
|
|
- Ensure consistent patterns across components
|
|
- Suggest deep customization strategies
|
|
|
|
6. Task accessibility-guardian(all Vue files)
|
|
- Validate WCAG 2.1 AA compliance
|
|
- Check color contrast ratios
|
|
- Validate keyboard navigation
|
|
- Check screen reader support
|
|
- Validate form accessibility
|
|
- Ensure animations respect reduced motion
|
|
|
|
**Phase 3: Configuration & Theme Review (Sequential)**
|
|
|
|
7. Review Tailwind Configuration
|
|
- Check `tailwind.config.ts` for custom fonts (not Inter/Roboto)
|
|
- Check for custom color palette (not default purple)
|
|
- Check for custom animation presets
|
|
- Validate extended spacing/sizing
|
|
- Check for design tokens
|
|
|
|
8. Review shadcn/ui Configuration
|
|
- Check `app.config.ts` for global UI customization
|
|
- Check `app.config.ts` for shadcn/ui theme settings
|
|
- Validate consistent design system approach
|
|
|
|
</parallel_tasks>
|
|
|
|
### 3. Findings Synthesis and Prioritization
|
|
|
|
<thinking>
|
|
After all agents complete, I need to consolidate findings, remove duplicates,
|
|
and prioritize by impact on brand distinctiveness and user experience.
|
|
</thinking>
|
|
|
|
#### Consolidation Process:
|
|
|
|
<consolidation_steps>
|
|
|
|
1. **Collect all findings** from skills and agents
|
|
2. **Remove duplicates** (same issue reported by multiple sources)
|
|
3. **Categorize by type**:
|
|
- Typography (fonts, hierarchy, sizing)
|
|
- Colors (palette, contrast, gradients)
|
|
- Animations (transitions, micro-interactions, hover states)
|
|
- Components (customization depth, consistency)
|
|
- Accessibility (contrast, keyboard, screen readers)
|
|
- Configuration (theme, design tokens)
|
|
|
|
4. **Prioritize by impact**:
|
|
- **P1 - Critical**: Generic patterns that make site indistinguishable
|
|
- Inter/Roboto fonts
|
|
- Purple gradients
|
|
- Default component props
|
|
- Missing animations
|
|
- Accessibility violations
|
|
- **P2 - Important**: Missed opportunities for distinctiveness
|
|
- Limited color palette
|
|
- Inconsistent component patterns
|
|
- Missing micro-interactions
|
|
- Insufficient customization depth
|
|
- **P3 - Polish**: Enhancements for excellence
|
|
- Advanced animations
|
|
- Dark mode refinements
|
|
- Enhanced accessibility
|
|
|
|
5. **Generate implementation plan** with time estimates
|
|
|
|
</consolidation_steps>
|
|
|
|
#### Output Format:
|
|
|
|
<findings_format>
|
|
|
|
# 🎨 Frontend Design Review Report
|
|
|
|
## Executive Summary
|
|
|
|
**Scope**: X components reviewed, Y configuration files analyzed
|
|
|
|
**Findings**:
|
|
- **P1 (Critical)**: X issues - Must fix for brand distinctiveness
|
|
- **P2 (Important)**: Y issues - Should fix for enhanced UX
|
|
- **P3 (Polish)**: Z opportunities - Nice to have improvements
|
|
|
|
**Generic Patterns Detected**:
|
|
- ❌ Inter font used in X components
|
|
- ❌ Purple gradient in Y components
|
|
- ❌ Default props in Z shadcn/ui components
|
|
- ❌ Missing animations on W interactive elements
|
|
- ❌ A accessibility violations (WCAG 2.1 AA)
|
|
|
|
**Distinctiveness Score**: XX/100
|
|
- Typography: XX/25 (Custom fonts, hierarchy, sizing)
|
|
- Colors: XX/25 (Brand palette, contrast, distinctive gradients)
|
|
- Animations: XX/25 (Transitions, micro-interactions, engagement)
|
|
- Components: XX/25 (Customization depth, consistency)
|
|
|
|
---
|
|
|
|
## Critical Issues (P1)
|
|
|
|
### 1. Generic Typography: Inter Font Detected
|
|
|
|
**Severity**: P1 - High Impact
|
|
**Files Affected**: 15 components
|
|
**Impact**: Indistinguishable from 80%+ of modern websites
|
|
|
|
**Finding**: Using default Inter font system-wide
|
|
|
|
**Current State**:
|
|
```tsx
|
|
<!-- app/components/Hero.tsx:12 -->
|
|
<h1 class="text-4xl font-sans">Welcome</h1>
|
|
|
|
<!-- tailwind.config.ts -->
|
|
fontFamily: {
|
|
sans: ['Inter', 'system-ui'] // ❌ Generic
|
|
}
|
|
```
|
|
|
|
**Recommendation**:
|
|
```tsx
|
|
<!-- Updated component -->
|
|
<h1 class="text-4xl font-heading tracking-tight">Welcome</h1>
|
|
|
|
<!-- tailwind.config.ts -->
|
|
fontFamily: {
|
|
sans: ['Space Grotesk', 'system-ui', 'sans-serif'], // Body
|
|
heading: ['Archivo Black', 'system-ui', 'sans-serif'], // Headings
|
|
mono: ['JetBrains Mono', 'monospace'] // Code
|
|
}
|
|
```
|
|
|
|
**Implementation**:
|
|
1. Update `tailwind.config.ts` with custom fonts (5 min)
|
|
2. Add font-heading class to all headings (10 min)
|
|
3. Verify font loading in `app.config.ts` (5 min)
|
|
**Total**: ~20 minutes
|
|
|
|
---
|
|
|
|
### 2. Purple Gradient Hero (Overused Pattern)
|
|
|
|
**Severity**: P1 - High Impact
|
|
**Files Affected**: `app/components/Hero.tsx:8`
|
|
**Impact**: "AI-generated" aesthetic, lacks brand identity
|
|
|
|
**Finding**: Hero section uses purple-500 to purple-600 gradient (appears in 60%+ of AI-generated sites)
|
|
|
|
**Current State**:
|
|
```tsx
|
|
<div class="bg-gradient-to-r from-purple-500 to-purple-600">
|
|
<h1 class="text-white">Hero Title</h1>
|
|
</div>
|
|
```
|
|
|
|
**Recommendation**:
|
|
```tsx
|
|
<div class="relative overflow-hidden">
|
|
<!-- Multi-layer atmospheric background -->
|
|
<div class="absolute inset-0 bg-gradient-to-br from-brand-coral via-brand-ocean to-brand-sunset" />
|
|
|
|
<!-- Animated gradient orbs -->
|
|
<div class="absolute top-0 left-0 w-96 h-96 bg-brand-coral/30 rounded-full blur-3xl animate-pulse" />
|
|
<div class="absolute bottom-0 right-0 w-96 h-96 bg-brand-ocean/30 rounded-full blur-3xl animate-pulse" style="animation-delay: 1s;" />
|
|
|
|
<!-- Content -->
|
|
<div class="relative z-10 py-24">
|
|
<h1 class="text-white font-heading text-6xl tracking-tight">
|
|
Hero Title
|
|
</h1>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- tailwind.config.ts: Add custom colors -->
|
|
colors: {
|
|
brand: {
|
|
coral: '#FF6B6B',
|
|
ocean: '#4ECDC4',
|
|
sunset: '#FFE66D'
|
|
}
|
|
}
|
|
```
|
|
|
|
**Implementation**:
|
|
1. Add brand colors to `tailwind.config.ts` (5 min)
|
|
2. Update Hero component with atmospheric background (15 min)
|
|
3. Test animations and responsiveness (5 min)
|
|
**Total**: ~25 minutes
|
|
|
|
---
|
|
|
|
### 3. Button Components with Default Props (23 instances)
|
|
|
|
**Severity**: P1 - High Impact
|
|
**Files Affected**: 8 components
|
|
**Impact**: Generic appearance, no brand identity
|
|
|
|
**Finding**: 23 Button instances using default props only (no customization)
|
|
|
|
**Current State**:
|
|
```tsx
|
|
<!-- app/components/CallToAction.tsx:34 -->
|
|
<Button onClick={handleClick">Click me</Button>
|
|
```
|
|
|
|
**Recommendation**:
|
|
```tsx
|
|
<Button
|
|
color="primary"
|
|
size="lg"
|
|
:ui="{
|
|
font: 'font-heading tracking-wide',
|
|
rounded: 'rounded-full',
|
|
padding: { lg: 'px-8 py-4' },
|
|
shadow: 'shadow-lg hover:shadow-xl'
|
|
}"
|
|
class="
|
|
transition-all duration-300 ease-out
|
|
hover:scale-105 hover:-rotate-1
|
|
active:scale-95 active:rotate-0
|
|
focus:outline-none
|
|
focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2
|
|
"
|
|
onClick={handleClick"
|
|
>
|
|
<span class="inline-flex items-center gap-2">
|
|
Click me
|
|
<Icon
|
|
name="i-heroicons-sparkles"
|
|
class="transition-transform duration-300 group-hover:rotate-12"
|
|
/>
|
|
</span>
|
|
</Button>
|
|
```
|
|
|
|
**Better Approach: Create Reusable Variants**:
|
|
```tsx
|
|
<!-- composables/useDesignSystem.ts -->
|
|
export const useDesignSystem = () => {
|
|
const button = {
|
|
primary: {
|
|
color: 'primary',
|
|
size: 'lg',
|
|
ui: {
|
|
font: 'font-heading tracking-wide',
|
|
rounded: 'rounded-full',
|
|
padding: { lg: 'px-8 py-4' }
|
|
},
|
|
class: 'transition-all duration-300 hover:scale-105 hover:shadow-xl'
|
|
}
|
|
};
|
|
|
|
return { button };
|
|
};
|
|
|
|
<!-- Usage in components -->
|
|
const { button } = useDesignSystem();
|
|
|
|
<Button v-bind="button.primary" onClick={handleClick">
|
|
Click me
|
|
</Button>
|
|
```
|
|
|
|
**Implementation**:
|
|
1. Create `composables/useDesignSystem.ts` with button variants (15 min)
|
|
2. Update all 23 button instances to use variants (30 min)
|
|
3. Test all button interactions (10 min)
|
|
**Total**: ~55 minutes
|
|
|
|
---
|
|
|
|
## Important Issues (P2)
|
|
|
|
### 4. Missing Hover Animations (32 interactive elements)
|
|
|
|
**Severity**: P2 - Medium Impact
|
|
**Impact**: Flat UI, reduced engagement
|
|
|
|
**Finding**: 32 interactive elements (buttons, links, cards) without hover animations
|
|
|
|
**Recommendation**: Add transition utilities to all interactive elements
|
|
```tsx
|
|
<!-- Before -->
|
|
<Card>Content</Card>
|
|
|
|
<!-- After -->
|
|
<Card
|
|
:ui="{ shadow: 'shadow-lg hover:shadow-2xl' }"
|
|
class="transition-all duration-300 hover:-translate-y-1"
|
|
>
|
|
Content
|
|
</Card>
|
|
```
|
|
|
|
[Continue with remaining P2 issues...]
|
|
|
|
---
|
|
|
|
## Accessibility Violations (WCAG 2.1 AA)
|
|
|
|
### 5. Insufficient Color Contrast (4 instances)
|
|
|
|
**Severity**: P1 - Blocker
|
|
**Standard**: WCAG 1.4.3 (4.5:1 for normal text, 3:1 for large text)
|
|
|
|
**Violations**:
|
|
1. `app/components/Footer.tsx:23` - Gray-400 on white (2.9:1) ❌
|
|
2. `app/routes/about.tsx:45` - Brand-coral on white (3.2:1) ❌
|
|
3. `app/components/Badge.tsx:12` - Yellow-300 on white (1.8:1) ❌
|
|
4. `layouts/default.tsx:67` - Blue-400 on gray-50 (2.4:1) ❌
|
|
|
|
**Fixes**: [Specific contrast-compliant color recommendations]
|
|
|
|
---
|
|
|
|
## Polish Opportunities (P3)
|
|
|
|
[List P3 improvements...]
|
|
|
|
---
|
|
|
|
## Implementation Roadmap
|
|
|
|
### Priority 1: Foundation (1-2 hours)
|
|
1. ✅ Update `tailwind.config.ts` with custom fonts and colors
|
|
2. ✅ Create `composables/useDesignSystem.ts` with reusable variants
|
|
3. ✅ Fix critical accessibility violations (contrast)
|
|
|
|
### Priority 2: Component Updates (2-3 hours)
|
|
4. ✅ Update all Button instances with design system variants
|
|
5. ✅ Add hover animations to interactive elements
|
|
6. ✅ Customize Card components with distinctive styling
|
|
|
|
### Priority 3: Polish (1-2 hours)
|
|
7. ✅ Enhance micro-interactions
|
|
8. ✅ Add staggered animations
|
|
9. ✅ Implement dark mode refinements
|
|
|
|
**Total Time Estimate**: 4-7 hours for complete implementation
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Review Findings**: Team reviews this report
|
|
2. **Prioritize Work**: Decide which issues to address
|
|
3. **Use `/triage`**: Create todos for approved findings
|
|
4. **Implement Changes**: Follow code examples provided
|
|
5. **Re-run Review**: Verify improvements with `/es-design-review`
|
|
|
|
## Distinctiveness Score Projection
|
|
|
|
**Before**: 35/100 (Generic, AI-generated aesthetic)
|
|
**After P1 Fixes**: 75/100 (Distinctive, branded)
|
|
**After P1+P2 Fixes**: 90/100 (Excellent, highly polished)
|
|
**After P1+P2+P3**: 95/100 (Outstanding, delightful)
|
|
|
|
</findings_format>
|
|
|
|
### 4. Create Triage-Ready Todos (Optional)
|
|
|
|
<thinking>
|
|
If user wants to proceed with fixes, use /triage command to create actionable todos.
|
|
Each todo should be specific, implementable, and include code examples.
|
|
</thinking>
|
|
|
|
#### Generate Todos:
|
|
|
|
<todo_format>
|
|
|
|
For each P1 issue, create a todo in `.claude/todos/` with format:
|
|
- `001-pending-p1-update-typography.md`
|
|
- `002-pending-p1-fix-hero-gradient.md`
|
|
- `003-pending-p1-customize-buttons.md`
|
|
- etc.
|
|
|
|
Each todo includes:
|
|
- **Title**: Clear, actionable
|
|
- **Severity**: P1/P2/P3
|
|
- **Files**: Specific file paths
|
|
- **Current State**: Code before
|
|
- **Target State**: Code after
|
|
- **Implementation Steps**: Numbered checklist
|
|
- **Time Estimate**: Minutes/hours
|
|
|
|
</todo_format>
|
|
|
|
Ask user: "Would you like me to create todos for these findings? You can then use `/triage` to work through them systematically."
|
|
|
|
## Success Criteria
|
|
|
|
✅ Design review complete when:
|
|
- All Vue components analyzed
|
|
- All generic patterns identified
|
|
- All accessibility violations found
|
|
- Findings categorized and prioritized
|
|
- Implementation plan provided with time estimates
|
|
- Code examples are complete and implementable
|
|
|
|
✅ Project ready for distinctive brand identity when:
|
|
- 0% Inter/Roboto font usage
|
|
- 0% purple gradient usage
|
|
- 100% of shadcn/ui components deeply customized
|
|
- 100% of interactive elements have animations
|
|
- 100% WCAG 2.1 AA compliance
|
|
- Distinctiveness score ≥ 85/100
|
|
|
|
## Post-Review Actions
|
|
|
|
After implementing fixes:
|
|
1. **Re-run review**: `/es-design-review` to verify improvements
|
|
2. **Validate code**: `/validate` to ensure no build/lint errors
|
|
3. **Test manually**: Check hover states, animations, keyboard navigation
|
|
4. **Deploy preview**: Test on actual Cloudflare Workers environment
|
|
|
|
## Resources
|
|
|
|
- Claude Skills Blog: Improving Frontend Design Through Skills
|
|
- shadcn/ui Documentation: https://ui.shadcn.com
|
|
- Tailwind 4 Documentation: https://tailwindcss.com/docs/v4-beta
|
|
- WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
|
|
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
|
|
|
|
## Notes
|
|
|
|
- This command focuses on **frontend design**, not Cloudflare Workers runtime
|
|
- Use `/review` for comprehensive code review (includes runtime, security, performance)
|
|
- Use `/es-component` to scaffold new components with best practices
|
|
- Use `/es-theme` to generate custom design themes
|