From 8fb4019854491d5790983d1446cfff72031242b0 Mon Sep 17 00:00:00 2001 From: nniel-ape Date: Tue, 6 Jan 2026 18:50:31 +0300 Subject: [PATCH 1/3] refactor: rename skill from design-principles to frontend-design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename skill file to SKILL.md (uppercase convention) - Update skill name, description, and invocation command - Update installation paths and documentation - Improve prose consistency (contractions → formal style) - Clarify design direction sections with consistent formatting --- README.md | 28 ++++---- install.sh | 12 ++-- skill/{skill.md => SKILL.md} | 120 +++++++++++++++++++---------------- 3 files changed, 87 insertions(+), 73 deletions(-) rename skill/{skill.md => SKILL.md} (60%) diff --git a/README.md b/README.md index b2b80a1..0fb4e03 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Design Principles Skill for Claude Code +# Frontend Design Skill for Claude Code -A Claude Code skill that enforces precise, crafted design for enterprise software, SaaS dashboards, and admin interfaces. Inspired by Linear, Notion, Stripe, and Vercel. +A Claude Code skill that creates distinctive, production-grade frontend interfaces with high design quality. Inspired by Linear, Notion, Stripe, and Vercel. ## What It Does @@ -26,34 +26,34 @@ See the difference at **[dashboard-v4-eta.vercel.app](https://dashboard-v4-eta.v ### Quick Install (macOS/Linux) ```bash -mkdir -p ~/.claude/skills/design-principles -curl -o ~/.claude/skills/design-principles/skill.md \ - https://raw.githubusercontent.com/Dammyjay93/claude-design-skill/main/skill/skill.md +mkdir -p ~/.claude/skills/frontend-design +curl -o ~/.claude/skills/frontend-design/SKILL.md \ + https://raw.githubusercontent.com/Dammyjay93/claude-design-skill/main/skill/SKILL.md ``` ### Manual Install 1. Create the skill directory: ```bash - mkdir -p ~/.claude/skills/design-principles + mkdir -p ~/.claude/skills/frontend-design ``` -2. Copy `skill/skill.md` to `~/.claude/skills/design-principles/skill.md` +2. Copy `skill/SKILL.md` to `~/.claude/skills/frontend-design/SKILL.md` 3. Restart Claude Code ## Usage -The skill activates automatically when you ask Claude Code to build UI. You can also invoke it explicitly: +The skill activates automatically when building web components, pages, or applications. It can also be invoked explicitly: ``` -/design-principles +/frontend-design ``` -Or reference it in your prompt: +Or referenced in prompts: ``` -Build a dashboard for [your use case]. Use the design-principles skill. +Build a dashboard for [your use case]. Use the frontend-design skill. ``` ## Design Directions @@ -80,13 +80,13 @@ The skill supports multiple design personalities: ## File Structure ``` -~/.claude/skills/design-principles/ -└── skill.md # The skill definition +~/.claude/skills/frontend-design/ +└── SKILL.md # The skill definition ``` ## Customization -Fork this repo and modify `skill/skill.md` to match your design system. Key sections to customize: +Fork this repo and modify `skill/SKILL.md` to match your design system. Key sections to customize: - **Design Directions** — Add your own personality options - **Color Foundation** — Define your brand colors diff --git a/install.sh b/install.sh index cf9c748..4d6d03d 100755 --- a/install.sh +++ b/install.sh @@ -1,21 +1,21 @@ #!/bin/bash -# Design Principles Skill Installer for Claude Code +# Frontend Design Skill Installer for Claude Code set -e -SKILL_DIR="$HOME/.claude/skills/design-principles" +SKILL_DIR="$HOME/.claude/skills/frontend-design" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -echo "Installing Design Principles skill for Claude Code..." +echo "Installing Frontend Design skill for Claude Code..." # Create skill directory mkdir -p "$SKILL_DIR" # Copy skill file -cp "$SCRIPT_DIR/skill/skill.md" "$SKILL_DIR/skill.md" +cp "$SCRIPT_DIR/skill/SKILL.md" "$SKILL_DIR/SKILL.md" -echo "Installed to $SKILL_DIR/skill.md" +echo "Installed to $SKILL_DIR/SKILL.md" echo "" echo "Restart Claude Code to activate the skill." -echo "Usage: /design-principles or just ask Claude to build UI" +echo "Usage: /frontend-design or ask Claude to build UI" diff --git a/skill/skill.md b/skill/SKILL.md similarity index 60% rename from skill/skill.md rename to skill/SKILL.md index 0421bc3..cbb49cf 100644 --- a/skill/skill.md +++ b/skill/SKILL.md @@ -1,69 +1,71 @@ --- -name: design-principles -description: Enforce a precise, minimal design system inspired by Linear, Notion, and Stripe. Use this skill when building dashboards, admin interfaces, or any UI that needs Jony Ive-level precision - clean, modern, minimalist with taste. Every pixel matters. +name: frontend-design +description: Create distinctive, production-grade frontend interfaces with high design quality. This skill should be used when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. --- -# Design Principles +# Frontend Design Skill This skill enforces precise, crafted design for enterprise software, SaaS dashboards, admin interfaces, and web applications. The philosophy is Jony Ive-level precision with intentional personality — every interface is polished, and each is designed for its specific context. ## Design Direction (REQUIRED) -**Before writing any code, commit to a design direction.** Don't default. Think about what this specific product needs to feel like. +**Before writing any code, commit to a design direction.** This is not optional. -### Think About Context +### Context Analysis -- **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. +Consider the following before designing: -### Choose a Personality +- **Product function** — A finance tool needs different energy than a creative tool +- **User type** — Power users want density; occasional users want guidance +- **Emotional job** — Trust? Efficiency? Delight? Focus? +- **Distinctiveness** — Every product has a chance to feel memorable -Enterprise/SaaS UI has more range than you think. Consider these directions: +### Personality Options -**Precision & Density** — Tight spacing, monochrome, information-forward. For power users who live in the tool. Think Linear, Raycast, terminal aesthetics. +Enterprise/SaaS UI has more range than assumed. Select from these directions: -**Warmth & Approachability** — Generous spacing, soft shadows, friendly colors. For products that want to feel human. Think Notion, Coda, collaborative tools. +**Precision & Density** — Tight spacing, monochrome, information-forward. For power users who live in the tool. Linear, Raycast, terminal aesthetics. -**Sophistication & Trust** — Cool tones, layered depth, financial gravitas. For products handling money or sensitive data. Think Stripe, Mercury, enterprise B2B. +**Warmth & Approachability** — Generous spacing, soft shadows, friendly colors. For products that feel human. Notion, Coda, collaborative tools. -**Boldness & Clarity** — High contrast, dramatic negative space, confident typography. For products that want to feel modern and decisive. Think Vercel, minimal dashboards. +**Sophistication & Trust** — Cool tones, layered depth, financial gravitas. For products handling money or sensitive data. Stripe, Mercury, enterprise B2B. -**Utility & Function** — Muted palette, functional density, clear hierarchy. For products where the work matters more than the chrome. Think GitHub, developer tools. +**Boldness & Clarity** — High contrast, dramatic negative space, confident typography. For modern, decisive products. Vercel, minimal dashboards. + +**Utility & Function** — Muted palette, functional density, clear hierarchy. For products where work matters more than chrome. GitHub, developer tools. **Data & Analysis** — Chart-optimized, technical but accessible, numbers as first-class citizens. For analytics, metrics, business intelligence. -Pick one. Or blend two. But commit to a direction that fits the product. +Pick one or blend two. Commit to a direction that fits the product. -### Choose a Color Foundation +### Color Foundation -**Don't default to warm neutrals.** Consider the product: +Avoid defaulting 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 modes aren't just light modes inverted. Dark feels technical, focused, premium. Light feels open, approachable, clean. Choose based on context. +**Light or dark?** Dark modes are not inverted light modes. Dark feels technical, focused, premium. Light feels open, approachable, clean. Choose based on context. -**Accent color** — Pick ONE that means something. Blue for trust. Green for growth. Orange for energy. Violet for creativity. Don't just reach for the same accent every time. +**Accent color** — Pick ONE that means something. Blue for trust. Green for growth. Orange for energy. Violet for creativity. Avoid reaching for the same accent every time. -### Choose a Layout Approach +### Layout Approach -The content should drive the layout: +Content drives layout: -- **Dense grids** for information-heavy interfaces where users scan and compare -- **Generous spacing** for focused tasks where users need to concentrate -- **Sidebar navigation** for multi-section apps with many destinations -- **Top navigation** for simpler tools with fewer sections -- **Split panels** for list-detail patterns where context matters +- **Dense grids** — for information-heavy interfaces where users scan and compare +- **Generous spacing** — for focused tasks where users need to concentrate +- **Sidebar navigation** — for multi-section apps with many destinations +- **Top navigation** — for simpler tools with fewer sections +- **Split panels** — for list-detail patterns where context matters -### Choose Typography +### Typography Selection -Typography sets tone. Don't always default: +Typography sets tone: -- **System fonts** — fast, native, invisible (good for utility-focused products) +- **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 @@ -75,15 +77,18 @@ Typography sets tone. Don't always default: These apply regardless of design direction. This is the quality floor. ### The 4px Grid + All spacing uses a 4px base grid: -- `4px` - micro spacing (icon gaps) -- `8px` - tight spacing (within components) -- `12px` - standard spacing (between related elements) -- `16px` - comfortable spacing (section padding) -- `24px` - generous spacing (between sections) -- `32px` - major separation + +- `4px` — micro spacing (icon gaps) +- `8px` — tight spacing (within components) +- `12px` — standard spacing (between related elements) +- `16px` — comfortable spacing (section padding) +- `24px` — generous spacing (between sections) +- `32px` — major separation ### Symmetrical Padding + **TLBR must match.** If top padding is 16px, left/bottom/right must also be 16px. Exception: when content naturally creates visual balance. ```css @@ -96,25 +101,26 @@ padding: 24px 16px 12px 16px; ``` ### Border Radius Consistency + Stick to the 4px grid. Sharper corners feel technical, rounder corners feel friendly. Pick a system and commit: - Sharp: 4px, 6px, 8px - Soft: 8px, 12px - Minimal: 2px, 4px, 6px -Don't mix systems. Consistency creates coherence. +Avoid mixing systems. Consistency creates coherence. ### Depth & Elevation Strategy -**Match your depth approach to your design direction.** Depth is a tool, not a requirement. Different products need different approaches: +**Match depth approach to design direction.** Depth is a tool, not a requirement: -**Borders-only (flat)** — Clean, technical, dense. Works for utility-focused tools where information density matters more than visual lift. Linear, Raycast, and many developer tools use almost no shadows — just subtle borders to define regions. This isn't lazy; it's intentional restraint. +**Borders-only (flat)** — Clean, technical, dense. Works for utility-focused tools. Linear, Raycast, and many developer tools use almost no shadows — just subtle borders. -**Subtle single shadows** — Soft lift without complexity. A simple `0 1px 3px rgba(0,0,0,0.08)` can be enough. Works for approachable products that want gentle depth without the weight of layered shadows. +**Subtle single shadows** — Soft lift without complexity. A simple `0 1px 3px rgba(0,0,0,0.08)` can be enough. Works for approachable products. -**Layered shadows** — Rich, premium, dimensional. Multiple shadow layers create realistic depth for products that want to feel substantial. Stripe and Mercury use this approach. Best for cards that need to feel like physical objects. +**Layered shadows** — Rich, premium, dimensional. Multiple shadow layers create realistic depth. Stripe and Mercury use this approach. -**Surface color shifts** — Background tints establish hierarchy without any shadows. A card at `#fff` on a `#f8fafc` background already feels elevated. Shadows can reinforce this, but color does the heavy lifting. +**Surface color shifts** — Background tints establish hierarchy without any shadows. A card at `#fff` on a `#f8fafc` background already feels elevated. Choose ONE approach and commit. Mixing flat borders on some cards with heavy shadows on others creates visual inconsistency. @@ -137,12 +143,12 @@ border: 0.5px solid var(--border); **The craft is in the choice, not the complexity.** A flat interface with perfect spacing and typography is more polished than a shadow-heavy interface with sloppy details. -### Card Layouts Vary, Surface Treatment Stays Consistent -Monotonous card layouts are lazy design. 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, another a two-column split. +### Card Layouts -Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography. Cohesion comes from the container chrome, not from forcing every card into the same layout template. +Monotonous card layouts are lazy design. A metric card does not have to look like a plan card does not have to look like a settings card. Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography. ### Isolated Controls + UI controls deserve container treatment. Date pickers, filters, dropdowns — these should feel like crafted objects sitting on the page, not plain text with click handlers. **Never use native form elements for styled UI.** Native ``, and similar elements render OS-native dropdowns and pickers that cannot be styled. Build custom components instead: @@ -151,34 +157,40 @@ UI controls deserve container treatment. Date pickers, filters, dropdowns — th - Custom date picker: input + calendar popover - Custom checkbox/radio: styled div with state management -**Custom select triggers must use `display: inline-flex` with `white-space: nowrap`** to keep text and chevron icons on the same row. Without this, flex children can wrap to new lines. +**Custom select triggers must use `display: inline-flex` with `white-space: nowrap`** to keep text and chevron icons on the same row. ### Typography Hierarchy + - Headlines: 600 weight, tight letter-spacing (-0.02em) - Body: 400-500 weight, standard tracking - Labels: 500 weight, slight positive tracking for uppercase - Scale: 11px, 12px, 13px, 14px (base), 16px, 18px, 24px, 32px ### Monospace for Data + Numbers, IDs, codes, timestamps belong in monospace. Use `tabular-nums` for columnar alignment. Mono signals "this is data." ### Iconography + Use **Phosphor Icons** (`@phosphor-icons/react`). Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Give standalone icons presence with subtle background containers. ### Animation + - 150ms for micro-interactions, 200-250ms for larger transitions - Easing: `cubic-bezier(0.25, 1, 0.5, 1)` - No spring/bouncy effects in enterprise UI ### Contrast Hierarchy + Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently. ### Color for Meaning Only + Gray builds structure. Color only appears when it communicates: status, action, error, success. Decorative color is noise. -When building data-heavy interfaces, ask whether each use of color is earning its place. Score bars don't need to be color-coded by performance — a single muted color works. Grade badges don't need traffic-light colors — typography can do the hierarchy work. Look at how GitHub renders tables and lists: almost entirely monochrome, with color reserved for status indicators and actionable elements. +When building data-heavy interfaces, ask whether each use of color earns its place. Score bars do not need color-coded performance — a single muted color works. Grade badges do not need traffic-light colors — typography can do the hierarchy work. --- @@ -186,11 +198,11 @@ When building data-heavy interfaces, ask whether each use of color is earning it Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including: -- **Navigation** — sidebar or top nav showing where you are in the app +- **Navigation** — sidebar or top nav showing location in the app - **Location indicator** — breadcrumbs, page title, or active nav state -- **User context** — who's logged in, what workspace/org +- **User context** — who is logged in, what workspace/org -When building sidebars, consider using the same background as the main content area. Tools like Supabase, Linear, and Vercel rely on a subtle border for separation rather than different background colors. This reduces visual weight and feels more unified. +When building sidebars, consider using the same background as the main content area. Tools like Supabase, Linear, and Vercel rely on a subtle border for separation rather than different background colors. --- @@ -198,7 +210,7 @@ When building sidebars, consider using the same background as the main content a Dark interfaces have different needs: -**Borders over shadows** — Shadows are less visible on dark backgrounds. Lean more on borders for definition. A border at 10-15% white opacity might look nearly invisible but it's doing its job — resist the urge to make it more prominent. +**Borders over shadows** — Shadows are less visible on dark backgrounds. Lean more on borders for definition. A border at 10-15% white opacity might look nearly invisible but it does its job — resist the urge to make it more prominent. **Adjust semantic colors** — Status colors (success, warning, error) often need to be slightly desaturated or adjusted for dark backgrounds to avoid feeling harsh. @@ -209,6 +221,7 @@ Dark interfaces have different needs: ## Anti-Patterns ### Never Do This + - Dramatic drop shadows (`box-shadow: 0 25px 50px...`) - Large border radius (16px+) on small elements - Asymmetric padding without clear reason @@ -219,7 +232,8 @@ Dark interfaces have different needs: - Gradients for decoration - Multiple accent colors in one interface -### Always Question +### Self-Check Questions + - "Did I think about what this product needs, or did I default?" - "Does this direction fit the context and users?" - "Does this element feel crafted?" From 0e75ed4cee7f7f18590675469c07dd6712d06601 Mon Sep 17 00:00:00 2001 From: nniel-ape Date: Tue, 6 Jan 2026 19:05:46 +0300 Subject: [PATCH 2/3] feat: add Claude Code plugin support - Add .claude-plugin/plugin.json manifest for plugin install - Move skill/SKILL.md to skills/SKILL.md (plugin convention) - Update README with plugin installation as recommended method - Remove install.sh (replaced by plugin system) --- .claude-plugin/plugin.json | 11 +++++++++++ README.md | 30 ++++++++++++++---------------- install.sh | 21 --------------------- {skill => skills}/SKILL.md | 0 4 files changed, 25 insertions(+), 37 deletions(-) create mode 100644 .claude-plugin/plugin.json delete mode 100755 install.sh rename {skill => skills}/SKILL.md (100%) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9afd9cf --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "frontend-design", + "version": "1.0.0", + "description": "Create distinctive, production-grade frontend interfaces with high design quality", + "author": { + "name": "Damola Akinleye" + }, + "repository": "https://github.com/Dammyjay93/claude-design-skill", + "license": "MIT", + "keywords": ["frontend", "design", "ui", "css", "react", "tailwind"] +} diff --git a/README.md b/README.md index 0fb4e03..c4e912e 100644 --- a/README.md +++ b/README.md @@ -23,25 +23,20 @@ See the difference at **[dashboard-v4-eta.vercel.app](https://dashboard-v4-eta.v ## Installation -### Quick Install (macOS/Linux) +### Plugin Install (Recommended) + +``` +/plugin install github:Dammyjay93/claude-design-skill +``` + +### Manual Install (Legacy) ```bash mkdir -p ~/.claude/skills/frontend-design curl -o ~/.claude/skills/frontend-design/SKILL.md \ - https://raw.githubusercontent.com/Dammyjay93/claude-design-skill/main/skill/SKILL.md + https://raw.githubusercontent.com/Dammyjay93/claude-design-skill/main/skills/SKILL.md ``` -### Manual Install - -1. Create the skill directory: - ```bash - mkdir -p ~/.claude/skills/frontend-design - ``` - -2. Copy `skill/SKILL.md` to `~/.claude/skills/frontend-design/SKILL.md` - -3. Restart Claude Code - ## Usage The skill activates automatically when building web components, pages, or applications. It can also be invoked explicitly: @@ -80,13 +75,16 @@ The skill supports multiple design personalities: ## File Structure ``` -~/.claude/skills/frontend-design/ -└── SKILL.md # The skill definition +claude-design-skill/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +└── skills/ + └── SKILL.md # The skill definition ``` ## Customization -Fork this repo and modify `skill/SKILL.md` to match your design system. Key sections to customize: +Fork this repo and modify `skills/SKILL.md` to match your design system. Key sections to customize: - **Design Directions** — Add your own personality options - **Color Foundation** — Define your brand colors diff --git a/install.sh b/install.sh deleted file mode 100755 index 4d6d03d..0000000 --- a/install.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/bin/bash - -# Frontend Design Skill Installer for Claude Code - -set -e - -SKILL_DIR="$HOME/.claude/skills/frontend-design" -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -echo "Installing Frontend Design skill for Claude Code..." - -# Create skill directory -mkdir -p "$SKILL_DIR" - -# Copy skill file -cp "$SCRIPT_DIR/skill/SKILL.md" "$SKILL_DIR/SKILL.md" - -echo "Installed to $SKILL_DIR/SKILL.md" -echo "" -echo "Restart Claude Code to activate the skill." -echo "Usage: /frontend-design or ask Claude to build UI" diff --git a/skill/SKILL.md b/skills/SKILL.md similarity index 100% rename from skill/SKILL.md rename to skills/SKILL.md From 536bac3c304abe1a066773e6fa425574ed7d46d8 Mon Sep 17 00:00:00 2001 From: nniel-ape Date: Tue, 6 Jan 2026 19:12:59 +0300 Subject: [PATCH 3/3] feat: enhance frontend-design skill with Anthropic best practices Integrate creative philosophy and anti-AI-slop guidance while preserving detailed craft rules: - Add "Design Thinking" section with bold aesthetic direction - Add Creative Extremes (brutalist, retro-futuristic, luxury, etc.) - Add Spatial Composition and Backgrounds/Visual Details sections - Expand Motion & Animation with philosophy and patterns - Add "AI Slop to Avoid" anti-patterns section - Add closing encouragement for creative work --- skills/SKILL.md | 169 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 138 insertions(+), 31 deletions(-) diff --git a/skills/SKILL.md b/skills/SKILL.md index cbb49cf..c0b6e4a 100644 --- a/skills/SKILL.md +++ b/skills/SKILL.md @@ -1,28 +1,43 @@ --- name: frontend-design -description: Create distinctive, production-grade frontend interfaces with high design quality. This skill should be used when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. +description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. --- # Frontend Design Skill -This skill enforces precise, crafted design for enterprise software, SaaS dashboards, admin interfaces, and web applications. The philosophy is Jony Ive-level precision with intentional personality — every interface is polished, and each is designed for its specific context. +This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. The philosophy combines Jony Ive-level precision with intentional personality — every interface is polished, crafted for its specific context, and memorable. -## Design Direction (REQUIRED) +--- -**Before writing any code, commit to a design direction.** This is not optional. +## Design Thinking (REQUIRED) -### Context Analysis +**Before writing any code, commit to a BOLD aesthetic direction.** This is not optional. + +### Creative Foundation Consider the following before designing: +- **Purpose**: What problem does this interface solve? Who uses it? +- **Tone**: Pick an extreme — don't settle for safe defaults (see Aesthetic Directions below) +- **Constraints**: Technical requirements (framework, performance, accessibility) +- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? + +**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity. + +### Context Analysis + - **Product function** — A finance tool needs different energy than a creative tool - **User type** — Power users want density; occasional users want guidance - **Emotional job** — Trust? Efficiency? Delight? Focus? - **Distinctiveness** — Every product has a chance to feel memorable -### Personality Options +--- + +## Aesthetic Directions + +Enterprise/SaaS UI has more range than assumed. Select from these directions or blend two: -Enterprise/SaaS UI has more range than assumed. Select from these directions: +### Enterprise Personalities **Precision & Density** — Tight spacing, monochrome, information-forward. For power users who live in the tool. Linear, Raycast, terminal aesthetics. @@ -36,9 +51,27 @@ Enterprise/SaaS UI has more range than assumed. Select from these directions: **Data & Analysis** — Chart-optimized, technical but accessible, numbers as first-class citizens. For analytics, metrics, business intelligence. +### Creative Extremes + +Push beyond safe defaults. Consider these as starting points: + +- **Brutally minimal** — stark, almost uncomfortable restraint +- **Maximalist chaos** — layered, dense, overwhelming intentionally +- **Retro-futuristic** — CRT glow, scan lines, analog-digital fusion +- **Organic/natural** — flowing shapes, earth tones, breathing motion +- **Luxury/refined** — precious metals, silk textures, whisper-quiet +- **Playful/toy-like** — bouncy, colorful, delightfully naive +- **Editorial/magazine** — dramatic typography, white space as content +- **Brutalist/raw** — exposed structure, anti-polish aesthetic +- **Art deco/geometric** — ornate symmetry, gold accents, 1920s glamour +- **Soft/pastel** — gentle gradients, rounded everything, cloud-like +- **Industrial/utilitarian** — exposed grids, warning colors, functional beauty + Pick one or blend two. Commit to a direction that fits the product. -### Color Foundation +--- + +## Color Foundation Avoid defaulting to warm neutrals. Consider the product: @@ -51,7 +84,11 @@ Avoid defaulting to warm neutrals. Consider the product: **Accent color** — Pick ONE that means something. Blue for trust. Green for growth. Orange for energy. Violet for creativity. Avoid reaching for the same accent every time. -### Layout Approach +**CRITICAL**: Dominant colors with sharp accents outperform timid, evenly-distributed palettes. + +--- + +## Layout Approach Content drives layout: @@ -61,14 +98,44 @@ Content drives layout: - **Top navigation** — for simpler tools with fewer sections - **Split panels** — for list-detail patterns where context matters -### Typography Selection +### Spatial Composition + +Break conventional layouts through: -Typography sets tone: +- **Asymmetry** — intentional imbalance creates visual interest +- **Overlap** — elements breaking their containers +- **Diagonal flow** — eye movement beyond horizontal/vertical +- **Grid-breaking elements** — strategic rule violations +- **Generous negative space** OR **controlled density** — both work, commit to one -- **System fonts** — fast, native, invisible (utility-focused products) -- **Geometric sans** (Geist, Inter) — modern, clean, technical +--- + +## Typography + +Typography sets tone and is often the single most impactful design decision. + +### Font Selection + +Choose fonts that are beautiful, unique, and interesting. **Avoid generic fonts like Arial, Inter, Roboto, and system fonts** — opt for distinctive choices that elevate the aesthetics. + +- **System fonts** — fast, native, invisible (only for utility-focused products) +- **Geometric sans** (Geist, Plus Jakarta Sans) — modern, clean, technical - **Humanist sans** (SF Pro, Satoshi) — warmer, more approachable - **Monospace influence** — technical, developer-focused, data-heavy +- **Display fonts** — distinctive headlines that anchor the design + +**Pair a distinctive display font with a refined body font.** Unexpected, characterful font choices create memorable interfaces. + +### Typography Hierarchy + +- Headlines: 600 weight, tight letter-spacing (-0.02em) +- Body: 400-500 weight, standard tracking +- Labels: 500 weight, slight positive tracking for uppercase +- Scale: 11px, 12px, 13px, 14px (base), 16px, 18px, 24px, 32px + +### Monospace for Data + +Numbers, IDs, codes, timestamps belong in monospace. Use `tabular-nums` for columnar alignment. Mono signals "this is data." --- @@ -159,29 +226,12 @@ UI controls deserve container treatment. Date pickers, filters, dropdowns — th **Custom select triggers must use `display: inline-flex` with `white-space: nowrap`** to keep text and chevron icons on the same row. -### Typography Hierarchy - -- Headlines: 600 weight, tight letter-spacing (-0.02em) -- Body: 400-500 weight, standard tracking -- Labels: 500 weight, slight positive tracking for uppercase -- Scale: 11px, 12px, 13px, 14px (base), 16px, 18px, 24px, 32px - -### Monospace for Data - -Numbers, IDs, codes, timestamps belong in monospace. Use `tabular-nums` for columnar alignment. Mono signals "this is data." - ### Iconography Use **Phosphor Icons** (`@phosphor-icons/react`). Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Give standalone icons presence with subtle background containers. -### Animation - -- 150ms for micro-interactions, 200-250ms for larger transitions -- Easing: `cubic-bezier(0.25, 1, 0.5, 1)` -- No spring/bouncy effects in enterprise UI - ### Contrast Hierarchy Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently. @@ -194,6 +244,45 @@ When building data-heavy interfaces, ask whether each use of color earns its pla --- +## Motion & Animation + +### Philosophy + +Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. + +### Timing + +- 150ms for micro-interactions +- 200-250ms for larger transitions +- Easing: `cubic-bezier(0.25, 1, 0.5, 1)` +- No spring/bouncy effects in enterprise UI (unless the aesthetic explicitly calls for playfulness) + +### Motion Patterns + +- **Staggered reveals** — elements entering in sequence +- **Scroll-triggered effects** — content appearing as user scrolls +- **Hover states that surprise** — unexpected but delightful responses +- **Prioritize CSS-only solutions** for HTML; use Motion library for React when available + +--- + +## Backgrounds & Visual Details + +Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic: + +- **Gradient meshes** — organic color blending +- **Noise textures** — tactile, analog feel +- **Geometric patterns** — structured, mathematical +- **Layered transparencies** — depth through overlap +- **Dramatic shadows** — theatrical lighting +- **Decorative borders** — ornate or minimal framing +- **Custom cursors** — interactive personality +- **Grain overlays** — photographic, filmic quality + +Match background treatment to the aesthetic direction. A brutalist interface doesn't need gradient meshes. A luxury interface doesn't need geometric patterns. + +--- + ## Navigation Context Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including: @@ -220,6 +309,18 @@ Dark interfaces have different needs: ## Anti-Patterns +### AI Slop to Avoid + +NEVER use generic AI-generated aesthetics: + +- **Overused font families**: Inter, Roboto, Arial, system fonts for creative work +- **Clichéd color schemes**: particularly purple gradients on white backgrounds, the ubiquitous blue (#3B82F6) +- **Predictable layouts**: same hero section, same card grid, same footer +- **Cookie-cutter patterns**: lacking context-specific character +- **Convergent choices**: Space Grotesk appearing in every generation + +Every design should be different. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations. + ### Never Do This - Dramatic drop shadows (`box-shadow: 0 25px 50px...`) @@ -228,7 +329,7 @@ Dark interfaces have different needs: - Pure white cards on colored backgrounds - Thick borders (2px+) for decoration - Excessive spacing (margins > 48px between sections) -- Spring/bouncy animations +- Spring/bouncy animations in enterprise contexts - Gradients for decoration - Multiple accent colors in one interface @@ -239,6 +340,8 @@ Dark interfaces have different needs: - "Does this element feel crafted?" - "Is my depth strategy consistent and intentional?" - "Are all elements on the grid?" +- "Would someone remember this interface tomorrow?" +- "Am I reaching for the same solution I used last time?" --- @@ -248,4 +351,8 @@ Every interface should look designed by a team that obsesses over 1-pixel differ Different products want different things. A developer tool wants precision and density. A collaborative product wants warmth and space. A financial product wants trust and sophistication. Let the product context guide the aesthetic. +**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. + The goal: intricate minimalism with appropriate personality. Same quality bar, context-driven execution. + +**Remember: Claude is capable of extraordinary creative work. Don't hold back — show what can truly be created when thinking outside the box and committing fully to a distinctive vision.**