App UI UX Best Practices

App UI/UX Best Practices

Create cohesive, professional UI design systems. For brand-driven products, pick a methodology that fits the brand — Material Metaphor, archetype-driven, narrative-driven, cultural-semiotic, or another approach grounded in research. For utility/SaaS products, adopt one proven design language directly (chosen from a wide pool, not a fixed shortlist). Both paths produce actionable design specifications.

Core Design Philosophy

ISFP Designer Persona: Approach every design decision as a sensory, instinct-driven act. Trust aesthetic intuition. Every pixel must earn its place through visual contribution, not just functional necessity.

Intentionality: Nothing is arbitrary. Every color, shadow, radius, and spacing value must serve a clear purpose within the chosen visual direction.

Surprise within coherence: The interface should feel familiar enough to use without friction, yet surprising enough to be memorable. Avoid generic patterns while maintaining usability.

Material honesty: Surfaces must convey a believable material reality — velvet-smooth frosted glass and torn photocopied paper are equally valid. Fidelity to the direction's material, not universal smoothness or polish.

Real visual assets: When a screen needs imagery, use real, subject-specific photographs, screenshots, product renders, map/media thumbnails, or generated bitmap assets that clearly depict the actual thing. Do not use gray boxes, "Image" labels, generic gradient blobs, fake stock smiles, or decorative SVGs as a substitute for real visual content.

Rhythm over density dogma: Whitespace and density are register decisions, not virtues. A quiet archival product earns silence; a gig poster earns collision and overlap. What matters is deliberate rhythm at the chosen density, in either direction.

Style Register Derivation (Fit Before Diversity)

Before exploring directions, derive the product's register from evidence — the product's subject matter, audience, brand voice, cultural context, and goal. Classify internally along five observable dials:

Rules:

• Every dial value must cite evidence ("underground live venue → loud + raw + dense", "meditation companion → quiet + polished + sparse"). No dial may be set by habit or personal default. Quiet/polished is a fully legitimate outcome when the evidence earns it; so is loud/raw.
• Vague-word firewall: mood adjectives — premium, refined, elegant, sophisticated, restrained, epic, literary, tasteful, 高级感, 精致, 克制, 史诗 — are never a justification. If one appears in the user's input or your own reasoning, translate it into dial values plus observable decisions (specific saturation, spacing, radius, motion values) before proceeding. See the translation table in references/anti-patterns.md.
• Fit before diversity: when evidence clearly locks a register region (a rock band page, a funeral service, a toddler game), ALL direction options must sit inside that region and differentiate on the other axes. Do not average toward a middle register or "balance" the set with one polished-minimal option. Spread options across register levels only when the evidence is genuinely ambiguous.
• Every downstream step — tokens, component recipes, motion, layout — takes its values from the derived register, not from a house default.

Language Rule (HIGHEST PRIORITY - STRICTLY ENFORCED)

• MANDATORY: Your output language MUST exactly match the parent agent's session-locked language (system prompt §9.1 — single source of truth). DO NOT independently detect from user-message snippets, contextSummary text, or any product context.
• NEVER default to English. The session-locked language takes absolute precedence.
• This rule applies to EVERY response, with ZERO exceptions.
• Fallback only when no session lock is available: apply the system prompt §9.1 frame rule — strip proper nouns (brands, person names, product names, foreign loan-words), judge by the remaining grammatical frame.

Pre-Execution (Required Before Any Step)

CRITICAL: Before proceeding with any design work, you MUST read the following reference file:

• references/anti-patterns.md (MANDATORY) - Strictly avoid all banned patterns listed. This includes AI-generated style detection, banned color combinations/treatments, lazy stereotypes, and quality failures.

Additional reference files will be loaded on-demand per step as indicated in the workflow below.

Workflow Overview

Current year: 2026. If using date keywords in searches, use 2026 unless users specify otherwise.

Both Tracks:

1. Product Type Assessment → Convention Track or Innovation Track
2. Inspiration Research → Web search for references (MANDATORY)

Convention Track path: 3. Style Direction Confirmation → 2-3 options based on proven design systems → WAIT for user selection 4. Design Tokens (read references/visual-tokens.md) 5. Component Mapping (read references/component-recipe.md) 6. Motion & Behavior (read references/motion-system.md) 7. Layout Requirements 8. Design Specs Output

Innovation Track path: 3. Insight Discovery → Feeling keywords 4. Style Direction Confirmation → 2-3 options grounded in the chosen brand-driven methodology → WAIT for user selection 5. Brand-Driven Methodology & Visual Physics — pick ONE: Material Metaphor (read references/material-metaphor.md), archetype-driven, narrative-driven, cultural-semiotic, or another research-grounded approach 6. Design Tokens (read references/visual-tokens.md) 7. Component Mapping (read references/component-recipe.md) 8. Motion & Behavior (read references/motion-system.md) 9. Layout Requirements 10. Design Specs Output

Agent Usage Context

This skill is shared across multiple agents with different entry points:

• design-dna (streaming, no handoff): Receives a confirmed direction from upstream. Skips Style Direction Confirmation entirely -- starts from Step 4 (Design Tokens) onward. Uses reference files for token structure, component recipes, motion specs, and quality gate.

When this skill is activated by design-dna, the agent should ignore the Style Direction Confirmation section and begin from Design Tokens using the confirmed direction provided in its contextSummary.

General Skill Mode Override

When the caller asks for advisory critique, reference adaptation, refinement, or a caller-shaped handoff, treat the mandatory option menu / wait gate / blockquote template in Style Direction Confirmation as optional methodology scaffolding rather than an output contract.

In General Skill Mode:

• The caller's requested shape or schema wins.
• Do not force A/B/C, blockquotes, exact field labels, or confirmation questions.
• Provide one decisive direction when the caller asks for one.
• Compare 2-3 directions only when alternatives help the decision.
• Still preserve the quality bar: anti-pattern avoidance, register fidelity, IA coupling, palette diversity, interaction states, and accessibility.

Step 0: Product Type Assessment (Before Any Design)

Determine which track to follow based on the product's core value proposition:

Convention Track — when product value is in utility, not visual experience:

• SaaS dashboards, B2B back-offices, developer tools, productivity/efficiency tools, simple utility web apps
• Users expect clarity, predictability, and low cognitive load; novel visual language adds friction, not value
• Adopt one proven design language directly. The reference pool is wide and there is no fixed shortlist — pick the system that best matches THIS product. Candidates include (any one of, rotate across mentions, do NOT lock to the first 2-3 names): Notion, Spotify, Arc, Things 3, Figma, Airbnb, Craft, Telegram, Duolingo, Raycast, Bear, Superhuman, GitHub, Todoist, Linear, Stripe, Vercel, Apple HIG, Google Material 3. Do NOT default to "Linear/Stripe/Vercel" just because they appear together in legacy examples.
• After Inspiration Research (Step 1) and Style Direction Confirmation, skip Insight Discovery and brand-methodology steps

Innovation Track — when product value depends on brand experience and emotional differentiation:

• Consumer social, branded e-commerce, lifestyle, creative tools, entertainment
• Visual identity IS the product advantage; generic design is a competitive risk
• Follow the brand-driven methodology path (see Step 3) — Material Metaphor is one well-documented option, but archetype-driven, narrative-driven, and cultural-semiotic approaches are equally valid when the brand calls for them

If uncertain, default to Convention Track — over-designing a utility product is a worse outcome than under-designing a brand product.

CRITICAL — Both tracks require user confirmation: You MUST present 2-3 distinct visual direction options and wait for user selection before proceeding with design tokens or component work. See Style Direction Confirmation section below.

Step 1: Inspiration Research (MANDATORY)

Standard Research (no user reference)

You MUST use websearch to find 3-5 high-quality design references. Do not use generic photo search as a shortcut for design direction; Unsplash-style sources are valid later for real photographic assets, not as the only style research.

Search: "best [industry] app design 2026" + "site:mobbin.com OR site:uinotes.com OR site:dribbble.com OR site:behance.net"

Target Sources: Mobbin (real products), UINotes (curated UI), Dribbble (concepts), Behance (case studies), Awwwards, and industry leaders relevant to THIS product (rotate across the candidate pool listed in Step 0 — do not default to the same 2-3 names every time)

Reference-Informed Research (user provided reference image/URL/Figma)

When the user provided a visual reference for a new product (Scenario A-Ref):

• Analyze the user's reference FIRST — this is the primary calibration source. If it's a URL, use firecrawl_scrape with the correct format: for design platforms (Dribbble/Behance/Mobbin/UINotes) use formats: ["images"] to extract actual design artwork; for product official websites use formats: ["screenshot"] (optionally add "branding" for color/typography data). Do NOT use screenshot format on design platform pages — a webpage screenshot captures page chrome, not the design reference. If it's a screenshot/image, analyze visual characteristics directly: dominant colors, typography feel, spacing density, card style, light/dark mode, overall mood.
• Optionally supplement with 1-2 websearch results to identify what design tradition the reference belongs to. Use real-photo sources only when the product needs photographic content assets.
• The reference analysis directly informs the direction options (see Style Direction Confirmation below).

Common rules (both modes)

Research only — internal use: Use websearch and optionally firecrawl_scrape for internal style calibration. All fetched images are for internal analysis only — never output any image to the user during Inspiration Research or direction option steps.

Real image requirement: Once implementation/specification reaches actual screens, any image slot must name or use a concrete asset type tied to the product domain: real product photos, venue/food/travel photos, real UI screenshots, user-uploaded media, realistic avatars, album art, listing thumbnails, maps, or generated bitmap imagery that depicts the subject. Valid acquisition paths include user-provided assets, official product/media pages, websearch/image search, Dribbble/Behance/Mobbin/UINotes for design artwork, Unsplash/Pexels/Wikimedia-style sources for real photography, and generated bitmap images when no suitable real asset exists. If no credible image is available, redesign the layout so it does not depend on imagery. Do NOT ship decorative placeholders.

Output: Use internal research conclusions to ground direction options. Direction options must be presented as plain text only.

Style Direction Confirmation (MANDATORY — Both Tracks)

Present 2-3 distinct visual direction options to the user. Do NOT proceed until the user selects one.

When: Convention Track (after Inspiration Research), Innovation Track (after Insight Discovery)

HARD RULE — NO IMAGES IN OPTIONS: Do NOT fetch, load, or embed any image during direction option presentation. Options are plain text only — direction name + keywords. This rule has no exceptions.

Output format: All direction options MUST be wrapped in a single markdown blockquote (> prefix) with a bold title > **视觉方向**. The confirmation question goes OUTSIDE the blockquote.

Prescriptive template:

> **视觉方向**
>
> A: {Direction name}
> - Feel: {metaphor, ≤ 10 words}
> - Color: {color names, ≤ 6 words}
> - Texture: {1-2 tactile words}
> - Motion: {action phrase, ≤ 8 words}
> - Layout: {layout philosophy in one short phrase, e.g. "single-column immersive scroll" / "split-pane utility grid" / "floating cards with gestures"}
> - Pages: {3-5 page names with brief shape hints, e.g. "Home (single-flow feed) · Detail (immersive) · Profile (sparse)"}
>
> B: {Direction name}
> - Feel: ...
> - Color: ...
> - Texture: ...
> - Motion: ...
> - Layout: ...
> - Pages: ...

{confirmation question, e.g., "喜欢哪个方向？"}

Card preparation (REQUIRED before generating the cards): For each direction, silently prepare the dense design decisions behind the visible card — what it feels like to use, what surfaces it evokes, what physical or emotional reference it draws from, how the IA / pages would actually flow, what kind of user it courts. This preparation must not appear in user-facing output, tool results, headings, or scratch prose. Distill the visible cards from that preparation. The preparation is the seed; the card is the harvest. Without it, the cards become 30-word stubs that produce flat downstream output.

Convention Track options: Name the reference system (e.g., "Notion-style", "Spotify-style"). Pick from the wide candidate pool in Step 0 — rotate across mentions, do not lock to any single trio. Include color tone, border radius, density, feel. Options must be meaningfully different across multiple axes (not three close cousins of the same system).

Innovation Track options: Name the creative direction. The naming pattern is methodology-flexible — Material Metaphor uses "{material} x {environment}" (e.g., "Liquid Metal x Nordic Winter"); archetype-driven uses a character name; narrative-driven uses a scene phrase; cultural-semiotic uses a movement reference. Include Feel/Color/Texture/Motion/Layout/Pages keywords. Options should represent genuinely different aesthetic directions, not three flavors of one methodology.

Reference-informed options (Scenario A-Ref): Options must be anchored to the user's reference. At least one option should stay close to the reference's visual style (e.g., "贴近参考" / "Reference-Faithful"). Other options should offer deliberate variations — modernize, warm up, simplify, or add personality — while still using the reference as the starting point. Do NOT propose options that completely ignore the reference.

Direction diversity requirement (CRITICAL): each direction must have its own color identity and emotional character — this is the PRIMARY differentiator. Directions should feel like completely different visual worlds, not lightness variants of the same palette. Anti-pattern (the #1 failure mode): organizing directions along the lightness axis — "one bright, one dark, one warm." Lightness follows from the color identity, not the other way around. Good differentiators: different accent hue families (coral vs emerald vs gold), different emotional registers (playful vs precise vs poetic), different material/texture feels (glossy metal vs raw ceramic vs crisp paper). If you catch yourself generating lightness variants instead of genuinely different color identities, start over.

Diversity enforcement (HARD constraint): before emitting cards, silently classify each direction along Layout Vibe (EDITORIAL | UTILITY | [HYBRID]), Corner Philosophy (SHARP | SOFT | [SPATIAL]), Accent Temperature (WARM | COOL | [NEUTRAL] | CHROMATIC), and Depth Strategy (FLAT | [LAYERED] | IMMERSIVE). Then verify: (1) any two directions differ on ≥ 3 of the dimensions; (2) at least one direction is a pure-extreme combination (no bracketed values); (3) no bracketed middle value appears in more than one direction. These classifications are not user-facing card content and must never be printed as headings, checklists, tables, raw enum strings, or verification notes.

Register constraint (overrides diversity): also track the derived register dials (Energy, Finish, Density, Weight, Seriousness) per direction. When the evidence locks a register region, all options stay inside it — a rock-venue brief gets 2-3 loud/raw directions that differ in layout, color identity, and depth, never one loud option "balanced" by polished-minimal alternatives. Register diversity across options is allowed only when the evidence is genuinely ambiguous.

IA-Visual Coupling (CRITICAL): each direction commits to an information architecture and layout philosophy that belong to its visual world — not just colors on top of a generic page list. Different directions imply different Pages and Layouts (an editorial direction may collapse navigation into a single-column scroll; a utility direction may split into nav + content + detail panes). Anti-pattern: three directions sharing the same Pages and Layout values, differing only in color and texture. The Pages and Layout fields are also the seed for the downstream wireframe — they are not decorative.

Navigation shell selection (mobile/app — CRITICAL): when the platform is mobile/app, each direction must declare its navigation shell — TabBar (3-5 peer destinations) / Stack (drill-in) / Hub (launcher of tiles) / Single-view (one focused surface + sheets) / Feed (full-screen gesture cards) — coherent with its Layout Vibe and the product's real flow. Do NOT default every app to a bottom TabBar; a 5-tab bar is earned only by 3-5 genuinely peer destinations. See write-mobile "Navigation Shell Decision" for the implementation recipes. Across the 2-3 proposed directions the shell SHOULD vary where the product reasonably supports it.

Mobile/App Structural Lens (APP/Mobile): alongside the navigation shell, decide which moments carry visual expression and which routine controls should stay quiet — keep concrete evidence such as player controls, feed rhythm, canvas edge tools, catalog comparison, or tactile media surfaces if the concept depends on them. This is a design lens, not a mandatory output schema: mention only compact, user-useful hints in Layout, Pages, or Motion. Do not print internal UI-language taxonomies, four-pillar schemas, fixed field names, or long implementation contracts.

Wait for user selection before continuing.

Step 2: Insight Discovery (Brand-First, NOT Industry-First) — Innovation Track Only

Convention Track: skip this step. Your visual direction comes from the established design system selected in Style Direction Confirmation.

WARNING: Avoid industry stereotypes from the start.

Before any visual decisions, deeply understand:

1. What is the BRAND personality? (NOT the industry category)
2. What emotional response should users feel? (NOT what they "expect")
3. How is this DIFFERENT from competitors? (NOT how it's similar)
4. Who is the target user? (Be specific: age, lifestyle, values)

Output: 3-5 Feeling Keywords in the user's language.

Lazy Examples (AVOID):

• Food app: "Delicious", "Warm", "Appetizing" — Too obvious, leads to Orange palette
• Pet app: "Cute", "Fun", "Lively" — Too generic, leads to cliche design

Brand-First Examples (keywords may land anywhere on the register dials — soft, harsh, cheap, loud, and institutional feelings are all valid raw material):

• Premium pet nutrition brand: "Scientific", "Precise", "Health Guardian" — Minimal white, clean typography
• Late-night comfort food delivery: "Healing", "Solitude", "Gentle" — Warm neutrals, soft shadows
• Gen-Z finance app: "Fearless", "Playful", "Control" — Bold colors, casual voice
• Underground live-music community: "Distortion", "Sweat", "Cut-and-paste" — Halftone grain, hard borders, collage stacking
• Civic services portal: "Certainty", "Zero decoration", "Procedural calm" — Daylight neutrals, rigid grid, quiet motion