benjaminshoemaker/ui-ux

UI/UX Design Intelligence

Unified UI/UX skill for analysis, research, and design guidance. Works in two modes:

• Audit mode (audit, review, improve, check) — Analyze existing UI code against craft principles, accessibility, and industry patterns. Produces prioritized recommendations.
• Design mode (design, build, create, plan) — Guide new UI creation with research-backed design direction, style selection, and implementation.

Both modes use product context, user research, and the design knowledge embedded below.

Acknowledgments

This skill incorporates ideas from three excellent sources. It bundles their key insights directly so no separate installs are needed. For the full experience, install the originals:

• design-principles by interface-design — Craft quality standards inspired by Linear, Notion, and Stripe. The design direction framework and depth/elevation strategies below are adapted from this skill.
• ui-ux-pro-max by nextlevelbuilder — Searchable design intelligence database with 50+ styles, 97 palettes, 57 font pairings. If installed, this skill can call its Python CLI for data-driven recommendations (see Phase 2a).
• frontend-design by Anthropic (Prithvi Rajasekaran, Alexander Bricken) — The anti-"AI slop" creative philosophy and spatial composition guidance below come from this official Claude Code plugin.

---

Phase 1: Context Gathering (ALWAYS DO THIS FIRST)

1a. Scan for Product Context

Read these files if they exist (stop once you have a clear picture):

PRODUCT_SPEC.md, FEATURE_SPEC.md, README.md, VISION.md,
AGENTS.md (look for design system references),
design-system/MASTER.md, design-system/tokens.*,
.cursorrules, .ai/*.md

Extract: product type, target users, core user jobs, emotional tone, industry.

1b. Scan for Existing Design System

Look for evidence of an established design system:

design-system/**, tailwind.config.*, theme.ts, theme.js,
**/tokens.css, **/variables.css, **/design-tokens.*,
components/ui/**, shadcn components (components.json)

Note: existing tokens, color palette, typography scale, spacing system, component library.

1c. Identify Tech Stack

Detect from package.json, config files, file extensions:

• Framework: React, Next.js, Vue, Nuxt, Svelte, Astro, etc.
• Styling: Tailwind, CSS Modules, styled-components, vanilla CSS
• Component library: shadcn/ui, Radix, MUI, Mantine, Headless UI
• Icons: Lucide, Phosphor, Heroicons

1d. Scan UI Code (Audit Mode)

For audit targets, read the relevant UI files. Look at:

• Component structure and composition patterns
• Color usage and consistency
• Spacing and layout patterns
• Typography choices
• Interactive states (hover, focus, disabled, loading, error)
• Responsive behavior
• Accessibility attributes (aria-*, alt, role, labels)

1e. Ask for Missing Context

If product context is thin (no specs, no README with product description), use AskUserQuestion:

"To give you the best UI/UX recommendations, I need some context:

1. What does this product do? Who uses it?
2. What's the emotional job? (Trust? Efficiency? Delight? Focus?)
3. Any design references or products you admire?

You can also point me at product docs or a live URL."

---

Phase 2: Research

2a. Design Intelligence Database (Optional Enhancement)

If ui-ux-pro-max is installed, use its Python CLI for data-driven recommendations. Check for the search script at these paths:

1. ~/.agents/skills/ui-ux-pro-max/scripts/search.py
2. ~/.claude/skills/ui-ux-pro-max/scripts/search.py

If found, generate a design system recommendation:

python3 <path>/search.py "<product_type> <industry> <keywords>" --design-system -p "Project Name"

Domain searches for deeper detail:

python3 <path>/search.py "<keywords>" --domain <domain>  # product, style, typography, color, landing, chart, ux, web
python3 <path>/search.py "<keywords>" --stack <stack>     # html-tailwind, react, nextjs, vue, svelte, shadcn, etc.

Persist design system for future sessions:

python3 <path>/search.py "<keywords>" --design-system --persist -p "Project Name" [--page "dashboard"]

If not installed, skip this step — the inline knowledge and web research below are sufficient. Note the availability to the user at the end: "For richer style/palette recommendations, install ui-ux-pro-max by nextlevelbuilder."

2b. Industry & Competitor Research

Use WebSearch to find relevant patterns for the specific product type and user base:

Search: "[product type] UI design patterns 2025 2026"
Search: "[industry] dashboard UX best practices"
Search: "[competitor names] design system"
Search: "best [product type] interfaces examples"

Focus on:

• What interaction patterns do leading products in this space use?
• What are the common UX pitfalls in this product category?
• What accessibility concerns are specific to this product type?
• What recent design trends are relevant (not just trendy)?

2c. Framework-Specific Research

If the stack warrants it, search for current best practices:

Search: "[framework] [component type] accessibility patterns"
Search: "Tailwind v4 @theme design tokens" (if using Tailwind)
Search: "shadcn/ui [component] best practices" (if using shadcn)

---

Phase 3: Design Direction

Adapted from design-principles by interface-design.

Before writing any code, commit to a design direction. Don't default. Think about what this specific product needs to feel like.

Context Questions

• What does this product do? A finance tool needs different energy than a creative tool.
• Who uses it? Power users want density. Occasional users want guidance.
• What's the emotional job? Trust? Efficiency? Delight? Focus?
• What would make this memorable? Every product has a chance to feel distinctive.

Choose a Personality

| Personality | Characteristics | Best For | |-------------|----------------|----------| | Precision & Density | Tight spacing, monochrome, information-forward | Power user tools (Linear, Raycast, terminals) | | Warmth & Approachability | Generous spacing, soft shadows, friendly colors | Collaborative tools (Notion, Coda) | | Sophistication & Trust | Cool tones, layered depth, financial gravitas | Finance, sensitive data (Stripe, Mercury) | | Boldness & Clarity | High contrast, dramatic negative space, confident type | Modern dashboards (Vercel) | | Utility & Function | Muted palette, functional density, clear hierarchy | Developer tools (GitHub) | | Data & Analysis | Chart-optimized, technical but accessible | Analytics, BI tools | | Bold Creative | Unexpected layouts, distinctive type, atmospheric depth | Marketing, creative tools, portfolios |

Pick one. Or blend two. But commit to a direction that fits the product.

Choose a Color Foundation

Don't default to warm neutrals. Consider the product:

• Warm foundations (creams, warm grays) — approachable, comfortable, human
• Cool foundations (slate, blue-gray) — professional, trustworthy, serious
• Pure neutrals (true grays, black/white) — minimal, bold, technical
• Tinted foundations (slight color cast) — distinctive, memorable, branded

Light or dark? Dark feels technical, focused, premium. Light feels open, approachable, clean. Choose based on context. Pick ONE accent color that means something.

Choose Typography

• System fonts — fast, native, invisible (utility-focused products)
• Geometric sans (Geist, Inter) — modern, clean, technical
• Humanist sans (SF Pro, Satoshi) — warmer, more approachable
• Monospace influence — technical, developer-focused, data-heavy
• Distinctive display — bold creative products deserve unexpected, characterful choices

Creative Direction

Adapted from frontend-design by Anthropic.

For every project, push beyond safe defaults. Ask: what makes this UNFORGETTABLE?

• Commit to a clear conceptual direction and execute with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
• Avoid generic AI aesthetics: overused fonts (Inter everywhere, Space Grotesk everywhere), purple-gradient-on-white, predictable layouts, cookie-cutter components. No design should be the same. Vary themes, fonts, and aesthetics across projects.
• Spatial composition: Consider unexpected layouts, asymmetry, overlap, diagonal flow, grid-breaking elements, generous negative space OR controlled density.
• Backgrounds & atmosphere: Create depth rather than defaulting to solid colors. Use gradient meshes, noise textures, geometric patterns, layered transparencies, grain overlays — whatever fits the aesthetic direction.
• Motion with purpose: Focus on high-impact moments — one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
• Match complexity to vision: Maximalist designs need elaborate code. Minimalist designs need restraint, precision, and careful attention to subtle details.

---

Phase 4: Craft Principles (Quality Floor)

Adapted from design-principles by interface-design.

Apply these regardless of design direction — they are the minimum quality bar. Covers: 4px spacing grid, depth/elevation strategy (pick one: borders-only, single shadows, layered shadows, or surface color shifts), typography hierarchy, contrast levels, card/surface consistency, custom controls, navigation context, dark mode rules, and anti-patterns to avoid.

See references/craft-principles.md for the full principles with CSS examples and detailed guidance.

---

Phase 5: Accessibility & Interaction Quality

Enforce WCAG AA standards (4.5:1 contrast, 44px touch targets, keyboard navigation, semantic HTML, focus rings, prefers-reduced-motion). Audit interaction quality: cursor states, hover feedback, transitions (150-300ms), loading states, error feedback. Check light/dark mode contrast for text, borders, and glass elements.

See references/accessibility.md for the full requirements tables and do/don't guidance.

---

Phase 6: Deliver Recommendations

Audit Mode Output

Structure findings as a prioritized report:

# UI/UX Audit: [Product Name]

## Context
- Product type: ...
- Target users: ...
- Design direction: [recommended personality]
- Tech stack: ...

## Design System Status
- [EXISTS/PARTIAL/MISSING] — [details]

## Findings

### Critical (Fix Immediately)
[Accessibility, broken interactions, contrast failures]

### High Priority (Fix Soon)
[Layout inconsistencies, missing states, responsive issues]

### Medium Priority (Improve)
[Typography, spacing, animation opportunities]

### Suggestions (Consider)
[Design direction refinement, creative enhancements, industry patterns]

## Research Insights
[Patterns from industry research specific to this product type]

## Design System Recommendations
[What to establish for consistent future work — see Phase 7]

## Implementation Plan
[Ordered changes, grouped by file/component]

Design Mode Output

For new UI work, provide:

1. Design direction — Personality, color foundation, typography, depth strategy
2. Research findings — Industry patterns and relevant references
3. Implementation guidance — Component structure, token setup, responsive strategy
4. Creative direction — What makes this design distinctive and memorable
5. Pre-delivery checklist — Quality gates before shipping

---

Phase 7: Establish Best Practices (ALWAYS INCLUDE)

After every audit or design session, include a "Future-Proofing" section with relevant recommendations. Don't include all — pick what's most impactful for this project's state.

Design System Setup

If the project lacks a design system, recommend creating one. This includes design tokens (CSS @theme or tokens.css), a design-system/MASTER.md doc, and page-specific overrides. Use AI-readable token metadata (DTCG format with when_to_use/avoid_when) for maximum AI effectiveness.

See references/design-tokens.md for token templates, CSS examples, component patterns, and modern CSS techniques.

AGENTS.md Integration

Recommend adding a Design System section to the project's AGENTS.md to document the chosen personality, tokens location, component library, icon set, and key constraints.

See references/agents-template.md for the template.

---

Pre-Delivery Checklist

Visual Quality

• [ ] Consistent spacing on 4px grid
• [ ] Typography hierarchy is clear and consistent
• [ ] Color usage is disciplined (accent earns its place)
• [ ] Depth strategy is consistent throughout
• [ ] No emojis as icons — using consistent SVG icon set
• [ ] Hover states don't cause layout shift
• [ ] Design feels intentional and distinctive, not generic

Interaction

• [ ] All clickable elements have cursor-pointer
• [ ] Hover, focus, active, disabled states all defined
• [ ] Transitions smooth (150-300ms)
• [ ] Loading states for async operations

Accessibility

• [ ] Color contrast 4.5:1+ (all text/background combinations)
• [ ] All images have alt text
• [ ] All form inputs have labels
• [ ] Keyboard navigation works (tab order, enter/space to activate)
• [ ] Focus rings visible
• [ ] prefers-reduced-motion respected
• [ ] Touch targets 44x44px minimum

Responsive

• [ ] Works at 375px, 768px, 1024px, 1440px
• [ ] No horizontal scroll on mobile
• [ ] Content readable at all breakpoints

Light/Dark Mode (if applicable)

• [ ] Text contrast sufficient in both modes
• [ ] Borders visible in both modes
• [ ] Semantic colors adjusted for dark backgrounds
• [ ] Glass/transparent elements visible in light mode