elements-patterns - SKILL.md Agent Skill

name: elements-patterns description: > Practical guide for designing common UI elements and patterns. Covers navigation, input fields, forms, profiles, settings, lists and cards, detail views, sort and filter, tables, modals, and design systems. Use when designing any standard UI element or pattern. Trigger on: navigation, nav, input field, form, login, signup, profile, settings, list, card, table, modal, dialog, dropdown, checkbox, radio, toggle, tabs, search, filter, sort, detail view, pagination, design system, component.

Elements & Patterns

Every element is a stepping stone in the user's journey from point A to point B. Design each one through the lens of that experience.

Read references/elements-knowledge.md for detailed guidance on specific element types.

Universal Principles

Start with platform defaults

Before designing any element from scratch, look at how iOS (HIG) or the web (shadcn/Tailwind) handles it. Match the convention, then exceed it.

Consistency over creativity

A consistent set of "good" components beats a mix of some "great" and some "mediocre." Every element should feel like it belongs to the same family.

State coverage

Every interactive element needs ALL states designed:

Default, Hover, Focused/Active, Disabled, Error, Success, Loading
Empty states for lists, search results, data views
Skeleton/loading states for async content

Missing states is the fastest way to look amateur.

Navigation

Mobile: Bottom tab bar for 3-5 primary destinations. More than 5? Reconsider information architecture.
Web app: Sidebar for apps (collapsible), top bar for marketing sites.
Highlight the active state clearly — color, weight, or indicator mark.
Secondary navigation (settings, profile) can live in header icons rather than tabs.
Test navigation labels at realistic lengths — "Activity" fits, "Transaction History" might not.

Input Fields

The mighty input needs extensive design work:

Label: Top-aligned, 8px gap to field, same or slightly smaller size as input text
Placeholder: AA-large contrast (3:1) minimum — dark enough to read, light enough to not look pre-filled
Focus state: Unmistakable. 2px colored border is the standard.
Error state: Red border + icon + message. Color alone isn't accessible.
Helper text: Below the field, 2pt smaller than input text, AA contrast
Sizing: Match field width to expected content. Zip code doesn't need a full-width field.

Input variants to design

Default, hover, focused, filled, error, success, disabled, password (with show/hide), multiline, dropdown, prefixed, character count, checkboxes, radio buttons, toggles.

Lists and Cards

Lists: Best for scannable, text-heavy content. Consistent row height creates rhythm. Consider avatars, metadata, and right-side accessories.

Cards: Best for visual content, browsable collections. Consistent aspect ratios. Consider how they reflow at different screen sizes.

The key question: Does the user need to scan quickly (list) or browse visually (cards)?

Detail Views

Every list/card links to a detail view. Design the transition intentionally:

Standard slide: Simple, expected, efficient for most cases
Expanding card: Fun, exploratory (App Store pattern) — only for browsing contexts
Modal/sheet: For focused tasks that shouldn't lose parent context

On the detail view: expand what was truncated, add secondary information, provide actions that don't belong on the list view.

Modals

Modals are conversations — small, contained interruptions:

Clear title that states what will happen
Concise body providing context
Primary action that answers the title's question
Secondary action (cancel) for a clear escape
Overlay keeping parent visible but inaccessible

Copy is critical: "Delete this video?" → "Yes, delete" / "Cancel" — never ambiguous. If the button labels could be confusing ("Cancel" on a cancellation dialog), rewrite them.

Modal types

Alert: Demands attention before continuing (delete confirmation, low battery)
Action sheet: Contextual actions from a specific trigger (share, export options)
Popover: Small contextual panel near its trigger (formatting options, date picker)
Interstitial: Full-screen bridge between flows (check your email, onboarding step)

Tables

Summary altitude: 3-4 columns maximum. Details belong in detail view.
Sort indicators should be subtle but clear.
Use tabular-nums for all number columns.
Alternating row backgrounds: 1-2% contrast difference is sufficient.
Header text: lighter weight or smaller size than body rows.

Design Systems

When you've designed enough individual elements, systematize:

Document every component with all states
Establish naming conventions
Define spacing tokens, color tokens, type tokens
Make components composable — inputs that work inside cards inside modals
The system should make the next page faster to design, not slower