design

If the current repo has its own rules/skills covering this topic (check .claude/rules/ and repo CLAUDE.md), those take precedence — apply this skill only where they're silent.

Design Principles

Core philosophy: Every interface should look designed by a team that obsesses over 1-pixel differences. Not stripped, crafted. And designed for its specific context.

Avoid AI Sameness

AI-generated UIs have a recognizable "median of the internet" feel. Polished but generic, like everything was designed by the same committee. Break out of that by making deliberate choices instead of reaching for defaults.

AI default patterns to actively avoid:

AI default	Why it happens	Do this instead
Indigo/purple gradients	Tailwind's bg-indigo-500 saturated training data	Choose an accent color that fits the product's emotional job
Inter or system fonts everywhere	Statistically safest choice	Pick typography that matches the product personality (see Choose Typography below)
Three-column icon grid	Every SaaS landing page template uses this	Vary card layouts by content type. Metric cards, feature cards, and testimonial cards should look different from each other
Centered hero + CTA button	The default starting point for every landing page	Consider what the user actually needs first. Maybe it's a dense dashboard, a split layout, or content-forward with no hero at all
Uniform border-radius on everything	rounded-lg applied without thinking	Pick a radius system and vary it by component role (sharp for data, softer for interactive)
White/light gray background + subtle shadow cards	The safest possible surface treatment	Commit to a depth strategy that matches the product (see Depth Strategy below)
Decorative gradients on hero sections	Looks "modern" without communicating anything	If using gradients, make them functional (show hierarchy, direct attention) not decorative

The test: If you swapped your brand name with a competitor's and the design still works, it's too generic. Something about the color foundation, typography, spacing rhythm, or layout density should feel specific to this product.

Controlled imperfection creates character. Perfect symmetry and uniform spacing everywhere reads as machine-generated. Human-designed interfaces have intentional asymmetry: a sidebar slightly narrower than expected, a headline that breaks the grid for emphasis, whitespace that breathes unevenly to create visual rhythm. These are deliberate choices, not sloppiness.

Design Direction (REQUIRED)

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

Think About Context

• 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

Direction	Feel	When to Use
Precision & Density	Tight spacing, monochrome, info-forward	Power users who live in the tool. Linear, Raycast, terminal aesthetics.
Warmth & Approachability	Generous spacing, soft shadows, friendly	Products that want to feel human. Notion, Coda, collaborative tools.
Sophistication & Trust	Cool tones, layered depth, gravitas	Products handling money or sensitive data. Stripe, Mercury.
Boldness & Clarity	High contrast, dramatic negative space	Modern, decisive products. Vercel, minimal dashboards.
Utility & Function	Muted palette, functional density	Work matters more than chrome. GitHub, developer tools.
Data & Analysis	Chart-optimized, technical but accessible	Analytics, metrics, business intelligence.

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

Choose Foundation

Color foundation (don't default to warm):

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

Light or dark? Dark feels technical, focused, premium. Light feels open, approachable, clean. Choose based on context.

Accent color: ONE that means something. Blue = trust. Green = growth. Orange = energy. Violet = creativity.

Choose Layout

• Dense grids for information-heavy interfaces where users scan and compare
• Generous spacing for focused tasks where users need to concentrate
• Sidebar nav for multi-section apps with many destinations
• Top nav for simpler tools with fewer sections

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

Card Layouts

Internal layouts should vary by content. A metric card doesn't have to look like a plan card doesn't have to look like a settings card. One might have a sparkline, another an avatar stack, another a progress ring.

Surface treatment stays consistent: same border weight, shadow depth, corner radius, padding scale.

Isolated Controls

Never use native form elements for styled UI. Native <select>, <input type="date"> render OS-native elements that cannot be styled. Build custom components.

Custom select triggers: display: inline-flex with white-space: nowrap to keep text and icons on same row.

Navigation Context

Screens need grounding:

• Navigation (sidebar or top)
• Location indicator (breadcrumbs, active state)
• User context (who's logged in)

When building sidebars, consider using same background as main content. Linear, Vercel use subtle border for separation rather than different backgrounds.

Dark Mode

• Borders over shadows: Shadows less visible on dark backgrounds
• Adjust semantic colors: Desaturate for dark backgrounds
• Same hierarchy, inverted values

Anti-Patterns

Never:

• Dramatic drop shadows (0 25px 50px...)
• Large radius (16px+) on small elements
• Asymmetric padding without reason
• Pure white cards on colored backgrounds
• Thick borders (2px+) for decoration
• Spring/bouncy animations
• Multiple accent colors
• Motion without purpose

The Standard

Different products want different things. A dev tool wants precision and density. A collaborative product wants warmth and space. A financial product wants trust and sophistication.

Same quality bar, context-driven execution.

Implementation

Detect which styling approach the project uses, then load the matching reference:

Project uses	Load
Vanilla CSS, CSS Modules, styled-components, or no Tailwind	references/craft-css.md
Tailwind CSS	references/craft-tailwind.md

If unclear, check for tailwind.config or @tailwind directives in the project. Default to CSS if neither is found.