UX Patterns

UX Patterns

Overview

Never generate UI from assumptions. Always consult documented patterns first.

Core principle: Every UI element must trace to a documented UX pattern or design system component. If you cannot cite your reference, you are guessing -- and guessing produces amateur results.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO UI CODE WITHOUT A UX REFERENCE FIRST

If you have not identified the applicable pattern, you are not authorized to write the component. Wrote UI code without a reference? Remove it. Begin again with a reference.

No excuses:

• Do not "quickly prototype" without tokens
• Do not "come back and polish the styling later"
• Do not use arbitrary pixel values "just to get it working"
• Do not bypass the entry protocol for "trivial" components
• "Quick and dirty" UI always ships. It always ships.

When to Use

Always:

• Web applications (SaaS, dashboards, admin panels)
• Landing pages and marketing sites
• Game interfaces (menus, HUDs, inventories, shops)
• CLI interfaces (output formatting, interactive prompts)
• Mobile applications
• Component libraries
• Any visual output a human will perceive

Including:

• "It is just a prototype" (prototypes become products)
• "Nobody will see this" (someone always does)
• "I will polish it later" (you will not)

The Entry Protocol

digraph entry_protocol {
    rankdir=TB;
    start [label="Need to author UI code", shape=doublecircle];
    identify [label="IDENTIFY\nWhat UI pattern is this?", shape=diamond];
    reference [label="REFERENCE\nConsult pattern in\npattern-libraries.md", shape=box];
    tokens [label="TOKENS\nDesign tokens established?", shape=diamond];
    define_tokens [label="Establish tokens from\ndesign-tokens.md", shape=box];
    adopt [label="ADOPT\nApply reference spacing,\ntypography, layout", shape=box];
    adapt [label="ADAPT\nModify only what the\nspecific context demands", shape=box];
    write [label="Author UI code", shape=doublecircle];
    halt [label="HALT\nYou are guessing", shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    start -> identify;
    identify -> reference [label="identified"];
    identify -> halt [label="unknown\npattern"];
    reference -> tokens;
    tokens -> adopt [label="yes"];
    tokens -> define_tokens [label="no"];
    define_tokens -> adopt;
    adopt -> adapt;
    adapt -> write;
    halt -> identify [label="research\nfirst"];
}

BEFORE authoring ANY UI code, execute every phase:

1. IDENTIFY -- What UI pattern is this? (navigation, form, data table, modal, card, etc.)
2. REFERENCE -- Consult the pattern in pattern-libraries.md
3. TOKENS -- Confirm design tokens are established for this project (see design-tokens.md)
4. ADOPT -- Apply the reference spacing, typography, layout, and interaction patterns
5. ADAPT -- Modify only what the specific context necessitates
6. AUTHOR -- Only then write the UI code

Skip any phase = guessing. Remove and restart.

Design Token Requirements

Every UI project must define these tokens BEFORE any component code:

Consult design-tokens.md for ready-to-use token templates by project classification.

Pattern Lookup Methodology

digraph pattern_selection {
    rankdir=TB;
    what [label="What am I building?", shape=diamond];
    saas [label="SaaS / Dashboard /\nAdmin Panel?", shape=diamond];
    game [label="Game Interface?", shape=diamond];
    marketing [label="Landing Page /\nMarketing Site?", shape=diamond];
    devtool [label="Developer Tool /\nCLI?", shape=diamond];
    ecommerce [label="Online Store?", shape=diamond];

    use_saas [label="SaaS patterns\n(data-dense, navigation-heavy)", shape=box];
    use_game [label="Game UI patterns\n(dark theme, bold, animated)", shape=box];
    use_marketing [label="Marketing patterns\n(conversion-focused, hero sections)", shape=box];
    use_devtool [label="Dev tool patterns\n(monospace, high contrast, minimal)", shape=box];
    use_ecommerce [label="E-commerce patterns\n(product-focused, trust signals)", shape=box];
    use_general [label="General UI patterns\n(clean, accessible, standard)", shape=box];

    lookup [label="Consult specific component\nin pattern-libraries.md", shape=box];

    what -> saas;
    saas -> use_saas [label="yes"];
    saas -> game [label="no"];
    game -> use_game [label="yes"];
    game -> marketing [label="no"];
    marketing -> use_marketing [label="yes"];
    marketing -> devtool [label="no"];
    devtool -> use_devtool [label="yes"];
    devtool -> ecommerce [label="no"];
    ecommerce -> use_ecommerce [label="yes"];
    ecommerce -> use_general [label="no"];

    use_saas -> lookup;
    use_game -> lookup;
    use_marketing -> lookup;
    use_devtool -> lookup;
    use_ecommerce -> lookup;
    use_general -> lookup;
}

Consult pattern-libraries.md for the complete reference organized by project classification and pattern category.

Hallmarks of Amateur UI (Anti-Patterns)

These are the unmistakable signatures of AI-generated amateur UI. Every one represents a failure to consult references.

Component Validation Checklist

Before authoring any component, verify ALL items:

• Design tokens established for this project (colors, typography, spacing, radii, shadows)
• Pattern identified from pattern-libraries.md
• Spacing consumes token scale (no arbitrary px values)
• Typography consumes type scale (no arbitrary font-size)
• Colors drawn from defined palette (no hex literals)
• Border radius drawn from defined scale
• Hover/focus/active/disabled states defined for all interactive elements
• Responsive behavior specified for at least mobile and desktop
• Realistic content used (no placeholder text)
• Accessibility verified: contrast ratios (4.5:1 body text, 3:1 large text), aria labels, keyboard navigation
• Empty state designed
• Loading state designed (skeleton preferred over spinner)
• Error state designed

Cannot satisfy all items? You are not ready to author the component.

Cognitive Traps

Guardrails -- HALT and Reference

If you catch yourself doing any of the following:

• Writing color: #3b82f6 without it being a defined token value
• Using padding: 10px instead of a spacing token
• Choosing a font size not present in the type scale
• Building a component without consulting pattern-libraries.md
• Deferring hover/focus states "for now"
• Using "Lorem ipsum" or "Example text"
• Centering everything because "it looks fine"
• Adding a gradient or shadow "to make it pop"
• Writing CSS without design tokens established
• Building a form without consulting form patterns
• Creating a dashboard without consulting dashboard patterns

Every item means: HALT. Remove. Return to the entry protocol.

Integration

Invoked by:

• godmode:intent-discovery -- When design involves UI, invoke this skill
• godmode:task-planning -- Plans involving UI work should reference this skill
• godmode:delegated-execution -- UI implementation subagents MUST use this

Complementary skills:

• godmode:ui-engineering -- This provides the reference system; that provides implementation patterns
• godmode:design-integration -- For adopting existing design systems

Supporting files:

• pattern-libraries.md -- Complete pattern reference by project classification and category
• design-tokens.md -- Ready-to-use token templates by project classification