---
name: ui-ux-guidance
description: Use when planning, designing, implementing, or auditing UI/UX with IBR in Codex. Provides the latest compact IBR guidance for Calm Precision, web archetypes, interaction states, mobile, content states, data visualization, Mockup Gallery targets, and imagegen approval gates.
---

# IBR UI/UX Guidance

Use this before implementing non-trivial interface work. The goal is a testable design contract: what the UI is for, how it is structured, which guidance applies, and how it will be validated.

## Guidance Order

Apply guidance in this order:

1. User-stated requirements and existing project design system.
2. Approved Mockup Gallery targets.
3. Explicitly approved imagegen visual concepts.
4. Platform conventions: web, mobile web, iOS, macOS, or cross-platform.
5. Product archetype defaults.
6. Calm Precision structural rules.
7. Component patterns and local templates.
8. Data visualization guidance when charts, KPIs, dashboards, rankings, trends, or analytical search responses are present.

Do not let style references override functional integrity, accessibility, real data constraints, or platform conventions unless the user explicitly chooses that tradeoff.

## Web Archetypes

Classify the web surface before design:

| Archetype | Use for | Default bias |
|---|---|---|
| `saas-dashboard` | recurring product overview and operations | dense content grid, restrained chrome |
| `data-research-tool` | search, evidence review, source comparison | compact filters + provenance-first results |
| `editor-workbench` | artifact creation, builder, canvas, IDE-like tool | primary canvas/document + subordinate panels |
| `ai-agent-chat` | chat, task delegation, tool output, artifacts | conversation + execution/artifact state |
| `commerce-checkout` | purchase or conversion path | minimal steps, high trust, clear errors |
| `content-publication` | docs, editorial, marketing content | readable body, subordinate nav |
| `internal-admin` | CRUD, queues, moderation, support tooling | compact tables/lists, safe bulk actions |

If a screen looks like a dashboard but the main job is inspecting evidence, choose `data-research-tool`. If it looks like chat but the main job is editing an artifact, choose `editor-workbench`.

Detailed installed references live under `references/web-design/` when deeper guidance is needed.

## Calm Precision Core

- Exactly one L1 anchor per page.
- L2 navigation and controls must stay visually subordinate to L1.
- L3 primary content should occupy at least 60% of the mobile viewport.
- L4 support content must hide, collapse, or move below primary content on mobile.
- Related list items share one group border with internal dividers; avoid individual borders when the items are one scannable group.
- Content units use three-line hierarchy: title, description, metadata.
- Content-to-chrome ratio should be about 70/30 or better.
- Touch targets are at least 44px on mobile.
- Button labels are Verb + Object, 3 words or fewer.
- Status should usually be text color plus meaning, not filled badges.
- Non-functional controls must be hidden, disabled, marked as demo/coming soon, or backed by a real endpoint.
- Motion must communicate state or affordance and respect reduced motion.

## Target Roles

| Role | Meaning | Validation |
|---|---|---|
| `wireframe-target` | approved low-fidelity layout, flow, hierarchy | semantic/layout scan; no pixel-perfect match |
| `visual-target` | approved hi-fi visual target | `/ibr:match` plus screenshot review |
| `inspiration` | non-binding direction | no pass/fail |
| `data-reference` | content/data shape to implement | verify real source mapping |

Never implement unrated or rejected mockups as binding targets. Ask the user to approve one or proceed scratch-first.

## Imagegen Concepts

Use imagegen only for mood, style, hero/product imagery, or hi-fi visual variants. Generated images:

- are `inspiration` by default
- become `visual-target` only after explicit user approval
- are never `wireframe-target`
- do not replace text-accurate specs, accessibility semantics, interaction requirements, or validation evidence

## Interaction And State Design

Every interactive element needs a working action, real destination, or clear disabled/demo state.

Loading states:

| Wait | State |
|---|---|
| under 100ms | none |
| 100ms-1s | spinner or subtle pulse |
| 1s-3s | skeleton matching final structure |
| over 3s | progress or step status with specific copy |

Errors use what -> why -> fix. Empty states use context: first-time value + setup CTA, search broadening, filter reset with total count, or all-done next step.

## Mobile

- Start with mobile base styles; breakpoints add complexity.
- Inputs use at least 16px text to avoid iOS zoom.
- Primary actions are reachable and do not cover primary content.
- Tables become cards, pinned-key tables, or horizontal scroll with an overflow hint.
- Sidebars become bottom sheets, disclosures, or below-content sections.

## Data Visualization

Use a chart only when it reveals a pattern, comparison, trend, distribution, correlation, flow, density, balance, or attribution faster than text. Require at least 3 comparable data points unless showing a simple 2-part composition.

| Relationship | Preferred visual |
|---|---|
| single metric | KPI callout |
| trend | line or sparkline |
| ranking | horizontal bar |
| comparison | grouped bar |
| part-to-whole | stacked bar or small donut |
| correlation | scatter |
| attribution | waterfall |
| flow | funnel or ordered steps |
| density | heatmap |
| hierarchy | treemap |

Every chart needs an insight title, context line, visual, focal annotation when useful, and source attribution.

## Validation Contract

Before calling UI work done, choose the narrowest proof:

- `scan` for layout, styles, semantic state, a11y, handlers, and console issues
- `observe` for actionable controls
- `interact` or `interact_and_verify` for specific UI behavior
- `flow_search`, `flow_form`, or `flow_login` for task flows
- `match` for approved `visual-target`
- `native_scan` or `scan_macos` for native surfaces

Report remaining gaps explicitly when a tool cannot run.