Skills
skills/vinceh/recipe/ui-creator

ui-creator

Installation
SKILL.md

UI Creator

Overview

To create high-quality user interfaces, combine visual design principles with practical implementation and objective evaluation. This skill provides comprehensive guidance for creating new UIs from descriptions, analyzing and improving existing interfaces, A/B testing variations, and building accessible component libraries. Uniquely integrates Playwright automation to objectively evaluate UI quality through accessibility audits, performance metrics, and visual regression testing.

Current Standards (2025):

  • Design: WCAG 2.2 Level AA accessibility
  • Frameworks: React 18+, Vue 3.5+
  • Testing: Playwright 1.48+, axe-core
  • Styling: Tailwind CSS, CSS Modules, Styled Components
  • Performance: Core Web Vitals (LCP < 2.5s, CLS < 0.1, FID < 100ms)

Decision Tree: Choosing Your Workflow

User Request → What is the goal?
    |
    ├─ Creating new UI from description?
    │   ├─ Simple component? → Quick Start: Component Creation
    │   └─ Full page/app? → Workflow 1: Full UI Creation
    │
    ├─ Analyzing existing UI?
    │   └─ Use Workflow 2: UI Analysis & Evaluation
    │       └─ Run scripts/evaluate-ui.ts for objective metrics
    │
    ├─ Improving existing UI?
    │   └─ Use Workflow 3: UI Improvement
    │       ├─ Load references/anti-patterns.md (common mistakes)
    │       ├─ Load references/accessibility-guidelines.md (a11y issues)
    │       └─ Load references/ui-design-principles.md (design improvements)
    │
    ├─ Comparing UI variations (A/B testing)?
    │   └─ Use Workflow 4: A/B Testing Comparison
    │       └─ Run scripts/compare-variations.ts for side-by-side analysis
    │
    ├─ Building component library?
    │   └─ Use Workflow 5: Component Library Creation
    │       ├─ Use assets/component-templates/ as starting point
    │       ├─ Use assets/design-tokens.json for consistency
    │       └─ Run scripts/init-component.ts to scaffold components
    │
    ├─ Need design system guidance?
    │   └─ Load references/ui-design-principles.md
    │
    ├─ Need accessibility help?
    │   └─ Load references/accessibility-guidelines.md
    │
    └─ Need component patterns?
        └─ Load references/component-patterns.md

Quick Start: Component Creation

Creating a Button Component

To create an accessible button component quickly:

import React from 'react';

interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({
  variant = 'primary',
  size = 'md',
  children,
  ...rest
}: ButtonProps) {
  return (
    <button
      className={`button button-${variant} button-${size}`}
      {...rest}
    >
      {children}
    </button>
  );
}

Use the component scaffolding script for complex components:

npx tsx scripts/init-component.ts button --type button --framework react

This generates a production-ready component with:

  • Full TypeScript types
  • Accessibility features (ARIA, keyboard support)
  • Multiple variants and states
  • Test file
  • Documentation

Evaluating the Component

After creating the component, evaluate its quality:

npx tsx scripts/evaluate-ui.ts http://localhost:3000/components/button

This provides:

  • Accessibility score (WCAG 2.2 compliance)
  • Performance metrics (load time, responsiveness)
  • Screenshot for visual review
  • Detailed recommendations

Workflow 1: Full UI Creation

To create a complete UI from a description, follow this systematic approach.

Step 1: Understand Requirements

To begin UI creation:

  1. Clarify user needs: What problem does this UI solve?
  2. Identify user personas: Who will use this interface?
  3. Define success criteria: What makes this UI effective?
  4. List required components: Buttons, forms, navigation, etc.
  5. Determine constraints: Platform, browser support, performance budgets

Example conversation:

  • User: "Create a dashboard for tracking fitness goals"
  • Claude: "I'll create a fitness dashboard. A few questions:
    • What metrics should be displayed? (steps, calories, weight, etc.)
    • What's the primary action users should take?
    • Mobile-first or desktop-first design?
    • Any brand colors or design preferences?"

Step 2: Design the UI

To design the interface:

  1. Apply design principles:

    • Visual hierarchy (most important elements larger/bolder)
    • Consistent spacing (8-point grid: 8px, 16px, 24px, 32px)
    • Color psychology (blue for trust, green for success, red for errors)
    • Whitespace for breathing room
    • Load references/ui-design-principles.md for comprehensive guidance

  2. Ensure accessibility:

    • Sufficient color contrast (4.5:1 for text, 3:1 for UI elements)
    • Semantic HTML structure
    • Keyboard navigation support
    • Screen reader compatibility
    • Load references/accessibility-guidelines.md for WCAG 2.2 requirements

  3. Choose design tokens:

    • Use assets/design-tokens.json as a starting point
    • Define colors, spacing, typography, border radius, shadows
    • Maintain consistency across components

  4. Create visual mockup (optional):

    • Describe layout and visual design
    • Use design principles to guide decisions
    • Consider responsive breakpoints (mobile: 375px, tablet: 768px, desktop: 1280px)

Step 3: Implement the Code

To implement the UI:

  1. Choose framework:

    • React (most common, 2025): Component-based, hooks, TypeScript
    • Vue 3.5+: Composition API, <script setup> syntax

  2. Structure components:

    • Break UI into small, focused components
    • Use composition over configuration
    • Follow single responsibility principle
    • Load references/component-patterns.md for patterns

  3. Implement with accessibility:

    • Use semantic HTML (<button>, <nav>, <main>)
    • Add ARIA attributes where needed
    • Ensure keyboard navigation
    • Include focus indicators

  4. Style with consistency:

    • Use design tokens from Step 2
    • Choose styling approach (Tailwind, CSS Modules, Styled Components)
    • Apply consistent spacing and typography
    • Support dark mode (2025 expectation)

Example implementation:

// Dashboard.tsx
import { Card, CardHeader, CardBody } from '@/components/Card';
import { MetricCard } from '@/components/MetricCard';

export function FitnessDashboard() {
  return (
    <main className="max-w-7xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">Fitness Dashboard</h1>

      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        <MetricCard
          title="Steps Today"
          value="8,432"
          goal="10,000"
          icon={<StepsIcon />}
        />
        <MetricCard
          title="Calories Burned"
          value="420"
          goal="500"
          icon={<CaloriesIcon />}
        />
        <MetricCard
          title="Active Minutes"
          value="45"
          goal="60"
          icon={<TimeIcon />}
        />
      </div>
    </main>
  );
}

Step 4: Evaluate with Playwright

To objectively assess UI quality:

# Evaluate accessibility and performance
npx tsx scripts/evaluate-ui.ts http://localhost:3000/dashboard --a11y --performance --screenshot

# Results:
# - Accessibility: 0 violations (100% WCAG 2.2 AA compliant)
# - Performance: LCP 1.2s, CLS 0.02
# - Score: 95/100
# - Screenshots saved to ./ui-evaluation/

Load references/playwright-evaluation.md for detailed evaluation patterns.

Step 5: Iterate Based on Evaluation

To improve based on evaluation results:

  1. Fix accessibility violations: Address any WCAG failures
  2. Optimize performance: Reduce LCP, improve CLS
  3. Refine visual design: Adjust based on screenshots
  4. Re-evaluate: Run evaluation script again to verify improvements

Workflow 2: UI Analysis & Evaluation

To analyze an existing UI objectively:

Run Automated Evaluation

npx tsx scripts/evaluate-ui.ts https://example.com/page \
  --viewport 1920x1080 \
  --a11y \
  --performance \
  --screenshot \
  --output-dir ./analysis

This generates:

  • HTML report: Visual report with screenshots and metrics
  • JSON data: Structured evaluation data
  • Recommendations: Specific improvements needed

Interpret Results

To understand evaluation output:

Accessibility Violations:

  • Critical/Serious: Fix immediately (blocks some users)
  • Moderate: Fix soon (impacts user experience)
  • Minor: Fix when possible (best practice)

Performance Metrics:

  • TTFB (Time to First Byte): < 500ms good, < 200ms excellent
  • FCP (First Contentful Paint): < 1.8s good, < 1.0s excellent
  • LCP (Largest Contentful Paint): < 2.5s good, < 1.8s excellent
  • CLS (Cumulative Layout Shift): < 0.1 good, < 0.05 excellent

Overall Score:

  • 85-100: Excellent UI quality
  • 70-84: Good, room for improvement
  • 50-69: Fair, needs optimization
  • < 50: Poor, significant issues

Load references/playwright-evaluation.md for advanced evaluation techniques.

Workflow 3: UI Improvement

To improve an existing UI based on analysis:

Step 1: Identify Issues

From evaluation report, categorize issues:

  1. Accessibility issues: Load references/accessibility-guidelines.md
  2. Design problems: Load references/ui-design-principles.md
  3. Common mistakes: Load references/anti-patterns.md
  4. Performance issues: Review performance metrics

Step 2: Prioritize Improvements

Order by impact:

  1. Critical accessibility: Blocks users with disabilities
  2. Major performance: Slow load times (> 3s)
  3. Usability issues: Confusing navigation, unclear CTAs
  4. Visual polish: Inconsistent spacing, color contrast
  5. Nice-to-haves: Animations, micro-interactions

Step 3: Implement Fixes

Apply improvements systematically:

Accessibility fixes:

// Before: Missing alt text
<img src="chart.png" />

// After: Descriptive alt text
<img src="chart.png" alt="Sales chart showing 25% increase in Q4" />

Performance optimizations:

// Before: Eager loading all images
<img src="large-image.jpg" />

// After: Lazy loading with responsive images
<img
  src="large-image.jpg"
  srcSet="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
  loading="lazy"
  alt="Description"
/>

Design improvements:

/* Before: Poor contrast */
.text {
  color: #999999; /* Contrast ratio: 2.3:1 (fails WCAG) */
  background: #ffffff;
}

/* After: Sufficient contrast */
.text {
  color: #333333; /* Contrast ratio: 7.0:1 (passes AAA) */
  background: #ffffff;
}

Step 4: Verify Improvements

Re-run evaluation to confirm fixes:

npx tsx scripts/evaluate-ui.ts https://example.com/page --threshold 85

Exit code 0 if score >= 85, exit code 1 otherwise (useful for CI/CD).

Workflow 4: A/B Testing Comparison

To compare multiple UI variations objectively:

Create Variations

Implement design variations:

// Variation A: Traditional button
<button className="bg-blue-600 text-white px-6 py-3 rounded">
  Sign Up
</button>

// Variation B: Outline button
<button className="border-2 border-blue-600 text-blue-600 px-6 py-3 rounded">
  Sign Up
</button>

// Variation C: Gradient button
<button className="bg-gradient-to-r from-blue-600 to-purple-600 text-white px-6 py-3 rounded-lg">
  Sign Up
</button>

Run Comparison

npx tsx scripts/compare-variations.ts \
  https://example.com/signup?variant=a \
  https://example.com/signup?variant=b \
  https://example.com/signup?variant=c \
  --labels "Traditional,Outline,Gradient" \
  --viewport 1920x1080

Analyze Results

Comparison report shows:

  • Side-by-side screenshots: Visual comparison
  • Accessibility scores: Which variation is most accessible
  • Performance metrics: Which loads fastest
  • Overall winner: Highest combined score

Example output:

Variant A (Traditional): 90/100
Variant B (Outline): 88/100
Variant C (Gradient): 85/100 (slower FCP due to gradient rendering)

Winner: Variant A

Workflow 5: Component Library Creation

To build a reusable component library:

Step 1: Define Design System

Use assets/design-tokens.json as foundation:

  1. Colors: Primary, neutral, semantic (success, error, warning)
  2. Typography: Font families, sizes, weights, line heights
  3. Spacing: 8-point grid system
  4. Shadows: Elevation levels for depth
  5. Border radius: Consistent rounded corners
  6. Animation: Duration and easing curves

Step 2: Create Base Components

Start with foundational components:

# Generate button component
npx tsx scripts/init-component.ts button --type button --tests --stories

# Generate input component
npx tsx scripts/init-component.ts input --type input --tests --stories

# Generate card component
npx tsx scripts/init-component.ts card --type card --tests --stories

# Generate modal component
npx tsx scripts/init-component.ts modal --type modal --tests --stories

Or copy from assets/component-templates/ for reference.

Step 3: Build Composition

Create complex components from base components:

// Form built from Input, Button components
export function SignupForm() {
  return (
    <form>
      <Input
        label="Email"
        type="email"
        required
        helperText="We'll never share your email"
      />
      <Input
        label="Password"
        type="password"
        required
        helperText="Minimum 8 characters"
      />
      <Button variant="primary" type="submit">
        Create Account
      </Button>
    </form>
  );
}

Step 4: Test & Document

For each component:

  1. Write tests: Unit tests, accessibility tests
  2. Document props: JSDoc comments, TypeScript types
  3. Create examples: Storybook stories or example usage
  4. Evaluate quality: Run Playwright evaluation

Load references/component-patterns.md for advanced patterns.

Playwright Evaluation Integration

Playwright enables objective UI evaluation beyond manual review.

Key Evaluation Capabilities

Accessibility Auditing:

  • Automated WCAG 2.2 compliance testing with axe-core
  • Detects missing alt text, poor contrast, keyboard issues
  • Generates actionable violation reports

Visual Regression Testing:

  • Screenshot capture with masking for dynamic content
  • Pixel-perfect comparison for detecting unintended changes
  • Cross-browser consistency testing

Performance Measurement:

  • Core Web Vitals: LCP, CLS, FID
  • TTFB, FCP, page weight
  • Performance budgets enforcement

Responsive Testing:

  • Test across multiple viewport sizes
  • Validate mobile, tablet, desktop layouts
  • Screenshot comparison per breakpoint

Evaluation Scripts Usage

evaluate-ui.ts - Comprehensive UI evaluation:

npx tsx scripts/evaluate-ui.ts <url> [options]

Options:
  --viewport 1920x1080  # Desktop viewport
  --mobile             # Use mobile viewport (375x667)
  --a11y               # Run accessibility checks
  --performance        # Measure performance
  --screenshot         # Capture screenshots
  --threshold 85       # Minimum score (CI/CD)

compare-variations.ts - A/B testing comparison:

npx tsx scripts/compare-variations.ts <url-a> <url-b> [options]

Options:
  --labels "A,B,C"     # Custom labels
  --mobile             # Mobile comparison
  --viewport 1920x1080 # Custom viewport

init-component.ts - Component scaffolding:

npx tsx scripts/init-component.ts <name> [options]

Options:
  --type button|input|card|modal|dropdown|custom
  --framework react|vue
  --typescript true|false
  --tests true|false
  --stories true|false

Resources

This skill includes comprehensive reference materials, evaluation scripts, and component templates:

references/ui-design-principles.md

Modern UI design principles including color theory, typography, layout, spacing, visual hierarchy, and 2025 design trends (glassmorphism, minimalism, bold typography). Covers design tokens and component libraries.

Load when: Creating new UIs, making design decisions, choosing colors/fonts, implementing design systems, need visual design guidance.

references/accessibility-guidelines.md

Complete WCAG 2.2 accessibility guide covering semantic HTML, ARIA patterns, keyboard navigation, screen reader support, color contrast, and common component accessibility patterns. Includes testing strategies.

Load when: Ensuring accessibility compliance, fixing a11y violations, implementing accessible components, keyboard navigation issues, screen reader testing.

references/playwright-evaluation.md

Comprehensive guide to using Playwright for UI evaluation including visual regression testing, accessibility auditing with axe-core, performance measurement, responsive testing, and automated quality scoring.

Load when: Setting up evaluation workflows, understanding Playwright capabilities, writing visual tests, measuring performance, A/B testing comparisons.

references/component-patterns.md

Reusable component design patterns covering props design, composition patterns, styling approaches (Tailwind, CSS Modules, CSS-in-JS), common components (Button, Input, Modal, Card), and advanced patterns (compound components, render props).

Load when: Building component libraries, designing component APIs, implementing complex components, composition strategies, styling decisions.

references/anti-patterns.md

Common UI/UX mistakes to avoid including accessibility anti-patterns, design mistakes, form errors, performance issues, and mobile problems. Provides bad vs. good examples for 30+ anti-patterns.

Load when: Reviewing existing UIs, debugging issues, learning what to avoid, code review feedback, improving UI quality.

scripts/evaluate-ui.ts

Playwright script for comprehensive UI evaluation with accessibility audits (axe-core), performance metrics (LCP, CLS, FCP, TTFB), screenshot capture, and HTML/JSON report generation. Includes quality scoring system.

Use when: Evaluating UI quality objectively, measuring accessibility compliance, checking performance, generating evaluation reports, CI/CD quality gates.

scripts/compare-variations.ts

A/B testing comparison script for evaluating multiple UI variations side-by-side. Compares screenshots, accessibility scores, performance metrics. Generates visual comparison report with winner determination.

Use when: A/B testing designs, comparing UI iterations, choosing between design options, presenting options to stakeholders.

scripts/init-component.ts

Component scaffolding tool that generates production-ready React/Vue components with TypeScript, accessibility features, tests, and documentation. Supports multiple component types (button, input, card, modal, dropdown).

Use when: Creating new components quickly, scaffolding component boilerplate, ensuring accessibility from the start, maintaining consistency.

assets/component-templates/

Production-ready component templates (Button, Input) with full TypeScript types, accessibility features (ARIA, keyboard support), multiple variants, and comprehensive documentation.

Use when: Need reference implementations, building component libraries, learning component patterns, starting new components.

assets/design-tokens.json

Comprehensive design token system with colors (primary, neutral, semantic), spacing (8-point grid), typography (fonts, sizes, weights), shadows, border radius, animations, and breakpoints. JSON format compatible with design tools.

Use when: Setting up design system, maintaining consistency, defining brand tokens, integrating with design tools, theme creation.

Tips for Success

  1. Start with accessibility: Design inclusively from the beginning (easier than retrofitting)
  2. Use design tokens: Maintain consistency with centralized design values
  3. Evaluate objectively: Use Playwright scripts for data-driven decisions
  4. Mobile-first: Design for smallest screen, progressively enhance
  5. Test early and often: Run evaluations during development, not just at the end
  6. Learn from templates: Study assets/component-templates/ for best practices
  7. Avoid anti-patterns: Review references/anti-patterns.md before implementing
  8. Measure performance: Core Web Vitals matter for user experience and SEO
  9. Document decisions: Use design tokens and component JSDoc comments
  10. Iterate based on data: Let evaluation scores guide improvements

When to Load Reference Files

To optimize context usage, load reference files strategically:

  • Load ui-design-principles.md when:

    • Creating new UI designs
    • Choosing colors, typography, spacing
    • Need design system guidance
    • Making visual design decisions

  • Load accessibility-guidelines.md when:

    • Ensuring WCAG 2.2 compliance
    • Fixing accessibility violations
    • Implementing accessible components
    • Questions about ARIA or keyboard navigation

  • Load playwright-evaluation.md when:

    • Setting up UI evaluation
    • Understanding Playwright capabilities
    • Writing visual regression tests
    • Measuring performance metrics

  • Load component-patterns.md when:

    • Building component libraries
    • Designing component APIs
    • Implementing complex components
    • Composition or styling questions

  • Load anti-patterns.md when:

    • Reviewing existing code
    • Debugging UI issues
    • Learning what to avoid
    • Improving UI quality
Weekly Installs
2
Repository
vinceh/recipe
GitHub Stars
2
First Seen
Mar 13, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
amp2
cline2
opencode2
cursor2
kimi-cli2
codex2