Initial commit

2025-11-29 18:45:50 +08:00
commit bd85f56f7c
78 changed files with 33541 additions and 0 deletions
--- a/skills/shadcn-ui-design-validator/SKILL.md
+++ b/skills/shadcn-ui-design-validator/SKILL.md
@@ -0,0 +1,333 @@
+---
+name: shadcn-ui-design-validator
+description: Automatically validates frontend design patterns to prevent generic aesthetics (Inter fonts, purple gradients, minimal animations) and enforce distinctive, branded design during Tanstack Start (React) development with shadcn/ui
+triggers: ["tsx file creation", "component changes", "tailwind config changes", "shadcn component usage", "design system updates"]
+note: "Updated for Tanstack Start + shadcn/ui. Validates React/TSX components with shadcn/ui patterns."
+---
+
+# shadcn/ui Design Validator SKILL
+
+## Activation Patterns
+
+This SKILL automatically activates when:
+- New `.tsx` React components are created
+- Tailwind configuration (`tailwind.config.ts`) is modified
+- Tanstack Start configuration (`app.config.ts`) is modified
+- Component styling or classes are changed
+- Design token definitions are updated
+- Before deployment commands are executed
+
+## Expertise Provided
+
+### Design Pattern Validation
+- **Generic Pattern Detection**: Identifies default/overused design patterns
+- **Typography Analysis**: Ensures distinctive font choices and hierarchy
+- **Animation Validation**: Checks for engaging micro-interactions and transitions
+- **Color System**: Validates distinctive color palettes vs generic defaults
+- **Component Customization**: Ensures shadcn/ui components are customized, not default
+
+### Specific Checks Performed
+
+#### ❌ Critical Violations (Generic Design Patterns)
+```tsx
+<!-- These patterns trigger alerts: -->
+
+<!-- Generic font (Inter/Roboto) -->
+<div className="font-sans">  <!-- Using default Inter -->
+
+<!-- Purple gradient on white (overused pattern) -->
+<div className="bg-gradient-to-r from-purple-500 to-purple-600">
+
+<!-- No animations/transitions -->
+<Button onClick="submit">Submit</Button>  <!-- No hover state -->
+
+<!-- Default background colors -->
+<div className="bg-gray-50">  <!-- Generic #f9fafb -->
+```
+
+#### ✅ Correct Distinctive Patterns
+```tsx
+<!-- These patterns are validated as correct: -->
+
+<!-- Custom distinctive fonts -->
+<h1 className="font-heading">  <!-- Custom font family -->
+
+<!-- Custom brand colors -->
+<div className="bg-brand-coral">  <!-- Distinctive palette -->
+
+<!-- Engaging animations -->
+<Button
+  className="transition-all duration-300 hover:scale-105 hover:shadow-xl"
+  onClick="submit"
+>
+  Submit
+</Button>
+
+<!-- Atmospheric backgrounds -->
+<div className="bg-gradient-to-br from-brand-ocean via-brand-sky to-brand-coral">
+```
+
+## Integration Points
+
+### Complementary to Existing Components
+- **frontend-design-specialist agent**: Handles deep design analysis, SKILL provides immediate validation
+- **tanstack-ui-architect agent**: Component expertise, SKILL validates implementation
+- **es-design-review command**: SKILL provides continuous validation between explicit reviews
+
+### Escalation Triggers
+- Complex design system questions → `frontend-design-specialist` agent
+- Component customization help → `tanstack-ui-architect` agent
+- Accessibility concerns → `accessibility-guardian` agent
+- Full design review → `/es-design-review` command
+
+## Validation Rules
+
+### P1 - Critical (Generic Patterns to Avoid)
+- **Default Fonts**: Inter, Roboto, Helvetica (in over 80% of sites)
+- **Purple Gradients**: `from-purple-*` to `to-purple-*` on white backgrounds
+- **Generic Grays**: `bg-gray-50`, `bg-gray-100` (overused neutrals)
+- **No Animations**: Interactive elements without hover/focus transitions
+- **Default Component Props**: Using shadcn/ui components with all default props
+
+### P2 - Important (Polish and Engagement)
+- **Missing Hover States**: Buttons/links without hover effects
+- **No Loading States**: Async actions without loading feedback
+- **Inconsistent Spacing**: Not using Tailwind spacing scale consistently
+- **No Micro-interactions**: Forms/buttons without feedback animations
+- **Weak Typography Hierarchy**: Similar font sizes for different heading levels
+
+### P3 - Best Practices
+- **Font Weight Variety**: Using only one or two font weights
+- **Limited Color Palette**: Not defining custom brand colors
+- **No Custom Tokens**: Not extending Tailwind theme with brand values
+- **Missing Dark Mode**: No dark mode variants (if applicable)
+
+## Remediation Examples
+
+### Fixing Generic Fonts
+```tsx
+<!-- ❌ Critical: Default Inter font -->
+  <h1 className="text-4xl font-sans">Welcome</h1>
+
+<!-- ✅ Correct: Distinctive custom font -->
+  <h1 className="text-4xl font-heading tracking-tight">Welcome</h1>
+
+<!-- tailwind.config.ts -->
+export default {
+  theme: {
+    extend: {
+      fontFamily: {
+        // ❌ NOT: sans: ['Inter', 'sans-serif']
+        // ✅ YES: Distinctive fonts
+        sans: ['Space Grotesk', 'system-ui', 'sans-serif'],
+        heading: ['Archivo Black', 'system-ui', 'sans-serif'],
+        mono: ['JetBrains Mono', 'monospace']
+      }
+    }
+  }
+}
+```
+
+### Fixing Generic Colors
+```tsx
+<!-- ❌ Critical: Purple gradient (overused) -->
+  <div className="bg-gradient-to-r from-purple-500 to-purple-600">
+    <h2 className="text-white">Hero Section</h2>
+  </div>
+
+<!-- ✅ Correct: Custom brand colors -->
+  <div className="bg-gradient-to-br from-brand-coral via-brand-ocean to-brand-sunset">
+    <h2 className="text-white">Hero Section</h2>
+  </div>
+
+<!-- tailwind.config.ts -->
+export default {
+  theme: {
+    extend: {
+      colors: {
+        // ❌ NOT: Using only default Tailwind colors
+        // ✅ YES: Custom brand palette
+        brand: {
+          coral: '#FF6B6B',
+          ocean: '#4ECDC4',
+          sunset: '#FFE66D',
+          midnight: '#2C3E50',
+          cream: '#FFF5E1'
+        }
+      }
+    }
+  }
+}
+```
+
+### Fixing Missing Animations
+```tsx
+<!-- ❌ Critical: No hover/transition effects -->
+  <Button onClick="handleSubmit">
+    Submit Form
+  </Button>
+
+<!-- ✅ Correct: Engaging animations -->
+  <Button
+    className="transition-all duration-300 hover:scale-105 hover:shadow-xl active:scale-95"
+    onClick="handleSubmit"
+  >
+    <span className="inline-flex items-center gap-2">
+      Submit Form
+      <Icon
+        name="i-heroicons-arrow-right"
+        className="transition-transform duration-300 group-hover:translate-x-1"
+      />
+    </span>
+  </Button>
+```
+
+### Fixing Default Component Usage
+```tsx
+<!-- ❌ P2: All default props (generic appearance) -->
+  <Card>
+    <p>Content here</p>
+  </Card>
+
+<!-- ✅ Correct: Customized for brand distinctiveness -->
+  <Card
+    :ui="{
+      background: 'bg-white dark:bg-brand-midnight',
+      ring: 'ring-1 ring-brand-coral/20',
+      rounded: 'rounded-2xl',
+      shadow: 'shadow-xl hover:shadow-2xl',
+      body: { padding: 'p-8' }
+    }"
+    className="transition-all duration-300 hover:-translate-y-1"
+  >
+    <p className="text-gray-700 dark:text-gray-300">Content here</p>
+  </Card>
+```
+
+## MCP Server Integration
+
+When shadcn/ui MCP server is available:
+- Query component customization options before validation
+- Verify that suggested customizations use valid props
+- Get latest component API to prevent hallucination
+- Validate `ui` prop structure against actual schema
+
+**Example MCP Usage**:
+```typescript
+// Validate Button customization
+const buttonDocs = await mcp.shadcn.get_component("Button");
+// Check if suggested props exist: color, size, variant, ui, etc.
+// Ensure customizations align with actual API
+```
+
+## Benefits
+
+### Immediate Impact
+- **Prevents Generic Design**: Catches overused patterns before they ship
+- **Enforces Brand Identity**: Ensures consistent, distinctive aesthetics
+- **Improves User Engagement**: Validates animations and interactions
+- **Educates Developers**: Clear explanations of design best practices
+
+### Long-term Value
+- **Consistent Visual Identity**: All components follow brand guidelines
+- **Faster Design Iterations**: Immediate feedback on design choices
+- **Better User Experience**: Polished animations and interactions
+- **Reduced Design Debt**: Prevents accumulation of generic patterns
+
+## Usage Examples
+
+### During Component Creation
+```tsx
+// Developer creates: <div className="font-sans bg-purple-500">
+// SKILL immediately activates: "⚠️ WARNING: Using default 'font-sans' (Inter) and purple gradient. Consider custom brand fonts and colors for distinctive design."
+```
+
+### During Styling
+```tsx
+// Developer adds: <Button>Click me</Button>
+// SKILL immediately activates: "⚠️ P2: Button lacks hover animations. Add transition utilities for better engagement: class='transition-all duration-300 hover:scale-105'"
+```
+
+### During Configuration
+```typescript
+// Developer modifies tailwind.config.ts with default Inter
+// SKILL immediately activates: "⚠️ P1: Using Inter font (appears in 80%+ of sites). Replace with distinctive font choices like Space Grotesk, Archivo, or other brand-appropriate fonts."
+```
+
+### Before Deployment
+```tsx
+// SKILL runs comprehensive check: "✅ Design validation passed. Custom fonts, distinctive colors, engaging animations, and customized components detected."
+```
+
+## Design Philosophy Alignment
+
+This SKILL implements the core insight from Claude's "Improving Frontend Design Through Skills" blog post:
+
+> "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."
+
+**Key Mappings**:
+- **Typography** → Tailwind `fontFamily` config + utility classes
+- **Animations** → Tailwind `transition-*`, `hover:*`, `duration-*` utilities
+- **Background effects** → Custom gradient combinations, `backdrop-*` utilities
+- **Themes** → Extended Tailwind color palette with brand tokens
+
+## Distinctive vs Generic Patterns
+
+### ❌ Generic Patterns (What to Avoid)
+```tsx
+<!-- The "AI default aesthetic" -->
+<div className="bg-white">
+  <h1 className="font-sans text-gray-900">Title</h1>
+  <div className="bg-gradient-to-r from-purple-500 to-purple-600">
+    <Button>Action</Button>
+  </div>
+</div>
+```
+
+**Problems**:
+- Inter font (default)
+- Purple gradient (overused)
+- Gray backgrounds (generic)
+- No animations (flat)
+- Default components (no customization)
+
+### ✅ Distinctive Patterns (What to Strive For)
+```tsx
+<!-- Brand-distinctive aesthetic -->
+<div className="bg-gradient-to-br from-brand-cream via-white to-brand-ocean/10">
+  <h1 className="font-heading text-6xl text-brand-midnight tracking-tighter">
+    Title
+  </h1>
+  <div className="relative overflow-hidden rounded-3xl bg-brand-coral p-8">
+    <!-- Atmospheric background -->
+    <div className="absolute inset-0 bg-gradient-to-br from-brand-coral to-brand-sunset opacity-80" />
+
+    <Button
+      :ui="{
+        font: 'font-heading',
+        rounded: 'rounded-full',
+        size: 'xl'
+      }"
+      className="relative z-10 transition-all duration-500 hover:scale-110 hover:rotate-2 hover:shadow-2xl active:scale-95"
+    >
+      <span className="flex items-center gap-2">
+        Action
+        <Icon
+          name="i-heroicons-sparkles"
+          className="animate-pulse"
+        />
+      </span>
+    </Button>
+  </div>
+</div>
+```
+
+**Strengths**:
+- Custom fonts (Archivo Black for headings)
+- Brand-specific colors (coral, ocean, sunset)
+- Atmospheric gradients (multiple layers)
+- Rich animations (scale, rotate, shadow transitions)
+- Heavily customized components (ui prop + utility classes)
+- Micro-interactions (icon pulse, hover effects)
+
+This SKILL ensures every Tanstack Start project develops a distinctive visual identity by preventing generic patterns and guiding developers toward branded, engaging design implementations.