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 FIRSTIf 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:
- IDENTIFY -- What UI pattern is this? (navigation, form, data table, modal, card, etc.)
- REFERENCE -- Consult the pattern in
pattern-libraries.md - TOKENS -- Confirm design tokens are established for this project (see
design-tokens.md) - ADOPT -- Apply the reference spacing, typography, layout, and interaction patterns
- ADAPT -- Modify only what the specific context necessitates
- 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:
| Token Category | What to Define | Why It Matters |
|---|---|---|
| Colors | Primary, secondary, neutral scale (50-950), semantic (error, success, warning, info) | Eliminates "random color" syndrome |
| Typography | Font family (max 2), size scale (xs through 4xl), weight scale (normal, medium, semibold, bold), line heights | Typography is 95% of visual quality |
| Spacing | Base unit (4px or 8px), scale (xs: 4px through 3xl: 64px) | Systematic spacing produces a professional feel |
| Border Radius | Scale: none, sm, md, lg, full | Ensures consistent component shapes |
| Shadows | 3-4 elevation levels (sm, md, lg, xl) | Establishes clear depth hierarchy |
| Breakpoints | sm (640px), md (768px), lg (1024px), xl (1280px) minimum | Responsive behavior from the start |
| Z-index | Scale: dropdown(10), sticky(20), modal(30), popover(40), toast(50) | Prevents z-index conflicts |
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.
| Anti-Pattern | Why It Looks Amateur | What Professionals Do |
|---|---|---|
| Erratic spacing | No grid system, gaps feel random, padding varies between sibling elements | Consume spacing tokens. Every gap is a token value. |
| Ad-hoc colors | Colors selected per-component, no unified palette, too many distinct hues | Define the complete palette FIRST. Every color references a token. |
| Disorganized typography | Mismatched sizes, inconsistent line heights, too many weights, weak hierarchy | Maximum 2 font families. Adhere to the type scale. Heading hierarchy is deliberate. |
| Flat visual hierarchy | Everything identical in size and weight, nothing draws the eye, impossible to scan | Primary actions are visually dominant. Secondary elements are subdued. Vary size, weight, color, contrast. |
| Inconsistent corners | Mix of sharp and rounded corners, varying border widths on similar elements | Define a border-radius scale. Same component type = same radius. |
| Placeholder content | "Lorem ipsum", "User Name", "Description here", "Item 1" | Use realistic content that demonstrates actual data shapes and lengths. |
| Missing interaction states | Buttons ignore the cursor, links are ambiguous, no keyboard focus ring | Define interaction states (hover, focus, active, disabled) for ALL interactive elements. |
| Center-everything layout | Default AI behavior: center all text, content, and sections | Use left-aligned layouts with proper grid. Center only intentionally (hero headlines, CTAs). |
| Uniform text walls | Every paragraph, label, and description uses the same font-size and weight | Vary weight and size. Labels are smaller and lighter. Headings are larger and bolder. Descriptions use muted color. |
| Missing non-happy states | Only "populated" UI exists, no skeleton loaders, no error messages | Design all states: empty, loading (skeleton), error, partial, success. |
| Oversized components | Buttons too tall, inputs too wide, cards fill the entire viewport | Use standard sizing. Buttons: 36-44px height. Inputs: 36-40px. Cards: constrain max-width. |
| No whitespace rhythm | Content crammed together or floating in excessive space | Sections have consistent vertical rhythm. Related items are close. Unrelated items have clear separation. |
| Gratuitous effects | Random gradients, shadows on everything, unnecessary animations | Effects serve purpose. Shadows indicate elevation. Gradients are subtle. Animations are functional. |
| Round-number spacing | Using 10px, 20px, 30px instead of a system | Use 4px or 8px base unit. Spacing values: 4, 8, 12, 16, 24, 32, 48, 64. |
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
| Rationalization | Truth |
|---|---|
| "It is just a prototype" | Prototypes become products. Professional prototypes use tokens too. |
| "I will fix the styling later" | You will not. "Later" never arrives. Every subsequent task takes priority. |
| "The user did not specify design requirements" | Absence of requirements is not permission to guess. Apply tokens by default. |
| "I need to get the logic working first" | Logic and presentation are not separate phases. Tokens take 5 minutes to establish. |
| "This component is too simple for all that" | Simple components are where inconsistency takes root. A button without tokens infects every page it touches. |
| "I will adopt a design system later" | Without tokens now, you will fight the design system later. Tokens make adoption trivial. |
| "Just one hardcoded color will not hurt" | One becomes ten. Then you have a palette of accidents. |
| "The AI can make it look acceptable" | "Acceptable" is the defining characteristic of amateur UI. Professional or amateur -- choose. |
Guardrails -- HALT and Reference
If you catch yourself doing any of the following:
- Writing
color: #3b82f6without it being a defined token value - Using
padding: 10pxinstead 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 categorydesign-tokens.md-- Ready-to-use token templates by project classification