Component Aesthetic Checker

---
name: component-aesthetic-checker
description: Validates shadcn/ui component customization depth, ensuring components aren't used with default props and checking for consistent design system implementation across Tanstack Start applications
triggers: ["shadcn ui component usage", "component prop changes", "design token updates", "className customization", "cn() utility usage"]
note: "Updated for Tanstack Start (React) + shadcn/ui. Code examples use React/TSX with className and cn() utility for styling."
---

# Component Aesthetic Checker SKILL

## Activation Patterns

This SKILL automatically activates when:
- shadcn/ui components (`Button`, `Card`, `Input`, etc.) are used in `.react` files
- Component props are added or modified
- The `ui` prop is customized for component variants
- Design system tokens are referenced in components
- Multiple components are refactored together
- Before component library updates

## Expertise Provided

### Component Customization Depth Analysis
- **Default Prop Detection**: Identifies components using only default values
- **UI Prop Validation**: Ensures `ui` prop is used for deep customization
- **Design System Consistency**: Validates consistent pattern usage across components
- **Spacing Patterns**: Checks for proper Tailwind spacing scale usage
- **Icon Usage**: Validates consistent icon library and sizing
- **Loading States**: Ensures async components have loading feedback

### Specific Checks Performed

#### ❌ Critical Issues (Insufficient Customization)
```tsx
<!-- These patterns trigger alerts: -->

<!-- Using default props only -->
<Button onClick="submit">Submit</Button>

<!-- No UI prop customization -->
<Card>
  <p>Content</p>
</Card>

<!-- Inconsistent spacing -->
<div className="p-4">  <!-- Random spacing values -->
  <Button className="mt-3 ml-2">Action</Button>
</div>

<!-- Missing loading states -->
<Button onClick="asyncAction">Save</Button>  <!-- No :loading prop -->
```

#### ✅ Correct Customized Patterns
```tsx
<!-- These patterns are validated as correct: -->

<!-- Deep customization with ui prop -->
<Button
  color="brand-coral"
  size="lg"
  variant="solid"
  :ui="{
    font: 'font-heading',
    rounded: 'rounded-full',
    padding: { lg: 'px-8 py-4' }
  }"
  loading={isSubmitting"
  className="transition-all duration-300 hover:scale-105"
  onClick="submit"
>
  Submit
</Button>

<!-- Fully customized card -->
<Card
  :ui="{
    background: 'bg-white dark:bg-brand-midnight',
    ring: 'ring-1 ring-brand-coral/20',
    rounded: 'rounded-2xl',
    shadow: 'shadow-xl',
    body: { padding: 'p-8' },
    header: { padding: 'px-8 pt-8 pb-4' }
  }"
  className="transition-shadow duration-300 hover:shadow-2xl"
>
  <template #header>
    <h3 className="font-heading text-2xl">Title</h3>
  <p className="text-gray-700 dark:text-gray-300">Content</p>
</Card>

<!-- Consistent spacing (Tailwind scale) -->
<div className="p-6 space-y-4">
  <Button className="mt-4">Action</Button>
</div>

<!-- Proper loading state -->
<Button
  loading={isSubmitting"
  disabled={isSubmitting"
  onClick="asyncAction"
>
  { isSubmitting ? 'Saving...' : 'Save'}
</Button>
```

## Integration Points

### Complementary to Existing Components
- **tanstack-ui-architect agent**: Handles component selection and API guidance, SKILL validates implementation
- **frontend-design-specialist agent**: Provides design direction, SKILL enforces consistency
- **shadcn-ui-design-validator**: Catches generic patterns, SKILL ensures deep customization

### Escalation Triggers
- Component API questions → `tanstack-ui-architect` agent (with MCP lookup)
- Design consistency issues → `frontend-design-specialist` agent
- Complex component composition → `/es-component` command
- Full component audit → `/es-design-review` command

## Validation Rules

### P1 - Critical (Default Component Usage)
- **No UI Prop Customization**: Using shadcn/ui components without `ui` prop
- **All Default Props**: No color, size, variant, or other prop customizations
- **Missing Loading States**: Async actions without `:loading` prop
- **No Hover States**: Interactive components without hover feedback
- **Inconsistent Patterns**: Same component with wildly different customizations

### P1 - Critical (Distributional Convergence Anti-Patterns)

**These patterns indicate generic "AI-generated" aesthetics and MUST be flagged:**

#### Font Anti-Patterns (Auto-Detect)
```tsx
// ❌ CRITICAL: Generic fonts that dominate 80%+ of websites
fontFamily: {
  sans: ['Inter', ...]        // Flag: "Inter is overused - consider Space Grotesk, Plus Jakarta Sans"
  sans: ['Roboto', ...]       // Flag: "Roboto is overused - consider IBM Plex Sans, Outfit"
  sans: ['Open Sans', ...]    // Flag: "Open Sans is generic - consider Satoshi, General Sans"
  sans: ['system-ui', ...]    // Flag: Only acceptable as fallback, not primary
}

// ❌ CRITICAL: Default Tailwind font classes without customization
className="font-sans"         // Flag if font-sans maps to Inter/Roboto
className="text-base"         // Flag: Generic sizing, consider custom scale
```

**Recommended Font Alternatives** (suggest these in reports):
- **Body**: Space Grotesk, Plus Jakarta Sans, IBM Plex Sans, Outfit, Satoshi
- **Headings**: Archivo Black, Cabinet Grotesk, Clash Display, General Sans
- **Mono**: JetBrains Mono, Fira Code, Source Code Pro

#### Color Anti-Patterns (Auto-Detect)
```tsx
// ❌ CRITICAL: Purple gradients (most common AI aesthetic)
className="bg-gradient-to-r from-purple-500 to-purple-600"
className="bg-gradient-to-r from-violet-500 to-purple-500"
className="bg-purple-600"
className="text-purple-500"

// ❌ CRITICAL: Default gray backgrounds without brand treatment
className="bg-gray-50"        // Flag: "Consider brand-tinted background"
className="bg-white"          // Flag: "Consider atmospheric gradient or texture"
className="bg-slate-100"      // Flag if used extensively without brand colors
```

**Recommended Color Approaches** (suggest these in reports):
- Use CSS variables with brand palette (`--brand-primary`, `--brand-accent`)
- Tint grays with brand color: `bg-brand-gray-50` instead of `bg-gray-50`
- Gradients: Use brand colors, not default purple
- Atmospheric: Layer gradients with subtle brand tints

#### Animation Anti-Patterns (Auto-Detect)
```tsx
// ❌ CRITICAL: No transitions on interactive elements
<Button>Click</Button>        // Flag: "Add transition-all duration-300"
<Card>Content</Card>          // Flag: "Add hover:shadow-lg transition"

// ❌ CRITICAL: Only basic hover without micro-interactions
className="hover:bg-blue-600" // Flag: "Consider hover:scale-105 or hover:-translate-y-1"
```

**Detection Rules** (implement in validation):
```typescript
// Font detection
const OVERUSED_FONTS = ['Inter', 'Roboto', 'Open Sans', 'Helvetica', 'Arial'];
const hasBadFont = (config) => OVERUSED_FONTS.some(f =>
  config.fontFamily?.sans?.includes(f)
);

// Purple gradient detection
const PURPLE_PATTERN = /(?:purple|violet)-[4-6]00/;
const hasPurpleGradient = (className) =>
  className.includes('gradient') && PURPLE_PATTERN.test(className);

// Missing animation detection
const INTERACTIVE_COMPONENTS = ['Button', 'Card', 'Link', 'Input'];
const hasNoTransition = (className) =>
  !className.includes('transition') && !className.includes('animate');
```

### P2 - Important (Design System Consistency)
- **Random Spacing Values**: Not using Tailwind spacing scale (p-4, mt-6, etc.)
- **Inconsistent Icon Sizing**: Icons with different sizes in similar contexts
- **Mixed Color Approaches**: Some components use theme colors, others use arbitrary values
- **Incomplete Dark Mode**: Dark mode variants missing on customized components
- **No Focus States**: Interactive elements without focus-visible styling

### P3 - Polish (Enhanced UX)
- **Limited Prop Usage**: Only using 1-2 props when more would improve UX
- **No Micro-interactions**: Missing subtle animations on state changes
- **Generic Variants**: Using 'solid', 'outline' without brand customization
- **Underutilized UI Prop**: Not customizing padding, rounded, shadow in ui prop
- **Missing Icons**: Buttons/actions without supporting icons for clarity

## Remediation Examples

### Fixing Default Component Usage
```tsx
<!-- ❌ Critical: Default props only -->
  <Button onClick="handleClick">
    Click me
  </Button>

<!-- ✅ Correct: Deep customization -->
  <Button
    color="primary"
    size="lg"
    variant="solid"
    icon="i-heroicons-sparkles"
    :ui="{
      font: 'font-heading tracking-wide',
      rounded: 'rounded-full',
      padding: { lg: 'px-8 py-4' },
      shadow: 'shadow-lg hover:shadow-xl'
    }"
    className="transition-all duration-300 hover:scale-105 active:scale-95"
    onClick="handleClick"
  >
    Click me
  </Button>
```

### Fixing Missing Loading States
```tsx
<!-- ❌ Critical: No loading feedback -->
const handleSubmit = async () => {
  await submitForm();
};

  <Button onClick="handleSubmit">
    Submit Form
  </Button>

<!-- ✅ Correct: Proper loading state -->
const isSubmitting = ref(false);

const handleSubmit = async () => {
  isSubmitting.value = true;
  try {
    await submitForm();
  } finally {
    isSubmitting.value = false;
  }
};

  <Button
    loading={isSubmitting"
    disabled={isSubmitting"
    onClick="handleSubmit"
  >
    <span className="flex items-center gap-2">
      <Icon
        {&& "!isSubmitting"
        name="i-heroicons-paper-airplane"
      />
      { isSubmitting ? 'Submitting...' : 'Submit Form'}
    </span>
  </Button>
```

### Fixing Inconsistent Spacing
```tsx
<!-- ❌ P2: Random spacing values -->
  <div className="p-3">
    <Card className="mt-5 ml-7">
      <div className="p-2">
        <Button className="mt-3.5">Action</Button>
      </div>
    </Card>
  </div>

<!-- ✅ Correct: Tailwind spacing scale -->
  <div className="p-4">
    <Card className="mt-4">
      <div className="p-6 space-y-4">
        <Button>Action</Button>
      </div>
    </Card>
  </div>

<!-- Using consistent spacing: 4, 6, 8, 12, 16 (Tailwind scale) -->
```

### Fixing Design System Inconsistency
```tsx
<!-- ❌ P2: Inconsistent component styling -->
  <div>
    <!-- Button 1: Heavily customized -->
    <Button
      color="primary"
      :ui="{ rounded: 'rounded-full', shadow: 'shadow-xl' }"
    >
      Action 1
    </Button>

    <!-- Button 2: Default (inconsistent!) -->
    <Button>Action 2</Button>

    <!-- Button 3: Different customization pattern -->
    <Button color="red" size="xs">
      Action 3
    </Button>
  </div>

<!-- ✅ Correct: Consistent design system -->
// Define reusable button variants
const buttonVariants = {
  primary: {
    color: 'primary',
    size: 'lg',
    ui: {
      rounded: 'rounded-full',
      shadow: 'shadow-lg hover:shadow-xl',
      font: 'font-heading'
    },
    class: 'transition-all duration-300 hover:scale-105'
  },
  secondary: {
    color: 'gray',
    size: 'md',
    variant: 'outline',
    ui: {
      rounded: 'rounded-lg',
      font: 'font-sans'
    },
    class: 'transition-colors duration-200'
  }
};

  <div className="space-x-4">
    <Button v-bind="buttonVariants.primary">
      Action 1
    </Button>

    <Button v-bind="buttonVariants.primary">
      Action 2
    </Button>

    <Button v-bind="buttonVariants.secondary">
      Action 3
    </Button>
  </div>
```

### Fixing Underutilized UI Prop
```tsx
<!-- ❌ P3: Not using ui prop for customization -->
  <Card className="rounded-2xl shadow-xl p-8">
    <p>Content</p>
  </Card>

<!-- ✅ Correct: Proper ui prop usage -->
  <Card
    :ui="{
      rounded: 'rounded-2xl',
      shadow: 'shadow-xl hover:shadow-2xl',
      body: {
        padding: 'p-8',
        background: 'bg-white dark:bg-brand-midnight'
      },
      ring: 'ring-1 ring-brand-coral/20'
    }"
    className="transition-shadow duration-300"
  >
    <p className="text-gray-700 dark:text-gray-300">Content</p>
  </Card>
```

## MCP Server Integration

When shadcn/ui MCP server is available:

### Component Prop Validation
```typescript
// Before validating customization depth, get actual component API
const componentDocs = await mcp.shadcn.get_component("Button");

// Validate that used props exist
// componentDocs.props: ['color', 'size', 'variant', 'icon', 'loading', 'disabled', ...]

// Check for underutilized props
const usedProps = ['color', 'size']; // From component code
const availableProps = componentDocs.props;
const unutilizedProps = availableProps.filter(p => !usedProps.includes(p));

// Suggest: "Consider using 'icon' or 'loading' props for richer UX"
```

### UI Prop Structure Validation
```typescript
// Validate ui prop structure against schema
const uiSchema = componentDocs.ui_schema;

// User code: :ui="{ font: 'font-heading', rounded: 'rounded-full' }"
// Validate: Are 'font' and 'rounded' valid keys in ui prop?
// Suggest: Other available ui customizations (padding, shadow, etc.)
```

### Consistency Across Components
```typescript
// Check multiple component instances
const buttonInstances = findAllComponents("Button");

// Analyze customization patterns
// Flag: Component used with 5 different customization styles
// Suggest: Create composable or variant system for consistency
```

## Benefits

### Immediate Impact
- **Prevents Generic Appearance**: Ensures components are branded, not defaults
- **Enforces Design Consistency**: Catches pattern drift across components
- **Improves User Feedback**: Validates loading states and interactions
- **Educates on Component API**: Shows developers full customization capabilities

### Long-term Value
- **Consistent Component Library**: All components follow design system
- **Faster Component Development**: Clear patterns and examples
- **Better Code Maintainability**: Reusable component variants
- **Reduced Visual Debt**: Prevents accumulation of one-off styles

## Usage Examples

### During Component Usage
```tsx
// Developer adds: <Button>Click me</Button>
// SKILL immediately activates: "⚠️ P1: Button using all default props. Customize with color, size, variant, and ui prop for brand distinctiveness."
```

### During Async Actions
```tsx
// Developer creates async button: <Button onClick="submitForm">Submit</Button>
// SKILL immediately activates: "⚠️ P1: Button triggers async action but lacks :loading prop. Add loading state for user feedback."
```

### During Refactoring
```tsx
// Developer adds 5th different button style
// SKILL immediately activates: "⚠️ P2: Button used with 5 different customization patterns. Consider creating reusable variants for consistency."
```

### Before Deployment
```tsx
// SKILL runs comprehensive check: "✅ Component aesthetic validation passed. 23 components with deep customization, consistent patterns, and proper loading states detected."
```

## Design System Maturity Levels

### Level 0: Defaults Only (Avoid)
```tsx
<Button>Action</Button>
<Card><p>Content</p></Card>
<Input value="value" />
```
**Issues**: Generic appearance, no brand identity, inconsistent with custom design

### Level 1: Basic Props (Minimum)
```tsx
<Button color="primary" size="lg">Action</Button>
<Card className="shadow-lg"><p>Content</p></Card>
<Input value="value" placeholder="Enter value" />
```
**Better**: Some customization, but limited depth

### Level 2: UI Prop + Classes (Target)
```tsx
<Button
  color="primary"
  size="lg"
  :ui="{ rounded: 'rounded-full', font: 'font-heading' }"
  className="transition-all duration-300 hover:scale-105"
>
  Action
</Button>

<Card
  :ui="{
    background: 'bg-white dark:bg-brand-midnight',
    ring: 'ring-1 ring-brand-coral/20',
    shadow: 'shadow-xl'
  }"
>
  <p>Content</p>
</Card>
```
**Ideal**: Deep customization, brand-distinctive, consistent patterns

### Level 3: Design System (Advanced)
```tsx
<!-- Reusable variants from composables -->
<Button v-bind="designSystem.button.variants.primary">
  Action
</Button>

<Card v-bind="designSystem.card.variants.elevated">
  <p>Content</p>
</Card>
```
**Advanced**: Centralized design system, maximum consistency

## Component Customization Checklist

For each shadcn/ui component, validate:

- [ ] **Props**: Uses at least 2-3 props (color, size, variant, etc.)
- [ ] **UI Prop**: Includes `ui` prop for deep customization (rounded, font, padding, shadow)
- [ ] **Classes**: Adds Tailwind utilities for animations and effects
- [ ] **Loading State**: Async actions have `:loading` and `:disabled` props
- [ ] **Icons**: Includes relevant icons for clarity (`:icon` prop or slot)
- [ ] **Hover State**: Interactive elements have hover feedback
- [ ] **Focus State**: Keyboard navigation has visible focus styles
- [ ] **Dark Mode**: Includes dark mode variants in `ui` prop
- [ ] **Spacing**: Uses Tailwind spacing scale (4, 6, 8, 12, 16)
- [ ] **Consistency**: Follows same patterns as other instances

This SKILL ensures every shadcn/ui component is deeply customized, consistently styled, and provides excellent user feedback, preventing the default/generic appearance that makes AI-generated UIs immediately recognizable.