ui-design

UI Design

Iron Law

START FROM THE USER TASK AND HIERARCHY; EVERY ELEMENT EARNS ITS PLACE. WCAG 2.2 AA IS THE FLOOR.

When to Use

• Building, changing, or reviewing any user-facing UI surface: layout, components, design systems, typography, color, motion, responsive behavior, forms, navigation, modals, custom controls, interactive states. Simple forms, single-page apps, and "just basic styling" all qualify; the polished-product threshold is too high a bar.
• Testing keyboard flow, focus order, screen-reader behavior, contrast, reduced motion, forced colors, or accessible names.

When NOT to Use

• Backend API shape; use api.
• Frontend runtime debugging or tests only; pair with proof and browser tooling.
• Performance profiling beyond UI design choices; use performance.

Rules

1. One screen has one visually dominant primary action and an information order that survives a squint test. Remove elements that do not improve comprehension, trust, or action.
2. Define the user task, state, and flow before choosing a framework, and choose existing framework or design-system patterns before inventing new ones.
3. A small token system covers spacing, type, color, radius, and motion. No stray one-off values in committed CSS.
4. Loading, empty, error, disabled, and success states are defined with the layout, not later.
5. Accessibility is a design input, not a later review pass. Native HTML controls and semantics come before ARIA: <button type="button"> for actions, <a href> for navigation, <nav> with links for site navigation, <dialog> with .showModal() for modals. Every interactive element has name, role, value, state, and keyboard behavior.
6. Focus is visible: at least a 2px outline at 3:1 contrast against both adjacent surfaces, with a transparent fallback for Forced Colors. Tab order follows DOM order; positive tabindex has no safe use. Focus is restored after a modal or overlay closes.
7. Color is never the only signal. Text and non-text contrast, target size, and reflow meet WCAG 2.2 AA. Reduced motion, forced colors, high contrast, and dark mode follow user preferences.
8. Forms have explicit labels, grouped controls, errors tied to fields, and no placeholder-only instructions. Dragging has a single-pointer alternative. Authentication never depends on a cognitive test.
9. Automated checks catch only part of the problem. Meaningful UI changes get manual keyboard testing, and custom controls, dialogs, menus, tabs, forms, and live updates get screen-reader testing. Remaining gaps are recorded as explicit blockers or deferred work, never left implicit.