Ui Reasoning Engine

---
name: ui-reasoning-engine
description: "Use when building, styling, optimizing, and auditing ui reasoning engine components, responsive layouts, design systems, and frontend state."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - product-aware-heuristics
  - interface-design
  - better-colors
  - better-ui
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
---

# UI Reasoning Engine — The Cognitive Design Loop

## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `ui-reasoning-engine` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).


## Activation Boundaries
- **Activate when:** Use when building, styling, optimizing, and auditing ui reasoning engine components, responsive layouts, design systems, and frontend state.
- **DO NOT activate when:** The task falls outside the `ui-reasoning-engine` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


---

## 🛠️ Technical Architecture & Reference Recipes

---

## The 16-Step Reasoning Pipeline

```
User Intent ↓ Product Classification ↓ User Classification ↓ Primary User Goals ↓ Task Frequency ↓ Information Architecture ↓ Interaction Model ↓ Content Hierarchy ↓ Platform Constraints ↓ Visual Direction ↓ Design System Selection ↓ Component Architecture ↓ Responsive Strategy ↓ Accessibility Strategy ↓ Motion Strategy ↓ Implementation
```

### 1. User Intent

- **Input:** User prompt description.
- **Analysis:** Analyze what the user is _actually_ trying to accomplish.
- **Result:** Is this an analytical task (comparing figures), an operational task (inputting records), a navigational task (getting to another screen), or an emotional/brand task (purchasing, onboarding)?

### 2. Product Classification

- **Input:** Chosen intent.
- **Analysis:** Categorize the product to choose the correct heuristic pack (see `product-aware-heuristics` skill).
- **Result:** SaaS, Developer Tool, Analytics Dashboard, Luxury/Marketing, AI Interface, Healthcare, Fintech, E-commerce, or Experimental.

### 3. User Classification

- **Input:** Product category.
- **Analysis:** Identify the target audience's demographics and expertise.
- **Result:** Is the user an expert operator (requires high density, shortcuts, speed), a casual consumer (requires clarity, onboarding, simplicity), or someone with temporary/permanent accessibility challenges?

### 4. Primary User Goals

- **Input:** User classification.
- **Analysis:** List the 3 most frequent tasks the user will perform on this screen.
- **Result:** How do we make the primary task take the least physical and cognitive effort (Fitts's Law)?

### 5. Task Frequency & Pace

- **Input:** Primary user goals.
- **Analysis:** Determine whether this is a high-frequency daily tool (e.g., terminal, text editor) or a low-frequency workflow (e.g., onboarding, checkout).
- **Result:** High frequency demands extreme speed, efficiency, and keyboard workflows. Low frequency demands validation, guardrails, and instructional microcopy.

### 6. Information Architecture (IA)

- **Input:** Spacing guidelines.
- **Analysis:** Map the relationships between data fields and screen areas.
- **Result:** Group related data items together using Gestalt principles of proximity and common region. Do not separate related data with arbitrary containers.

### 7. Interaction Model

- **Input:** IA relationships.
- **Analysis:** Define how users navigate, filter, and modify data.
- **Result:** Are we using modal dialogs, slide-out drawers, inline disclosures, tabs, or split-screen panels? Choose based on cognitive load and screen size.

### 8. Content Hierarchy

- **Input:** Interaction model.
- **Analysis:** Rank items by visual weight.
- **Result:** The eye must see the most important element first (Primary Action / Primary Figure), followed by secondary details, then supporting metadata.

### 9. Platform Constraints

- **Input:** Content hierarchy.
- **Analysis:** Identify the target environment.
- **Result:** Desktop (mouse precision, wide viewport), Mobile (coarse pointer, bottom action zone), or Cross-Platform.

### 10. Visual Direction & Mood

- **Input:** Platform constraints.
- **Analysis:** Select a distinctive theme that matches the product purpose (from `DESIGN.md`).
- **Result:** Swiss Precision, Brutalist, Dark Luxury, Editorial, Neo-Glassmorphism, Soft Minimal, Retro Analog, or Neon Cyberpunk.

### 11. Design System Selection

- **Input:** Visual Direction.
- **Analysis:** Match colors, radius, and shadows to the Visual Direction.
- **Result:** Never use raw hex colors. Use OKLCH semantic variables (`--bg-surface`, `--color-primary`, `--border-subtle`).

### 12. Component Architecture

- **Input:** Design system.
- **Analysis:** Decompose the UI into primitives (headless buttons, fields), components (cards, forms), and patterns (dashboards, headers).
- **Result:** Prevent duplication. Reuse existing UI tokens and patterns.

### 13. Responsive Strategy

- **Input:** Component list.
- **Analysis:** Plan reflow, resizing, and pointer changes.
- **Result:** Avoid scaling down desktop interfaces. Reorganize layouts using container queries (`@container`) and CSS clamp functions.

### 14. Accessibility (A11y) Strategy

- **Input:** Responsive plan.
- **Analysis:** Verify contrast, keyboard paths, and ARIA labels.
- **Result:** Verify target sizes are at least 24px (standard AA) and preferably 44px (touch). Contrast must meet APCA Lc ratios.

### 15. Motion Strategy

- **Input:** Accessibility strategy.
- **Analysis:** Define transitions and state changes.
- **Result:** Ensure all animations serve a purpose (feedback, orientation, or progression) and respect `prefers-reduced-motion`.

### 16. Implementation

- **Input:** All prior steps trace.
- **Analysis:** Generate the actual semantic markup, CSS custom properties, and logic.
- **Result:** Output code block.

---

## Enforcement Protocol

When building any UI, the Maker Agent must document this reasoning loop before returning the final code. Output the reasoning as a collapsed markdown block:

```markdown
<details>
<summary>🧠 UI Reasoning Engine Trace</summary>

1. **Intent:** [Analytical/Operational/etc.]
2. **Product Category:** [SaaS/DevTool/etc.]
3. **User Type:** [Expert/Casual]
4. **Primary Goals:** [Goal 1, 2, 3]
5. **Frequency:** [High/Low]
6. **IA & Grouping:** [Data relationships]
7. **Interaction Model:** [Modals/Drawers/Tabs]
8. **Content Hierarchy:** [Primary → Secondary → Muted]
9. **Platform:** [Desktop/Mobile/Tablet]
10. **Visual Mood:** [Swiss/Editorial/etc.]
11. **Tokens Used:** [OKLCH variables]
12. **A11y Strategy:** [Focus paths, contrast levels]
13. **Responsive Plan:** [Breakpoints & clamp sizes]
14. **Motion Plan:** [Easing, durations]

</details>
```

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |


## 🤖 LLM-Specific Traps Table

| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
|:---|:---|:---|
| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |


## 🏛️ Tribunal Verification & Guardrails

**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
**Slash Command:** `/review` or `/tribunal-full`

### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.

### ✅ Pre-Flight Self-Audit Checklist
```
✅ Are all component props strictly typed with zero implicit "any"?
✅ Are responsive breakpoints, fluid typography, and optical balance verified?
✅ Is accessibility (ARIA labels, keyboard navigation, contrast ratio >= 4.5:1) validated?
✅ Are re-renders minimized and state lifecycles cleanly separated?
✅ Did I verify all imported UI components and icon sets actually exist?
```

### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.