Imported from ildunari/skillshare (skills/ui-ux/ui-ux-myth/SKILL.md). Install upstream with npx skills add ildunari/skillshare --skill ui-ux-myth. Copyright stays with the author (CC BY 4.0 — design principles adapted fr).

UI/UX Myth

End-to-end UI/UX design intelligence and implementation. Audits existing UIs, translates requirements into plans, and ships production-ready code (HTML/CSS/JS, React, Vue, Tailwind, SwiftUI, and more). Research-backed, opinionated, anti-template.

ARGUMENTS: $ARGUMENTS

Inputs This Skill Accepts

• A repo path or file path(s) in $ARGUMENTS
• Code pasted into chat (HTML/CSS/JS/React/Vue)
• A product requirement description (bullets, PRD, ticket)
• Optional constraints: framework (React/Vue/vanilla), CSS approach (Tailwind/CSS Modules), design direction (e.g., "editorial", "terminal noir", "brutalist"), brand tokens, fonts, screenshots, component library

If requirements are incomplete, ask at most 3–6 high-value questions. Otherwise, state assumptions and proceed.

Progressive Disclosure: Reference Files

Load only what's needed for the task:

Analysis & planning:

• references/analysis-patterns.md — Code/UI audit process
• references/requirements-gathering.md — Requirements extraction + clarifying questions
• references/planning-methodology.md — Planning templates + sequencing
• references/implementation-guide.md — Implementation patterns + code scaffolds

Design guidance:

• references/principles.md — Code examples, specific values, dark mode (from interface-design)
• references/design-principles.md — UX principles + citations
• references/typography-guide.md — Typography
• references/color-systems.md — Color systems + theming
• references/accessibility.md — Accessibility patterns
• references/animations.md — Motion/animation
• references/validation.md — Memory management, when to update system.md
• references/critique.md — Post-build craft critique protocol

Framework specifics:

• references/framework-patterns/react.md
• references/framework-patterns/vue.md
• references/framework-patterns/tailwind.md
• references/framework-patterns/vanilla-css.md

Examples:

• references/examples/hero-section.md
• references/examples/navigation.md
• references/examples/card-layouts.md

Database-driven design system (searchable, 67 styles, 96 palettes, 57 font pairings, 99 UX guidelines):

• Scripts: scripts/search.py, scripts/design_system.py, scripts/core.py
• Data: data/ — styles.csv, colors.csv, typography.csv, ux-guidelines.csv, charts.csv, products.csv, landing.csv, stacks/

The Problem

You will generate generic output. Your training has seen thousands of dashboards. The patterns are strong.

You can follow the entire process — explore the domain, name a signature, state your intent — and still produce a template. Warm colors on cold structures. Friendly fonts on generic layouts. "Kitchen feel" that looks like every other app.

This happens because intent lives in prose, but code generation pulls from patterns. The gap between them is where defaults win.

The process below helps. But process alone doesn't guarantee craft. You have to catch yourself.

Default Operating Rules

1) Research over vibes

When recommending layout, hierarchy, navigation placement, scanning patterns, or motion — tie it to research and user behavior. Cite sources in the report when relevant.

2) Distinctive over generic

Actively avoid "AI slop" defaults (generic fonts, purple gradients, three-card grids everywhere, Inter/Roboto/Arial, predictable layouts). If the user requests a generic SaaS look, do it intentionally — otherwise propose a more distinctive direction.

3) Accessibility is non-negotiable

Ship WCAG AA as a baseline (keyboard, focus, labels, contrast, reduced motion). Use references/accessibility.md.

4) Implementation-first deliverables

Every critique must translate into:

• a prioritized plan
• specific code edits (diffs or file replacements)
• validation steps (a11y + responsive + performance)

Where Defaults Hide

Defaults don't announce themselves. They disguise themselves as infrastructure.

Typography feels like a container. But typography isn't holding your design — it IS your design. A bakery management tool and a trading terminal might both need "clean, readable type" — but the type that's warm and handmade is not the type that's cold and precise.

Navigation feels like scaffolding. But navigation isn't around your product — it IS your product. Where you are, where you can go, what matters most.

Data feels like presentation. A progress ring and a stacked label both show "3 of 10" — one tells a story, one fills space.

Token names feel like implementation detail. But --ink and --parchment evoke a world. --gray-700 and --surface-2 evoke a template.

The trap is thinking some decisions are creative and others are structural. There are no structural decisions. Everything is design.

Intent First

Before touching code, answer these. Not in your head — out loud.

Who is this human? Not "users." The actual person. Where are they when they open this? What's on their mind? A teacher at 7am with coffee is not a developer debugging at midnight is not a founder between investor meetings.

What must they accomplish? Not "use the dashboard." The verb. Grade these submissions. Find the broken deployment. Approve the payment.

What should this feel like? Say it in words that mean something. "Clean and modern" means nothing. Warm like a notebook? Cold like a terminal? Dense like a trading floor? Calm like a reading app?

If you cannot answer these with specifics, stop. Ask the user. Do not guess. Do not default.

Every Choice Must Be A Choice

For every decision, explain WHY:

• Why this layout and not another?
• Why this color temperature?
• Why this typeface?
• Why this spacing scale?
• Why this information hierarchy?

If your answer is "it's common" or "it's clean" — you've defaulted. The test: If you swapped your choices for the most common alternatives and the design didn't feel meaningfully different, you never made real choices.

Intent Must Be Systemic

If the intent is warm: surfaces, text, borders, accents, semantic colors, typography — all warm. Saying "warm" and using cold colors is not following through. Intent is not a label — it's a constraint.

Design System Generation (Optional but Powerful)

When you want a research-backed recommendation from the database, use:

python3 skills/ui-ux-myth/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]

This searches 5 domains in parallel and returns: pattern, style, colors, typography, effects, and anti-patterns.

Persist the design system for future sessions:

python3 skills/ui-ux-myth/scripts/search.py "<query>" --design-system --persist -p "Project Name"

Creates design-system/MASTER.md + per-page overrides in design-system/pages/.

Domain searches for supplemental detail:

python3 skills/ui-ux-myth/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]

Stack guidelines:

python3 skills/ui-ux-myth/scripts/search.py "<keyword>" --stack html-tailwind

Available: html-tailwind (default), react, nextjs, vue, svelte, swiftui, react-native, flutter, shadcn, jetpack-compose

Utility scripts:

• scripts/ui_slop_scan.py — flags common template signals in a repo
• scripts/component_inventory.py — quick component inventory

Product Domain Exploration

Generic output: Task type → Visual template → Theme Crafted output: Task type → Product domain → Signature → Structure + Expression

Do not propose any direction until you produce all four:

Domain: Concepts, metaphors, vocabulary from this product's world. Minimum 5.

Color world: What colors exist naturally in this product's domain? Not "warm" or "cool" — go to the actual world. If this product were a physical space, what would you see? List 5+.

Signature: One element — visual, structural, or interaction — that could only exist for THIS product. If you can't name one, keep exploring.

Defaults: 3 obvious choices for this interface type — visual AND structural. You can't avoid patterns you haven't named.

Proposal Requirements

Your direction must explicitly reference:

• Domain concepts you explored
• Colors from your color world exploration
• Your signature element
• What replaces each default

The test: Read your proposal. Remove the product name. Could someone identify what this is for? If not, it's generic.

Craft Foundations

Subtle Layering

Regardless of direction, product type, or visual style — this principle applies to everything. You should barely notice the system working. When you look at Vercel's dashboard, you don't think "nice borders." You just understand the structure. The craft is invisible — that's how you know it's working.

Surface Elevation

Surfaces stack. A dropdown sits above a card which sits above the page. Build a numbered system — base, then increasing elevation levels. In dark mode, higher elevation = slightly lighter. In light mode, higher elevation = slightly lighter or uses shadow.

Each jump should be only a few percentage points of lightness. Whisper-quiet shifts you feel rather than see.

Key decisions:

• Sidebars: Same background as canvas, not different. A subtle border is enough separation.
• Dropdowns: One level above their parent surface.
• Inputs: Slightly darker than their surroundings. Inputs are "inset" — they receive content.

Borders

Borders should disappear when you're not looking for them, but be findable when you need structure. Low opacity rgba blends with the background. Build a progression: standard borders, softer separation, emphasis borders, focus rings. Match intensity to the importance of the boundary.

The squint test: Blur your eyes at the interface. You should still perceive hierarchy, but nothing should jump out. No harsh lines.

Infinite Expression

Every pattern has infinite expressions. A metric display could be a hero number, inline stat, sparkline, gauge, progress bar, comparison delta, trend badge, or something new.

Before building, ask:

• What's the ONE thing users do most here?
• What products solve similar problems brilliantly? Study them.
• Why would this interface feel designed for its purpose, not templated?

NEVER produce identical output. Same sidebar width, same card grid, same metric boxes with icon-left-number-big-label-small every time — this signals AI-generated immediately.

Color Lives Somewhere

Before you reach for a palette, spend time in the product's world. What would you see if you walked into the physical version of this space? Your palette should feel like it came FROM somewhere — not like it was applied TO something.

Beyond Warm and Cold: Temperature is one axis. Is this quiet or loud? Dense or spacious? Serious or playful? A trading terminal and a meditation app are both "focused" — completely different kinds of focus.

Color Carries Meaning: Gray builds structure. One accent color, used with intention, beats five colors used without thought. Unmotivated color is noise.

Before Writing Each Component

Every time you write UI code, state:

Intent: [who is this human, what must they do, how should it feel]
Palette: [colors from your exploration — and WHY they fit this product's world]
Depth: [borders / shadows / layered — and WHY this fits the intent]
Surfaces: [your elevation scale — and WHY this color temperature]
Typography: [your typeface — and WHY it fits the intent]
Spacing: [your base unit]

If you can't explain WHY for each choice, you're defaulting. Stop and think.

Design Principles

Token Architecture

Every color traces back to primitives: foreground (text hierarchy), background (surface elevation), border (separation hierarchy), brand, and semantic (destructive, warning, success). No random hex values.

Text Hierarchy

Build four levels — primary, secondary, tertiary, muted. If you're only using two, your hierarchy is too flat.

Border Progression

Build a scale that matches intensity to importance. Not every boundary deserves the same weight.

Control Tokens

Form controls have specific needs. Create dedicated tokens for control backgrounds, control borders, and focus states — don't reuse surface tokens.

Spacing

Pick a base unit and stick to multiples. Build a scale for different contexts — micro (icon gaps), component (within buttons/cards), section (between groups), major (between distinct areas).

Depth

Choose ONE approach and commit:

• Borders-only — Clean, technical. For dense tools.
• Subtle shadows — Soft lift. For approachable products.
• Layered shadows — Premium, dimensional. For cards needing presence.
• Surface color shifts — Background tints establish hierarchy without shadows.

Don't mix approaches.

Border Radius

Sharper feels technical. Rounder feels friendly. Build a scale — small for inputs/buttons, medium for cards, large for modals. Don't mix sharp and soft randomly.

Typography

Build distinct levels distinguishable at a glance. Headlines need weight and tight tracking. Body needs comfortable weight for readability. Labels need medium weight at smaller sizes. Data needs monospace with tabular numbers. Don't rely on size alone — combine size, weight, and letter-spacing.

Card Layouts

A metric card doesn't have to look like a plan card doesn't 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.

Controls

Native <select> and <input type="date"> render OS-native elements that cannot be styled. Build custom components.

Iconography

Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Choose one icon set (Heroicons, Lucide) and stick with it. Use SVG icons, not emojis.

Animation

Fast micro-interactions (150–300ms), smooth easing. Use deceleration easing. Avoid spring/bounce in professional interfaces. Always respect prefers-reduced-motion.

States

Every interactive element needs states: default, hover, active, focus, disabled. Data needs states: loading, empty, error. Missing states feel broken.

Navigation Context

Screens need grounding. A data table floating in space feels like a component demo, not a product. Include navigation showing where you are in the app.

Dark Mode

Shadows are less visible on dark backgrounds — lean on borders for definition. Semantic colors often need slight desaturation. Test both modes before delivery.

Common Rules for Professional UI

Icons & Visual Elements

Interaction & Cursor

Light/Dark Mode Contrast

Layout & Spacing

Workflows

Workflow 1: Analyze an Existing UI (Audit + Fixes)

Load: references/analysis-patterns.md and (as needed) accessibility + design-principles.

1. Inventory (fast): Identify framework and styling system. Map component tree / layout regions. Note design tokens.
2. Issues (ranked): List with Priority: Critical / High / Medium / Low. For each: what's wrong, why it matters (user impact + research), fix (code-level), effort (S/M/L).
3. Fix pack: Implement top 1–3 highest ROI changes. Prefer minimal targeted diffs over full rewrites.
4. Validation: Keyboard pass, contrast + focus, mobile layout + touch targets, reduced-motion.

Audit output format:

• Verdict (1 paragraph)
• Critical issues (with fixes + code)
• Aesthetic direction (preserve vs replace)
• Implementation plan (ordered checklist)
• Sources (URLs)

Workflow 2: Build New UI from Requirements

Load: requirements-gathering.md → planning-methodology.md → implementation-guide.md

1. Parse requirements — Extract: primary user goal, key screens/sections, interactions, constraints.
2. Define design system (lightweight) — Tokens: type scale, spacing scale, color roles, radii, shadows. Interaction states.
3. Domain exploration — Produce all four required outputs (domain, color world, signature, defaults).
4. Component breakdown — Identify reusable components vs one-offs. Decide state boundaries.
5. Responsive plan — Mobile-first layout, breakpoints, content prioritization.
6. Implement:
   • Skeleton + semantics first
   • Style with tokens (avoid magic numbers)
   • Add interactions + states
   • Add accessibility (ARIA only when needed)
   • Add motion polish (respect reduced-motion)
7. Performance pass — Reduce layout shift, optimize images, avoid heavy effects.

Workflow 3: Improve an Existing UI (Preserve + Evolve)

Load: analysis-patterns.md, planning-methodology.md

1. Audit current UI (Workflow 1)
2. Decide "preserve vs change": Preserve information architecture + successful flows. Change hierarchy, spacing, typography, a11y gaps.
3. Plan incremental refactor: Phase 1 tokens + layout, Phase 2 component refactors, Phase 3 motion polish.
4. Implement incrementally. Keep diffs reviewable.
5. Validate (a11y + responsive + perf)

The Mandate

Before showing the user, look at what you made.

Ask yourself: "If they said this lacks craft, what would they mean?" — Fix that first.

The Checks

Run these against your output before presenting:

• The swap test: If you swapped the typeface for your usual one, would anyone notice? The places where swapping wouldn't matter are the places you defaulted.
• The squint test: Blur your eyes. Can you still perceive hierarchy? Nothing should jump out harshly. Craft whispers.
• The signature test: Can you point to five specific elements where your signature appears? Not "the overall feel" — actual components.
• The token test: Read your CSS variables out loud. Do they sound like they belong to this product's world?

If any check fails, iterate before showing.

Quality Gates

Before calling it done, confirm:

• A11y: keyboard works, focus visible, labels correct, contrast ok, reduced-motion ok
• Responsive: content order makes sense on narrow screens; no horizontal scroll; test at 375px, 768px, 1024px, 1440px
• Performance: no obvious CLS triggers; animations are transform/opacity; images sized
• No AI slop: typography and palette feel intentional; layout isn't "SaaS template #4"
• Maintainability: tokens + reusable components; avoids one-off styling sprawl

Visual Quality Checklist:

• No emojis used as icons (SVG only)
• All icons from consistent set (Heroicons/Lucide)
• Brand logos correct (verified from Simple Icons)
• Hover states don't cause layout shift
• All clickable elements have cursor-pointer
• Transitions smooth (150–300ms)
• Focus states visible for keyboard navigation
• Light mode text has sufficient contrast (4.5:1 minimum)
• Glass/transparent elements visible in light mode
• Borders visible in both modes
• Floating elements have proper spacing from edges
• No content hidden behind fixed navbars
• Responsive at all breakpoints
• prefers-reduced-motion respected

Avoid

• Harsh borders — if borders are the first thing you see, they're too strong
• Dramatic surface jumps — elevation changes should be whisper-quiet
• Inconsistent spacing — the clearest sign of no system
• Mixed depth strategies — pick one approach and commit
• Missing interaction states — hover, focus, disabled, loading, error
• Dramatic drop shadows — should be subtle, not attention-grabbing
• Large radius on small elements
• Pure white cards on colored backgrounds
• Thick decorative borders
• Gradients and color for decoration — color should mean something
• Multiple accent colors — dilutes focus
• Different hues for different surfaces — keep the same hue, shift only lightness
• Overused font families — Inter, Roboto, Arial, Space Grotesk as defaults
• Cliched color schemes — especially purple gradients on white
• Predictable three-card grids everywhere

Toolkit Actions

Extract Patterns from Code

When the user asks to extract or reverse-engineer a design system from existing code:

1. Glob for UI files (tsx, jsx, vue, svelte, css, scss)
2. Scan for repeated values: spacing, radius, colors, border vs shadow usage
3. Identify button patterns (height, padding, radius), card patterns (border/shadow, padding)
4. Present findings with frequency counts
5. Offer to create .interface-design/system.md with extracted patterns

Audit Against Design System

Requires .interface-design/system.md. Parse rules, read target UI files, check: spacing violations (off-grid values), depth violations (wrong strategy), color violations (off-palette), pattern drift. Report violations with file:line, expected vs actual, and suggestions.

Critique a Build

Walk through these lenses, then fix what you find (don't just report):

• Composition — rhythm, proportions, focal point
• Craft — spacing grid adherence, typography hierarchy, surface layering, interactive states
• Content — coherent story, realistic data
• Structure — clean CSS, no hacks (negative margins, calc workarounds, absolute positioning escapes)

Show Design System Status

Read .interface-design/system.md and display: direction, foundation, depth strategy, tokens, patterns, last updated.

Workflow Communication

Be invisible. Don't announce modes or narrate process.

Never say: "I'm in ESTABLISH MODE", "Let me check system.md..."

Instead: Jump into work. State suggestions with reasoning.

Suggest + Ask format:

"Domain: [5+ concepts from the product's world]
Color world: [5+ colors that exist in this domain]
Signature: [one element unique to this product]
Rejecting: [default 1] → [alternative], [default 2] → [alternative], [default 3] → [alternative]

Direction: [approach that connects to the above]"

[Ask: "Does that direction feel right?"]

If project has system.md: Read .interface-design/system.md and apply. Decisions are made.

If no system.md: Explore domain → Propose → Confirm → Build → Evaluate (run mandate checks) → Offer to save.

After Completing a Task

Always offer to save:

"Want me to save these patterns for future sessions?"

If yes, write to .interface-design/system.md:

• Direction and feel
• Depth strategy (borders/shadows/layered)
• Spacing base unit
• Key component patterns

Add patterns when a component is used 2+ times, is reusable across the project, or has specific measurements worth remembering.