design-foundation

name	adhoc_design_foundation
description	Merged design foundation skill set: context gathering, design direction, onboarding, extraction, distillation, and clarification.

Ad-hoc Design Foundation

This file is a grouped copy of the source bundle from C:\Users\jan.papousek\Downloads\impeccable-style-universal\.agents\skills, focused on design context, direction, and structural thinking.

Vault Integration Notes

• Follow this vault's AGENTS.md, SOUL.md, and MEMORY.md first.
• Inspect relevant local notes before design work, especially project notes under 30_Projects/.
• Where the source bundle says to persist design context in .impeccable.md or other external tool files, persist that context in the relevant vault project note or project snapshot instead.
• Keep outputs and notes Obsidian-friendly, and preserve established design systems when working inside an existing product.

Source Skill: design-foundation

---

name: design-foundation description: Create distinctive, production-grade interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics.

This skill guides creation of distinctive, production-grade interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

Context Gathering Protocol

Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.

Required context — every design skill needs at minimum:

• Target audience: Who uses this product and in what context?
• Use cases: What jobs are they trying to get done?
• Brand personality/tone: How should the interface feel?

Individual skills may require additional context — check the skill's preparation section for specifics.

CRITICAL: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context.

Gathering order:

1. Check current instructions (instant): If your loaded instructions already contain a Design Context section, proceed immediately.
2. Check .impeccable.md (fast): If not in instructions, read .impeccable.md from the project root. If it exists and contains the required context, proceed.
3. Run teach-impeccable (REQUIRED): If neither source has context, you MUST run the teach-impeccable skill NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.

---

Design Direction

Commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• 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.

Then implement working code that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Design Aesthetics Guidelines

Typography

→ Consult typography reference for scales, pairing, and loading strategies.

Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.

DO: Use a modular type scale with fluid sizing (clamp) DO: Vary font weights and sizes to create clear visual hierarchy DON'T: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults DON'T: Use monospace typography as lazy shorthand for "technical/developer" vibes DON'T: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated

Color & Theme

→ Consult color reference for OKLCH, palettes, and dark mode.

Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.

DO: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes DO: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion DON'T: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead DON'T: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature DON'T: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds DON'T: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful DON'T: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions

Layout & Space

→ Consult spatial reference for grids, rhythm, and container queries.

Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.

DO: Create visual rhythm through varied spacing—tight groupings, generous separations DO: Use fluid spacing with clamp() that breathes on larger screens DO: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis DON'T: Wrap everything in cards—not everything needs a container DON'T: Nest cards inside cards—visual noise, flatten the hierarchy DON'T: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly DON'T: Use the hero metric layout template—big number, small label, supporting stats, gradient accent DON'T: Center everything—left-aligned text with asymmetric layouts feels more designed DON'T: Use the same spacing everywhere—without rhythm, layouts feel monotonous

Visual Details

DO: Use intentional, purposeful decorative elements that reinforce brand DON'T: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully DON'T: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional DON'T: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful DON'T: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output DON'T: Use modals unless there's truly no better alternative—modals are lazy

Motion

→ Consult motion reference for timing, easing, and reduced motion.

Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.

DO: Use motion to convey state changes—entrances, exits, feedback DO: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration DO: For height animations, use grid-template-rows transitions instead of animating height directly DON'T: Animate layout properties (width, height, padding, margin)—use transform and opacity only DON'T: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly

Interaction

→ Consult interaction reference for forms, focus, and loading patterns.

Make interactions feel fast. Use optimistic UI—update immediately, sync later.

DO: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions) DO: Design empty states that teach the interface, not just say "nothing here" DO: Make every interactive surface feel intentional and responsive DON'T: Repeat the same information—redundant headers, intros that restate the heading DON'T: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters

Responsive

→ Consult responsive reference for mobile-first, fluid design, and container queries.

DO: Use container queries (@container) for component-level responsiveness DO: Adapt the interface for different contexts—don't just shrink it DON'T: Hide critical functionality on mobile—adapt the interface, don't amputate it

UX Writing

→ Consult ux-writing reference for labels, errors, and empty states.

DO: Make every word earn its place DON'T: Repeat information users can already see

---

The AI Slop Test

Critical quality check: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.

A distinctive interface should make someone ask "how was this made?" not "which AI made this?"

Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025.

---

Implementation Principles

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.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.

Remember: the model 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.

Source Skill: teach-impeccable

---

name: teach-impeccable description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines. user-invokable: true

Gather design context for this project, then persist it for all future sessions.

Step 1: Explore the Codebase

Before asking questions, thoroughly scan the project to discover what you can:

• README and docs: Project purpose, target audience, any stated goals
• Package.json / config files: Tech stack, dependencies, existing design libraries
• Existing components: Current design patterns, spacing, typography in use
• Brand assets: Logos, favicons, color values already defined
• Design tokens / CSS variables: Existing color palettes, font stacks, spacing scales
• Any style guides or brand documentation

Note what you've learned and what remains unclear.

Step 2: Ask UX-Focused Questions

ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:

Users & Purpose

• Who uses this? What's their context when using it?
• What job are they trying to get done?
• What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)

Brand & Personality

• How would you describe the brand personality in 3 words?
• Any reference sites or apps that capture the right feel? What specifically about them?
• What should this explicitly NOT look like? Any anti-references?

Aesthetic Preferences

• Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
• Light mode, dark mode, or both?
• Any colors that must be used or avoided?

Accessibility & Inclusion

• Specific accessibility requirements? (WCAG level, known user needs)
• Considerations for reduced motion, color blindness, or other accommodations?

Skip questions where the answer is already clear from the codebase exploration.

Step 3: Write Design Context

Synthesize your findings and the user's answers into a ## Design Context section:

## Design Context

### Users
[Who they are, their context, the job to be done]

### Brand Personality
[Voice, tone, 3-word personality, emotional goals]

### Aesthetic Direction
[Visual tone, references, anti-references, theme]

### Design Principles
[3-5 principles derived from the conversation that should guide all design decisions]

Write this section to .impeccable.md in the project root. If the file already exists, update the Design Context section in place.

Then ask the user directly to clarify what you cannot infer. whether they'd also like the Design Context appended to .github/copilot-instructions.md. If yes, append or update the section there as well.

Confirm completion and summarize the key design principles that will now guide all future work.

Source Skill: clarify

---

name: clarify description: Improve unclear UX copy, error messages, microcopy, labels, and instructions. Makes interfaces easier to understand and use. user-invokable: true argument-hint: [TARGET=]

Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: audience technical level and users' mental state in context.

---

Assess Current Copy

Identify what makes the text unclear or ineffective:

1. Find clarity problems:

   • Jargon: Technical terms users won't understand
   • Ambiguity: Multiple interpretations possible
   • Passive voice: "Your file has been uploaded" vs "We uploaded your file"
   • Length: Too wordy or too terse
   • Assumptions: Assuming user knowledge they don't have
   • Missing context: Users don't know what to do or why
   • Tone mismatch: Too formal, too casual, or inappropriate for situation

2. Understand the context:

   • Who's the audience? (Technical? General? First-time users?)
   • What's the user's mental state? (Stressed during error? Confident during success?)
   • What's the action? (What do we want users to do?)
   • What's the constraint? (Character limits? Space limitations?)

CRITICAL: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.

Plan Copy Improvements

Create a strategy for clearer communication:

• Primary message: What's the ONE thing users need to know?
• Action needed: What should users do next (if anything)?
• Tone: How should this feel? (Helpful? Apologetic? Encouraging?)
• Constraints: Length limits, brand voice, localization considerations

IMPORTANT: Good UX writing is invisible. Users should understand immediately without noticing the words.

Improve Copy Systematically

Refine text across these common areas:

Error Messages

Bad: "Error 403: Forbidden" Good: "You don't have permission to view this page. Contact your admin for access."

Bad: "Invalid input" Good: "Email addresses need an @ symbol. Try: [e-mail]"

Principles:

• Explain what went wrong in plain language
• Suggest how to fix it
• Don't blame the user
• Include examples when helpful
• Link to help/support if applicable

Form Labels & Instructions

Bad: "DOB (MM/DD/YYYY)" Good: "Date of birth" (with placeholder showing format)

Bad: "Enter value here" Good: "Your email address" or "Company name"

Principles:

• Use clear, specific labels (not generic placeholders)
• Show format expectations with examples
• Explain why you're asking (when not obvious)
• Put instructions before the field, not after
• Keep required field indicators clear

Button & CTA Text

Bad: "Click here" | "Submit" | "OK" Good: "Create account" | "Save changes" | "Got it, thanks"

Principles:

• Describe the action specifically
• Use active voice (verb + noun)
• Match user's mental model
• Be specific ("Save" is better than "OK")

Help Text & Tooltips

Bad: "This is the username field" Good: "Choose a username. You can change this later in Settings."

Principles:

• Add value (don't just repeat the label)
• Answer the implicit question ("What is this?" or "Why do you need this?")
• Keep it brief but complete
• Link to detailed docs if needed

Empty States

Bad: "No items" Good: "No projects yet. Create your first project to get started."

Principles:

• Explain why it's empty (if not obvious)
• Show next action clearly
• Make it welcoming, not dead-end

Success Messages

Bad: "Success" Good: "Settings saved! Your changes will take effect immediately."

Principles:

• Confirm what happened
• Explain what happens next (if relevant)
• Be brief but complete
• Match the user's emotional moment (celebrate big wins)

Loading States

Bad: "Loading..." (for 30+ seconds) Good: "Analyzing your data... this usually takes 30-60 seconds"

Principles:

• Set expectations (how long?)
• Explain what's happening (when it's not obvious)
• Show progress when possible
• Offer escape hatch if appropriate ("Cancel")

Confirmation Dialogs

Bad: "Are you sure?" Good: "Delete 'Project Alpha'? This can't be undone."

Principles:

• State the specific action
• Explain consequences (especially for destructive actions)
• Use clear button labels ("Delete project" not "Yes")
• Don't overuse confirmations (only for risky actions)

Navigation & Wayfinding

Bad: Generic labels like "Items" | "Things" | "Stuff" Good: Specific labels like "Your projects" | "Team members" | "Settings"

Principles:

• Be specific and descriptive
• Use language users understand (not internal jargon)
• Make hierarchy clear
• Consider information scent (breadcrumbs, current location)

Apply Clarity Principles

Every piece of copy should follow these rules:

1. Be specific: "Enter email" not "Enter value"
2. Be concise: Cut unnecessary words (but don't sacrifice clarity)
3. Be active: "Save changes" not "Changes will be saved"
4. Be human: "Oops, something went wrong" not "System error encountered"
5. Be helpful: Tell users what to do, not just what happened
6. Be consistent: Use same terms throughout (don't vary for variety)

NEVER:

• Use jargon without explanation
• Blame users ("You made an error" → "This field is required")
• Be vague ("Something went wrong" without explanation)
• Use passive voice unnecessarily
• Write overly long explanations (be concise)
• Use humor for errors (be empathetic instead)
• Assume technical knowledge
• Vary terminology (pick one term and stick with it)
• Repeat information (headers restating intros, redundant explanations)
• Use placeholders as the only labels (they disappear when users type)

Verify Improvements

Test that copy improvements work:

• Comprehension: Can users understand without context?
• Actionability: Do users know what to do next?
• Brevity: Is it as short as possible while remaining clear?
• Consistency: Does it match terminology elsewhere?
• Tone: Is it appropriate for the situation?

Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.

Source Skill: distill

---

name: distill description: Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. user-invokable: true argument-hint: [TARGET=]

Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.

---

Assess Current State

Analyze what makes the design feel complex or cluttered:

1. Identify complexity sources:

   • Too many elements: Competing buttons, redundant information, visual clutter
   • Excessive variation: Too many colors, fonts, sizes, styles without purpose
   • Information overload: Everything visible at once, no progressive disclosure
   • Visual noise: Unnecessary borders, shadows, backgrounds, decorations
   • Confusing hierarchy: Unclear what matters most
   • Feature creep: Too many options, actions, or paths forward

2. Find the essence:

   • What's the primary user goal? (There should be ONE)
   • What's actually necessary vs nice-to-have?
   • What can be removed, hidden, or combined?
   • What's the 20% that delivers 80% of value?

If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.

CRITICAL: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.

Plan Simplification

Create a ruthless editing strategy:

• Core purpose: What's the ONE thing this should accomplish?
• Essential elements: What's truly necessary to achieve that purpose?
• Progressive disclosure: What can be hidden until needed?
• Consolidation opportunities: What can be combined or integrated?

IMPORTANT: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless.

Simplify the Design

Systematically remove complexity across these dimensions:

Information Architecture

• Reduce scope: Remove secondary actions, optional features, redundant information
• Progressive disclosure: Hide complexity behind clear entry points (accordions, modals, step-through flows)
• Combine related actions: Merge similar buttons, consolidate forms, group related content
• Clear hierarchy: ONE primary action, few secondary actions, everything else tertiary or hidden
• Remove redundancy: If it's said elsewhere, don't repeat it here

Visual Simplification

• Reduce color palette: Use 1-2 colors plus neutrals, not 5-7 colors
• Limit typography: One font family, 3-4 sizes maximum, 2-3 weights
• Remove decorations: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function
• Flatten structure: Reduce nesting, remove unnecessary containers—never nest cards inside cards
• Remove unnecessary cards: Cards aren't needed for basic layout; use spacing and alignment instead
• Consistent spacing: Use one spacing scale, remove arbitrary gaps

Layout Simplification

• Linear flow: Replace complex grids with simple vertical flow where possible
• Remove sidebars: Move secondary content inline or hide it
• Full-width: Use available space generously instead of complex multi-column layouts
• Consistent alignment: Pick left or center, stick with it
• Generous white space: Let content breathe, don't pack everything tight

Interaction Simplification

• Reduce choices: Fewer buttons, fewer options, clearer path forward (paradox of choice is real)
• Smart defaults: Make common choices automatic, only ask when necessary
• Inline actions: Replace modal flows with inline editing where possible
• Remove steps: Can signup be one step instead of three? Can checkout be simplified?
• Clear CTAs: ONE obvious next step, not five competing actions

Content Simplification

• Shorter copy: Cut every sentence in half, then do it again
• Active voice: "Save changes" not "Changes will be saved"
• Remove jargon: Plain language always wins
• Scannable structure: Short paragraphs, bullet points, clear headings
• Essential information only: Remove marketing fluff, legalese, hedging
• Remove redundant copy: No headers restating intros, no repeated explanations, say it once

Code Simplification

• Remove unused code: Dead CSS, unused components, orphaned files
• Flatten component trees: Reduce nesting depth
• Consolidate styles: Merge similar styles, use utilities consistently
• Reduce variants: Does that component need 12 variations, or can 3 cover 90% of cases?

NEVER:

• Remove necessary functionality (simplicity ≠ feature-less)
• Sacrifice accessibility for simplicity (clear labels and ARIA still required)
• Make things so simple they're unclear (mystery ≠ minimalism)
• Remove information users need to make decisions
• Eliminate hierarchy completely (some things should stand out)
• Oversimplify complex domains (match complexity to actual task complexity)

Verify Simplification

Ensure simplification improves usability:

• Faster task completion: Can users accomplish goals more quickly?
• Reduced cognitive load: Is it easier to understand what to do?
• Still complete: Are all necessary features still accessible?
• Clearer hierarchy: Is it obvious what matters most?
• Better performance: Does simpler design load faster?

Document Removed Complexity

If you removed features or options:

• Document why they were removed
• Consider if they need alternative access points
• Note any user feedback to monitor

Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

Source Skill: extract

---

name: extract description: Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. user-invokable: true argument-hint: [TARGET=]

Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse.

Discover

Analyze the target area to identify extraction opportunities:

1. Find the design system: Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure:

   • Component organization and naming conventions
   • Design token structure (if any)
   • Documentation patterns
   • Import/export conventions

   CRITICAL: If no design system exists, ask before creating one. Understand the preferred location and structure first.

2. Identify patterns: Look for:

   • Repeated components: Similar UI patterns used multiple times (buttons, cards, inputs, etc.)
   • Hard-coded values: Colors, spacing, typography, shadows that should be tokens
   • Inconsistent variations: Multiple implementations of the same concept (3 different button styles)
   • Reusable patterns: Layout patterns, composition patterns, interaction patterns worth systematizing

3. Assess value: Not everything should be extracted. Consider:

   • Is this used 3+ times, or likely to be reused?
   • Would systematizing this improve consistency?
   • Is this a general pattern or context-specific?
   • What's the maintenance cost vs benefit?

Plan Extraction

Create a systematic extraction plan:

• Components to extract: Which UI elements become reusable components?
• Tokens to create: Which hard-coded values become design tokens?
• Variants to support: What variations does each component need?
• Naming conventions: Component names, token names, prop names that match existing patterns
• Migration path: How to refactor existing uses to consume the new shared versions

IMPORTANT: Design systems grow incrementally. Extract what's clearly reusable now, not everything that might someday be reusable.

Extract & Enrich

Build improved, reusable versions:

• Components: Create well-designed components with:

  • Clear props API with sensible defaults
  • Proper variants for different use cases
  • Accessibility built in (ARIA, keyboard navigation, focus management)
  • Documentation and usage examples

• Design tokens: Create tokens with:

  • Clear naming (primitive vs semantic)
  • Proper hierarchy and organization
  • Documentation of when to use each token

• Patterns: Document patterns with:

  • When to use this pattern
  • Code examples
  • Variations and combinations

NEVER:

• Extract one-off, context-specific implementations without generalization
• Create components so generic they're useless
• Extract without considering existing design system conventions
• Skip proper TypeScript types or prop documentation
• Create tokens for every single value (tokens should have semantic meaning)

Migrate

Replace existing uses with the new shared versions:

• Find all instances: Search for the patterns you've extracted
• Replace systematically: Update each use to consume the shared version
• Test thoroughly: Ensure visual and functional parity
• Delete dead code: Remove the old implementations

Document

Update design system documentation:

• Add new components to the component library
• Document token usage and values
• Add examples and guidelines
• Update any Storybook or component catalog

Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.

Source Skill: onboard

---

name: onboard description: Design or improve onboarding flows, empty states, and first-time user experiences. Helps users get started successfully and understand value quickly. user-invokable: true argument-hint: [TARGET=]

MANDATORY PREPARATION

Use the design-foundation skill — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users' experience level.

---

Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.

Assess Onboarding Needs

Understand what users need to learn and why:

1. Identify the challenge:

   • What are users trying to accomplish?
   • What's confusing or unclear about current experience?
   • Where do users get stuck or drop off?
   • What's the "aha moment" we want users to reach?

2. Understand the users:

   • What's their experience level? (Beginners, power users, mixed?)
   • What's their motivation? (Excited and exploring? Required by work?)
   • What's their time commitment? (5 minutes? 30 minutes?)
   • What alternatives do they know? (Coming from competitor? New to category?)

3. Define success:

   • What's the minimum users need to learn to be successful?
   • What's the key action we want them to take? (First project? First invite?)
   • How do we know onboarding worked? (Completion rate? Time to value?)

CRITICAL: Onboarding should get users to value as quickly as possible, not teach everything possible.

Onboarding Principles

Follow these core principles:

Show, Don't Tell

• Demonstrate with working examples, not just descriptions
• Provide real functionality in onboarding, not separate tutorial mode
• Use progressive disclosure - teach one thing at a time

Make It Optional (When Possible)

• Let experienced users skip onboarding
• Don't block access to product
• Provide "Skip" or "I'll explore on my own" options

Time to Value

• Get users to their "aha moment" ASAP
• Front-load most important concepts
• Teach 20% that delivers 80% of value
• Save advanced features for contextual discovery

Context Over Ceremony

• Teach features when users need them, not upfront
• Empty states are onboarding opportunities
• Tooltips and hints at point of use

Respect User Intelligence

• Don't patronize or over-explain
• Be concise and clear
• Assume users can figure out standard patterns

Design Onboarding Experiences

Create appropriate onboarding for the context:

Initial Product Onboarding

Welcome Screen:

• Clear value proposition (what is this product?)
• What users will learn/accomplish
• Time estimate (honest about commitment)
• Option to skip (for experienced users)

Account Setup:

• Minimal required information (collect more later)
• Explain why you're asking for each piece of information
• Smart defaults where possible
• Social login when appropriate

Core Concept Introduction:

• Introduce 1-3 core concepts (not everything)
• Use simple language and examples
• Interactive when possible (do, don't just read)
• Progress indication (step 1 of 3)

First Success:

• Guide users to accomplish something real
• Pre-populated examples or templates
• Celebrate completion (but don't overdo it)
• Clear next steps

Feature Discovery & Adoption

Empty States: Instead of blank space, show:

• What will appear here (description + screenshot/illustration)
• Why it's valuable
• Clear CTA to create first item
• Example or template option

Example:

No projects yet
Projects help you organize your work and collaborate with your team.
[Create your first project] or [Start from template]

Contextual Tooltips:

• Appear at relevant moment (first time user sees feature)
• Point directly at relevant UI element
• Brief explanation + benefit
• Dismissable (with "Don't show again" option)
• Optional "Learn more" link

Feature Announcements:

• Highlight new features when they're released
• Show what's new and why it matters
• Let users try immediately
• Dismissable

Progressive Onboarding:

• Teach features when users encounter them
• Badges or indicators on new/unused features
• Unlock complexity gradually (don't show all options immediately)

Guided Tours & Walkthroughs

When to use:

• Complex interfaces with many features
• Significant changes to existing product
• Industry-specific tools needing domain knowledge

How to design:

• Spotlight specific UI elements (dim rest of page)
• Keep steps short (3-7 steps max per tour)
• Allow users to click through tour freely
• Include "Skip tour" option
• Make replayable (help menu)

Best practices:

• Interactive > passive (let users click real buttons)
• Focus on workflow, not features ("Create a project" not "This is the project button")
• Provide sample data so actions work

Interactive Tutorials

When to use:

• Users need hands-on practice
• Concepts are complex or unfamiliar
• High stakes (better to practice in safe environment)

How to design:

• Sandbox environment with sample data
• Clear objectives ("Create a chart showing sales by region")
• Step-by-step guidance
• Validation (confirm they did it right)
• Graduation moment (you're ready!)

Documentation & Help

In-product help:

• Contextual help links throughout interface
• Keyboard shortcut reference
• Search-able help center
• Video tutorials for complex workflows

Help patterns:

• ? icon near complex features
• "Learn more" links in tooltips
• Keyboard shortcut hints (⌘K shown on search box)

Empty State Design

Every empty state needs:

What Will Be Here

"Your recent projects will appear here"

Why It Matters

"Projects help you organize your work and collaborate with your team"

How to Get Started

[Create project] or [Import from template]

Visual Interest

Illustration or icon (not just text on blank page)

Contextual Help

"Need help getting started? [Watch 2-min tutorial]"

Empty state types:

• First use: Never used this feature (emphasize value, provide template)
• User cleared: Intentionally deleted everything (light touch, easy to recreate)
• No results: Search or filter returned nothing (suggest different query, clear filters)
• No permissions: Can't access (explain why, how to get access)
• Error state: Failed to load (explain what happened, retry option)

Implementation Patterns

Technical approaches:

Tooltip libraries: Tippy.js, Popper.js Tour libraries: Intro.js, Shepherd.js, React Joyride Modal patterns: Focus trap, backdrop, ESC to close Progress tracking: LocalStorage for "seen" states Analytics: Track completion, drop-off points

Storage patterns:

// Track which onboarding steps user has seen
localStorage.setItem('onboarding-completed', 'true');
localStorage.setItem('feature-tooltip-seen-reports', 'true');

IMPORTANT: Don't show same onboarding twice (annoying). Track completion and respect dismissals.

NEVER:

• Force users through long onboarding before they can use product
• Patronize users with obvious explanations
• Show same tooltip repeatedly (respect dismissals)
• Block all UI during tour (let users explore)
• Create separate tutorial mode disconnected from real product
• Overwhelm with information upfront (progressive disclosure!)
• Hide "Skip" or make it hard to find
• Forget about returning users (don't show initial onboarding again)

Verify Onboarding Quality

Test with real users:

• Time to completion: Can users complete onboarding quickly?
• Comprehension: Do users understand after completing?
• Action: Do users take desired next step?
• Skip rate: Are too many users skipping? (Maybe it's too long/not valuable)
• Completion rate: Are users completing? (If low, simplify)
• Time to value: How long until users get first value?

Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.

Shared References

Reference: typography.md

Typography

Classic Typography Principles

Vertical Rhythm

Your line-height should be the base unit for ALL vertical spacing. If body text has line-height: 1.5 on 16px type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.

Modular Scale & Hierarchy

The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.

Use fewer sizes with more contrast. A 5-size system covers most needs:

Role	Typical Ratio	Use Case
xs	0.75rem	Captions, legal
sm	0.875rem	Secondary UI, metadata
base	1rem	Body text
lg	1.25-1.5rem	Subheadings, lead text
xl+	2-4rem	Headlines, hero text

Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.

Readability & Measure

Use ch units for character-based measure (max-width: 65ch). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.

Non-obvious: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05-0.1 to your normal line-height.

Font Selection & Pairing

Choosing Distinctive Fonts

Avoid the invisible defaults: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal—but if you want distinctive design, look elsewhere.

Better Google Fonts alternatives:

• Instead of Inter → Instrument Sans, Plus Jakarta Sans, Outfit
• Instead of Roboto → Onest, Figtree, Urbanist
• Instead of Open Sans → Source Sans 3, Nunito Sans, DM Sans
• For editorial/premium feel → Fraunces, Newsreader, Lora

System fonts are underrated: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.

Pairing Principles

The non-obvious truth: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).

When pairing, contrast on multiple axes:

• Serif + Sans (structure contrast)
• Geometric + Humanist (personality contrast)
• Condensed display + Wide body (proportion contrast)

Never pair fonts that are similar but not identical (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.

Web Font Loading

The layout shift problem: fonts load late, text reflows, and users see content jump. Here's the fix:

/* 1. Use font-display: swap for visibility */
@font-face {
  font-family: 'CustomFont';
  src: url('font.woff2') format('woff2');
  font-display: swap;
}

/* 2. Match fallback metrics to minimize shift */
@font-face {
  font-family: 'CustomFont-Fallback';
  src: local('Arial');
  size-adjust: 105%;        /* Scale to match x-height */
  ascent-override: 90%;     /* Match ascender height */
  descent-override: 20%;    /* Match descender depth */
  line-gap-override: 10%;   /* Match line spacing */
}

body {
  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
}

Tools like Fontaine calculate these overrides automatically.

Modern Web Typography

Fluid Type

Fluid typography via clamp(min, preferred, max) scales text smoothly with the viewport. The middle value (e.g., 5vw + 1rem) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.

Use fluid type for: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.

Use fixed rem scales for: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI — fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.

OpenType Features

Most developers don't know these exist. Use them for polish:

/* Tabular numbers for data alignment */
.data-table { font-variant-numeric: tabular-nums; }

/* Proper fractions */
.recipe-amount { font-variant-numeric: diagonal-fractions; }

/* Small caps for abbreviations */
abbr { font-variant-caps: all-small-caps; }

/* Disable ligatures in code */
code { font-variant-ligatures: none; }

/* Enable kerning (usually on by default, but be explicit) */
body { font-kerning: normal; }

Check what features your font supports at Wakamai Fondue.

Typography System Architecture

Name tokens semantically (--text-body, --text-heading), not by value (--font-size-16). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.

Accessibility Considerations

Beyond contrast ratios (which are well-documented), consider:

• Never disable zoom: user-scalable=no breaks accessibility. If your layout breaks at 200% zoom, fix the layout.
• Use rem/em for font sizes: This respects user browser settings. Never px for body text.
• Minimum 16px body text: Smaller than this strains eyes and fails WCAG on mobile.
• Adequate touch targets: Text links need padding or line-height that creates 44px+ tap targets.

---

Avoid: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.

Reference: ux-writing.md

UX Writing

The Button Label Problem

Never use "OK", "Submit", or "Yes/No". These are lazy and ambiguous. Use specific verb + object patterns:

Bad	Good	Why
OK	Save changes	Says what will happen
Submit	Create account	Outcome-focused
Yes	Delete message	Confirms the action
Cancel	Keep editing	Clarifies what "cancel" means
Click here	Download PDF	Describes the destination

For destructive actions, name the destruction:

• "Delete" not "Remove" (delete is permanent, remove implies recoverable)
• "Delete 5 items" not "Delete selected" (show the count)

Error Messages: The Formula

Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".

Error Message Templates

Situation	Template
Format error	"[Field] needs to be [format]. Example: [example]"
Missing required	"Please enter [what's missing]"
Permission denied	"You don't have access to [thing]. [What to do instead]"
Network error	"We couldn't reach [thing]. Check your connection and [action]."
Server error	"Something went wrong on our end. We're looking into it. [Alternative action]"

Don't Blame the User

Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".

Empty States Are Opportunities

Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".

Voice vs Tone

Voice is your brand's personality—consistent everywhere. Tone adapts to the moment.

Moment	Tone Shift
Success	Celebratory, brief: "Done! Your changes are live."
Error	Empathetic, helpful: "That didn't work. Here's what to try..."
Loading	Reassuring: "Saving your work..."
Destructive confirm	Serious, clear: "Delete this project? This can't be undone."

Never use humor for errors. Users are already frustrated. Be helpful, not cute.

Writing for Accessibility

Link text must have standalone meaning—"View pricing plans" not "Click here". Alt text describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use alt="" for decorative images. Icon buttons need aria-label for screen reader context.

Writing for Translation

Plan for Expansion

German text is ~30% longer than English. Allocate space:

Language	Expansion
German	+30%
French	+20%
Finnish	+30-40%
Chinese	-30% (fewer chars, but same width)

Translation-Friendly Patterns

Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.

Consistency: The Terminology Problem

Pick one term and stick with it:

Inconsistent	Consistent
Delete / Remove / Trash	Delete
Settings / Preferences / Options	Settings
Sign in / Log in / Enter	Sign in
Create / Add / New	Create

Build a terminology glossary and enforce it. Variety creates confusion.

Avoid Redundant Copy

If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.

Loading States

Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.

Confirmation Dialogs: Use Sparingly

Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").

Form Instructions

Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.

---

Avoid: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.