touchine-ojo/ojo-design-skills/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:

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

Innovation Track path:

1. Insight Discovery → Feeling keywords
2. Style Direction Confirmation → 2-3 options grounded in the chosen brand-driven methodology → WAIT for user selection
3. 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
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

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.