shadcn-ui-design-validator

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)

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

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

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

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

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

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

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

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

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

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

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

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

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