zhongwei/gh-hirefrank-hirefrank-marketplace-plugins-edge-stack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:45:50 +08:00
commit bd85f56f7c
78 changed files with 33541 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

538
commands/es-design-review.md Normal file
View File

@@ -0,0 +1,538 @@
---
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