zhongwei/gh-hirefrank-hirefrank-marketplace-plugins-edge-stack

Files

Zhongwei Li bd85f56f7c Initial commit

2025-11-29 18:45:50 +08:00

16 KiB

Raw Blame History

description

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

Senior Frontend Design Architect with expertise in shadcn/ui, Tailwind CSS, accessibility (WCAG 2.1 AA), and distinctive design patterns

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

- 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

Main Tasks

1. Project Analysis

First, I need to understand the project structure and identify all frontend files. This enables targeted design review of components, pages, and configuration.

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:

✅ shadcn-ui-design-validator (SKILL)
- Detects Inter/Roboto fonts
- Detects purple gradients
- Detects missing animations
- Validates typography hierarchy
- Checks color contrast
✅ component-aesthetic-checker (SKILL)
- Validates component customization depth
- Checks for default props only
- Ensures consistent design system
- Validates spacing patterns
- Checks loading states
✅ 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:

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
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
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)

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
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

After all agents complete, I need to consolidate findings, remove duplicates, and prioritize by impact on brand distinctiveness and user experience.

Consolidation Process:

<consolidation_steps>

Collect all findings from skills and agents
Remove duplicates (same issue reported by multiple sources)
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)
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
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:

<!-- app/components/Hero.tsx:12 -->
<h1 class="text-4xl font-sans">Welcome</h1>

<!-- tailwind.config.ts -->
fontFamily: {
  sans: ['Inter', 'system-ui']  // ❌ Generic
}

Recommendation:

<!-- 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:

Update tailwind.config.ts with custom fonts (5 min)
Add font-heading class to all headings (10 min)
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:

<div class="bg-gradient-to-r from-purple-500 to-purple-600">
  <h1 class="text-white">Hero Title</h1>
</div>

Recommendation:

<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:

Add brand colors to tailwind.config.ts (5 min)
Update Hero component with atmospheric background (15 min)
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:

<!-- app/components/CallToAction.tsx:34 -->
<Button onClick={handleClick">Click me</Button>

Recommendation:

<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:

<!-- 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:

Create composables/useDesignSystem.ts with button variants (15 min)
Update all 23 button instances to use variants (30 min)
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

<!-- 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:

app/components/Footer.tsx:23 - Gray-400 on white (2.9:1) ❌
app/routes/about.tsx:45 - Brand-coral on white (3.2:1) ❌
app/components/Badge.tsx:12 - Yellow-300 on white (1.8:1) ❌
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)

✅ Update tailwind.config.ts with custom fonts and colors
✅ Create composables/useDesignSystem.ts with reusable variants
✅ Fix critical accessibility violations (contrast)

Priority 2: Component Updates (2-3 hours)

✅ Update all Button instances with design system variants
✅ Add hover animations to interactive elements
✅ Customize Card components with distinctive styling

Priority 3: Polish (1-2 hours)

✅ Enhance micro-interactions
✅ Add staggered animations
✅ Implement dark mode refinements

Total Time Estimate: 4-7 hours for complete implementation

Next Steps

Review Findings: Team reviews this report
Prioritize Work: Decide which issues to address
Use /triage: Create todos for approved findings
Implement Changes: Follow code examples provided
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)

If user wants to proceed with fixes, use /triage command to create actionable todos. Each todo should be specific, implementable, and include code examples.

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:

Re-run review: /es-design-review to verify improvements
Validate code: /validate to ensure no build/lint errors
Test manually: Check hover states, animations, keyboard navigation
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

16 KiB Raw Blame History

Design Review Command

Introduction

Prerequisites

Main Tasks

1. Project Analysis

Immediate Actions:

Output Summary:

2. Multi-Phase Design Review

3. Findings Synthesis and Prioritization

Consolidation Process:

Output Format:

🎨 Frontend Design Review Report

Executive Summary

Critical Issues (P1)

1. Generic Typography: Inter Font Detected

2. Purple Gradient Hero (Overused Pattern)

3. Button Components with Default Props (23 instances)

Important Issues (P2)

4. Missing Hover Animations (32 interactive elements)

Accessibility Violations (WCAG 2.1 AA)

5. Insufficient Color Contrast (4 instances)

Polish Opportunities (P3)

Implementation Roadmap

Priority 1: Foundation (1-2 hours)

Priority 2: Component Updates (2-3 hours)

Priority 3: Polish (1-2 hours)

Next Steps

Distinctiveness Score Projection

4. Create Triage-Ready Todos (Optional)

Generate Todos:

Success Criteria

Post-Review Actions

Resources

Notes

16 KiB

Raw Blame History