--- name: product-aware-heuristics description: "Use when building, styling, optimizing, and auditing product aware heuristics components, responsive layouts, design systems, and frontend state." version: 6.0.0 last-updated: 2026-09-29 skills: - ui-reasoning-engine - interface-design - baseline-ui - better-ui tools: Read, Grep, Glob, Bash, Edit, Write scripts-binding: - .agent/scripts/lint_runner.js - .agent/scripts/verify_all.js inputs: task: "string" target_file: "string" outputs: result: "string" verification_status: "boolean" trigger: - "product" - "aware" - "heuristics" --- # Product-Aware Heuristics โ€” Category-Specific Design Systems ## Mandatory Pre-Flight Context Inspection Before reading, generating, or refactoring code in the `product-aware-heuristics` 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 product aware heuristics components, responsive layouts, design systems, and frontend state. - **DO NOT activate when:** The task falls outside the `product-aware-heuristics` 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 --- ## 1. SaaS & Enterprise Applications - **Goal:** Operational efficiency, scannability, multi-record management, and action density. - **Visual Tone:** Swiss Precision or Soft Minimal. Clear borders, muted tinted grays, and highly legible typography. - **Heuristics:** - **Data Density:** Prefer structured tables and compact list views. Spacing should be tight but consistent (`8px` to `16px` grid). - **Keyboard Workflows:** All common actions must have keyboard shortcuts. Tab focus paths must be linear and predictable. - **Filters & Actions:** Provide global filters, batch action bars (appearing only when records are selected), and quick search boundaries. - **Responsive:** Grid layouts reflow to linear scroll cards on smaller screens; large tabular displays must support horizontal scrolling with sticky primary columns. ### SaaS Code Template (Dense Dynamic Table with Sidebar Detail Panel) ```tsx import React, { useState } from 'react'; import { Filter, MoreHorizontal, FileText, Check, ChevronRight, X } from 'lucide-react'; export function SaaSDataTable({ records }) { const [selectedIds, setSelectedIds] = useState([]); const [activeDetailId, setActiveDetailId] = useState(null); const activeRecord = records.find(r => r.id === activeDetailId); return (
{/* Table Main Area */}
{/* Table Toolbar */}
{selectedIds.length > 0 && (
{selectedIds.length} selected
)}
{/* Table container */}
{records.map(record => ( setActiveDetailId(record.id)} className={`hover:bg-[var(--bg-base)]/50 transition-colors group cursor-pointer ${activeDetailId === record.id ? 'bg-[var(--bg-base)]' : ''}`} > ))}
setSelectedIds(e.target.checked ? records.map(r => r.id) : [])} checked={selectedIds.length === records.length} className="rounded border-[var(--border-subtle)]" /> Name Status Usage
e.stopPropagation()}> setSelectedIds(prev => e.target.checked ? [...prev, record.id] : prev.filter(id => id !== record.id), ) } className="rounded border-[var(--border-subtle)]" /> {record.name} Active {record.usage} GB e.stopPropagation()}>
{/* Detail Slideout Panel */} {activeRecord && (

Record details

Name {activeRecord.name}
Usage Metrics {activeRecord.usage} Gigabytes
)}
); } ``` --- ## 2. Developer Tools - **Goal:** Technical clarity, command-driven inputs, diagnostics readability, and low cognitive overhead. - **Visual Tone:** Swiss Precision or Neon Cyberpunk. Dark backgrounds, high contrast, monospace font blocks, and flat borders. - **Heuristics:** - **Monospace Integration:** Log listings, code snippets, status outputs, and parameters must be wrapped in `` or `
` containers using `JetBrains Mono` or equivalent.
  - **Interactive Consoles:** Integrate quick-copy buttons for snippets. Terminal emulator areas should have responsive layouts that prevent truncation of long lines.
  - **Status Indicators:** Use explicit semantic color markers (e.g., solid red circle for critical error, pulsing green for active daemon) accompanied by text labels, never color alone.
  - **Density:** Extreme. Maximize visible data on-screen; minimize decorative card wrapping and whitespace.

### Developer Tool Code Template (Terminal log stream)

```tsx
import React, { useState } from 'react';
import { Copy, Terminal, Check } from 'lucide-react';

export function DevConsole({ logs }) {
  const [copied, setCopied] = useState(false);
  const command = 'npm run dev --port 8080';

  const handleCopy = () => {
    navigator.clipboard.writeText(command);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  return (
    

      {/* Console Header */}
      

        

           console.log
        

        
      


      {/* Console Body */}
      

        
$ {command}

        {logs.map((log, index) => (
          

            [{log.time}]
            
              {log.type.toUpperCase()}:
            
            {log.message}
          

        ))}
      

    

  );
}
```

---

## 3. Consumer Marketing & Landing Pages

- **Goal:** Emotional appeal, high conversion flows, brand differentiation, and typographic pacing.
- **Visual Tone:** Editorial, Dark Luxury, Swiss Precision, or Organic Natural.
- **Heuristics:**
  - **Layout Asymmetry:** Avoid 50/50 hero templates. Use overlapping layers, full-bleed media breakouts, and dramatic grid breaks.
  - **Typography Hierarchy:** Large, expressive display headings paired with highly legible body columns constrained to `60-70ch` to prevent eye strain.
  - **Controlled Motion:** Use scroll-driven reveals (e.g., clip-path reveals, stagger entry) to guide reading flow. Avoid constant looping animations.
  - **Visual Proof Grid:** Grid rows for logos and customer reviews must balance visual weight and scale.

### Landing Page Code Template (Asymmetric Hero Section)

```tsx
import React from 'react';
import { ArrowRight } from 'lucide-react';

export function AsymmetricHero() {
  return (
    

      

        {/* Left Side: Editorial Typography Column (Spans 7 columns) */}
        

          
            Flagship Release
          
          

            Create interfaces that feel{' '}
            
              human
            {' '}
            again.
          

          

            We extract clean, reusable design principles from elite developer interfaces and encode
            them into deterministic token specifications.
          

          

            
            
          

        


        {/* Right Side: Visual Accent Panel (Spans 5 columns, asymmetric displacement) */}
        

          

          

            

              Picasso v3 Token Output
            

            
              {`{
  "theme": "dark-luxury",
  "primary": "oklch(65% 0.22 250)",
  "geometry": {
    "radius-default": "12px",
    "border-subtle": "1px hairlines"
  }
}`}
            

          

        

      

    

  );
}
```

---

## 4. AI Interfaces

- **Goal:** Interactive stream clarity, model transparency, history containment, and prompting accessibility.
- **Visual Tone:** Neo-Glassmorphism, Dark Luxury, or Soft Minimal.
- **Heuristics:**
  - **Streaming Content States:** Show skeleton overlays or pulsing typing indicator bubbles during LLM processing. Stream response blocks chunk-by-chunk without layout shifts.
  - **System Boundaries:** Visually differentiate user inputs, assistant responses, and system alerts (using background tinting or subtle border lines).
  - **Actionable Prompts:** Provide quick-start suggestion chips at the bottom of empty chat views.
  - **Scroll Locking:** Automatically anchor chat containers to the bottom as long messages render, but release lock if the user manually scrolls up to read history.

### AI Chat Code Template (Input Prompt Area)

```tsx
import React, { useState } from 'react';
import { Send, Sparkles } from 'lucide-react';

export function AIChatInput({ onSubmit }) {
  const [input, setInput] = useState('');
  const suggestions = ['Generate SaaS Layout', 'Optimize CSS Grids', 'APCA Contrast Check'];

  return (
    

      {/* Suggestions Chips Row */}
      

        {suggestions.map((sug, i) => (
          
        ))}
      


      {/* Input Text Form */}
      
 {
          e.preventDefault();
          if (input.trim()) {
            onSubmit(input);
            setInput('');
          }
        }}
        className="flex gap-2 items-center border border-[var(--border-default)] rounded-[var(--radius-sm)] px-3 py-2 bg-[var(--bg-base)] focus-within:ring-1 focus-within:ring-[var(--color-primary)] transition-all"
      >
         setInput(e.target.value)}
          placeholder="Ask Antigravity UI to design..."
          className="flex-1 bg-transparent border-0 outline-none text-xs text-[var(--text-primary)] placeholder-[var(--text-muted)]"
        />
        
      

    

  );
}
```

---

## 5. Fintech & Dashboards

- **Goal:** Financial precision, trust, quick status retrieval, and clean charts.
- **Visual Tone:** Soft Minimal or Dark Luxury. Green/red semantic indicators should be soft sage and terracotta to avoid harsh, alarmist styling.
- **Heuristics:**
  - **Tabular Data Precision:** Use tabular numbers (`font-variant-numeric: tabular-nums`) to align digits perfectly in records.
  - **Interactive Visualizations:** Chart axes must have visible grids and clear legend labels. Hover tooltips must follow mouse movements and show precise numerical values.

## ๐Ÿšจ 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 
 without role="button", tabIndex, or onKeyDown | Use semantic