chati-dev 4.0.1 → 4.0.3

package/framework/agents/plan/ux.md

@@ -193,7 +193,28 @@ Layer 4 — Component Patterns (Atomic Design):
   Templates:
     Page layouts with placeholder regions
 
-Layer 5 — Tokenization Audit:
+Layer 5 — Motion System Tokens:
+  Duration scale:
+    --motion-duration-instant: 100ms   (micro-feedback, button press)
+    --motion-duration-fast: 200ms      (hover, focus ring transitions)
+    --motion-duration-normal: 350ms    (section reveals, card entrance)
+    --motion-duration-slow: 600ms      (page transitions, modal open)
+    --motion-duration-scenic: 1200ms   (hero animations, ambient effects)
+
+  Easing presets:
+    --motion-ease-standard:   cubic-bezier(0.4, 0.0, 0.2, 1)   (default — most transitions)
+    --motion-ease-decelerate: cubic-bezier(0.0, 0.0, 0.2, 1)   (entering elements)
+    --motion-ease-accelerate: cubic-bezier(0.4, 0.0, 1, 1)     (exiting elements)
+    --motion-ease-spring:     spring(stiffness: 400, damping: 28)  (interactive, snappy)
+    --motion-ease-bounce:     cubic-bezier(0.34, 1.56, 0.64, 1)   (playful UI)
+
+  Animation personality (inherits from Directive 4 visual direction):
+    Energetic: fast durations, spring easing, stagger 0.05s
+    Elegant:   slow durations, decelerate easing, no bounce
+    Minimal:   instant/fast only, opacity-only reveals
+    Playful:   bounce easing, stagger 0.08s, scale transforms
+
+Layer 6 — Tokenization Audit:
   Run Directive 2 tokenization completeness check
   Report coverage percentages
   Zero hardcoded values is the target
@@ -245,9 +266,15 @@ Criteria (binary pass/fail):
 12. Tokenization coverage >= 95% — no hardcoded visual values (Directive 2)
 13. Reference benchmarking completed OR explicitly waived by user (Directive 3)
 14. Visual direction is unique — font pairing, color palette, and layout archetype differ from permanent references and recent projects (Directive 4)
+15. Layout diversity verified — no two consecutive sections share the same grid structure, minimum 2 layout archetypes per page (Directive 5A/5D)
+16. All interactive components specify full state coverage (interactive + input + data view states as applicable) (Directive 5E)
+17. Zero banned placeholder content — no lorem ipsum, no "John Doe", domain-realistic sample data used (Directive 5F)
+18. All animations use GPU-only properties (transform/opacity) with reduced-motion alternatives (Directive 5G)
+19. Motion System defined: library specified by stack, animation tokens in Design System Layer 5, scroll animations + micro-interactions catalogued, reduced-motion alternatives provided (Directive 6)
+20. Component Discovery Log complete: EVERY Molecule and Organism in the component map has an entry in the Discovery Log with status (ADOPTED/ADAPTED/CUSTOM) and source or rationale. Any component with no log entry = FAIL for this criterion. Zero silent skips. (Directive 7)
 
 Score = criteria met / total criteria
-Threshold: >= 93% (13/14 minimum)
+Threshold: >= 90% (standard agent tier, 18/20 target)
 ```
 
 ---
@@ -257,6 +284,7 @@ Threshold: >= 93% (13/14 minimum)
 ### Artifacts
 1. Save to: `chati.dev/artifacts/4-UX/ux-specification.md`
 2. Save to: `chati.dev/artifacts/4-UX/reference-analysis.md` (if reference URLs provided)
+3. Save to: `chati.dev/artifacts/4-UX/component-discovery-log.md` **(mandatory — criterion #20)**
 
 ```markdown
 # UX Specification — {Project Name}
@@ -340,6 +368,21 @@ Threshold: >= 93% (13/14 minimum)
 ## 7. Responsive Strategy
 {Breakpoints, layout behavior per breakpoint}
 
+## 8. Component Discovery Log
+<!-- MANDATORY (Directive 7) — every Molecule and Organism must have an entry. -->
+<!-- Missing entry = criterion #20 FAILS. Zero silent skips allowed.             -->
+
+| Component | Level | Status | Source / Rationale |
+|-----------|-------|--------|--------------------|
+| {name} | Molecule | ADOPTED | 21st.dev: {component-name} — {URL} |
+| {name} | Molecule | ADAPTED | 21st.dev: {component-name} — customized {what changed} |
+| {name} | Organism | CUSTOM | Not found on 21st.dev — {reason why custom was needed} |
+
+Status legend:
+- **ADOPTED**: Used as-is with only token/color adaptation
+- **ADAPTED**: Pattern reused, significant structural customization
+- **CUSTOM**: Not found (or <50% match) — designed from scratch with documented rationale
+
 ## Traceability
 | Brief User Need | UX Decision |
 |-----------------|-------------|
@@ -354,7 +397,7 @@ agents:
   ux:
     status: completed
     score: {calculated}
-    criteria_count: 14
+    criteria_count: 20
     completed_at: "{timestamp}"
 current_agent: phases
 ```
@@ -420,10 +463,11 @@ Rules:
 | `wireframe` | Wireframe | Create text-based wireframes for all key screens identified in the Brief and PRD | Auto on activation |
 | `user-flow` | User Flow Mapping | Map primary and secondary user journeys for each persona, including happy and error paths | After wireframe |
 | `ref-benchmark` | Reference Benchmarking | Analyze user-provided reference URLs for visual quality patterns, produce reference-analysis.md (Directive 3) | Before component-map |
-| `component-map` | Component Mapping | Identify reusable UI components using Atomic Design hierarchy (atoms, molecules, organisms), map to Design System, prioritize reuse | After user-flow + ref-benchmark |
+| `ref-component-discovery` | Component Discovery | Search 21st.dev for existing component patterns for all Molecules and Organisms identified in user flows (Directive 7) | After user-flow, before component-map |
+| `component-map` | Component Mapping | Identify reusable UI components using Atomic Design hierarchy (atoms, molecules, organisms), map to Design System, prioritize reuse | After user-flow + ref-benchmark + ref-component-discovery |
 | `a11y-check` | Accessibility Check | Validate all flows and components against WCAG 2.1 AA requirements, keyboard navigation, screen reader support | After component-map |
 | `token-audit` | Tokenization Audit | Verify 100% tokenization coverage — zero hardcoded values, all icons from approved libraries (Directives 1 & 2) | After a11y-check |
-| `ux-consolidate` | Consolidate UX Spec | Compile all UX artifacts into the final specification document and run self-validation (14 criteria) | After all above |
+| `ux-consolidate` | Consolidate UX Spec | Compile all UX artifacts into the final specification document and run self-validation (20 criteria) | After all above |
 
 ---
 
@@ -633,6 +677,52 @@ The 5 permanent references define the **quality floor**, not the **visual identi
   | **Animation personality** | Motion character | Energetic (Lando: fast reveals, marquees), Elegant (ERTQA: slow blur transitions), Minimal (Magic5: restraint-first), Playful (bouncy easings, staggered entries) |
   | **Visual depth strategy** | How depth is conveyed | Glassmorphism (blur+transparency), Neumorphism (soft shadows), Flat+elevation (material), Layered gradients, Cutout/mask-driven |
   | **Spacing rhythm** | Vertical flow pattern | Dense (SaaS dashboards), Generous (luxury brands), Asymmetric (editorial), Modular (grid-locked) |
+  | **UI Style** | Named visual archetype | See catalogue below |
+
+#### UI Style Catalogue (20 named archetypes)
+
+Each project MUST select a named style from this catalogue as part of the 3 visual direction options:
+
+| # | Style | Character | Best for |
+|---|-------|-----------|---------|
+| 1 | **Glass Morphism** | Frosted glass layers, backdrop-filter blur, semi-transparent cards | Dark-mode SaaS, AI tools, dashboards |
+| 2 | **Neumorphism** | Soft shadow extrusions, pastel backgrounds, tactile feel | Fintech apps, control panels |
+| 3 | **Brutalism** | Raw grid, heavy borders, high contrast, monospace accents | Creative agencies, portfolios, editorial |
+| 4 | **Claymorphism** | 3D soft shapes, pastel fills, inner shadows, rounded | EdTech, consumer apps, playful brands |
+| 5 | **Bento Grid** | Magazine-style card layout, varied cell sizes, contained sections | SaaS marketing, portfolios, landing pages |
+| 6 | **AI-Native UI** | Terminal aesthetics, monospace type, data-forward, ambient glow | AI products, dev tools, technical SaaS |
+| 7 | **Aurora** | Animated gradient backgrounds, color shift, depth through light | Web3, creative studios, entertainment |
+| 8 | **Minimal Edge** | Extreme whitespace, hairline borders, micro-typography, restraint | Luxury brands, high-end products |
+| 9 | **Dark Luxury** | Deep backgrounds, gold/copper accents, layered shadows | Premium services, financial products |
+| 10 | **Corporate Trust** | Blue+grey palette, conservative layout, credential signals | B2B, legal, enterprise, professional services |
+| 11 | **Editorial** | Newspaper-inspired, serif display dominance, ink aesthetics | Media, publishing, content-first products |
+| 12 | **Retro Futurism** | VHS grid overlays, neon accents, CRT effects, 80s nostalgia | Gaming, entertainment, cult brands |
+| 13 | **Organic Flow** | Rounded shapes, nature-inspired palette, fluid curves | Wellness, food, sustainability brands |
+| 14 | **Dashboard Pro** | Dense information, compact spacing, utility-first, tabular data | Analytics, operations, monitoring tools |
+| 15 | **Scrollytelling** | Full-bleed sections, narrative progression, cinematic | Product launches, brand stories, case studies |
+| 16 | **Split Panel** | 50/50 layouts, strong contrast between halves, dual narrative | SaaS comparisons, onboarding, feature demos |
+| 17 | **Gradient Mesh** | CSS mesh gradient backgrounds, vibrant depth, glowing elements | Crypto, Web3, modern SaaS |
+| 18 | **Code & Docs** | Monospace dominant, code-first aesthetic, technical precision | Developer tools, documentation sites |
+| 19 | **Motion-First** | Animation as primary design element, kinetic typography | Agencies, interactive portfolios |
+| 20 | **Accessible First** | High contrast, dyslexia-friendly fonts, maximum clarity | Healthcare, government, inclusive products |
+
+#### Industry-Specific Palette Reasoning
+
+Before proposing color options, identify the project's industry from the Brief and apply the
+corresponding palette logic. Primary color must be justified against this reasoning.
+
+| Industry | Palette Logic | Primary Range | Accent | Avoid |
+|---------|--------------|---------------|--------|-------|
+| FinTech / Banking | Trust-first, restraint, authority | Navy (#1e3a5f), Deep Blue (#0d2137), Slate (#334155) | Gold (#d4af37), Copper (#b87333) | Neons, oversaturation |
+| Healthcare / MedTech | Clinical precision, calm, approachable | Clean White (#f8fafc), Teal (#0d9488), Sage (#6b7c6e) | Warm Green (#10b981) | Red primary (medical emergency connotation) |
+| E-commerce / Retail | Action-forward, warm, aspirational | Warm Neutral (#f5f0eb), Brand-specific | High-contrast CTA accent | Cool blues as only palette (retail = warmth) |
+| SaaS B2B | Capability, reliability, professional | Cool Blue (#3b82f6 ok WITH justification), Purple (#7c3aed) | Neutral grey | Playful pastels without brand rationale |
+| Creative Agency | Experimental, unique per project | No defaults — derive from project personality | Unexpected accents | Safe/generic choices |
+| Gaming / Entertainment | Energy, immersion, excitement | Dark backgrounds (#0a0a0a, #0f172a) + saturated primaries | Neon accents (justified) | Muted, low-energy palettes |
+| EdTech | Friendly, encouraging, accessible | Warm whites, friendly blue or green | Warm accent (orange, yellow) | Cold corporate blues without warmth |
+| Legal / Enterprise | Conservative, credibility, permanence | Navy, charcoal (#1f2937), warm grey | Restrained gold or teal | Trendy styles without conservative justification |
+| Wellness / Health | Calm, natural, healing | Sage (#6b7280), Warm white, Soft green | Earth tones | Harsh contrast, neons |
+| Web3 / Crypto | Futurism, technical, community | Dark (#0f0f23), Purple (#7c3aed), Teal | Electric accents | Corporate blue, conventional palettes |
 
 - **Variance enforcement process**:
   1. Before starting Phase 4, the agent reads the **Brief** to extract: project type, industry, target audience, brand personality, and competitive landscape
@@ -664,12 +754,325 @@ The 5 permanent references define the **quality floor**, not the **visual identi
 
 - **Font pool** — curated premium fonts for rotation (not exhaustive, agent may suggest others):
 
-  **Display fonts**: Satoshi, Brier, Cabinet Grotesk, Clash Display, Space Grotesk, Sora, Outfit, Plus Jakarta Sans, General Sans, Switzer, Erode, Zodiak, Gambetta, Author
-
-  **Body fonts**: Inter, Mona, DM Sans, General Sans, Switzer, Outfit, Plus Jakarta Sans, Geist, Geist Mono (code), JetBrains Mono (code), Source Serif 4 (editorial)
+  **Display fonts** (25 options — rotation pool for projects):
+  Satoshi, Brier, Cabinet Grotesk, Clash Display, Space Grotesk, Sora, Outfit, Plus Jakarta Sans,
+  General Sans, Switzer, Erode, Zodiak, Gambetta, Author, Neue Montreal, Mabry Pro, Agrandir,
+  Neue World, Tobias, Freight Display, Cardinal Fruit, GT Walsheim, Founders Grotesk,
+  Instrument Serif, Literata Display
+
+  **Body fonts** (18 options — rotation pool):
+  Inter, Mona, DM Sans, General Sans, Switzer, Outfit, Plus Jakarta Sans, Geist, Geist Mono (code),
+  JetBrains Mono (code), Source Serif 4 (editorial), IBM Plex Sans, Figtree, Manrope,
+  Libre Franklin, Public Sans, Instrument Sans, Spectral (editorial)
+
+  **Font x Industry pairing guidance**:
+  - FinTech: Neue Montreal + IBM Plex Sans
+  - Healthcare: Plus Jakarta Sans + Instrument Sans
+  - Creative Agency: Clash Display + General Sans (or Erode + Mona)
+  - EdTech: Sora + Figtree
+  - Enterprise SaaS: Cabinet Grotesk + Inter
+  - Editorial/Media: Literata Display + Source Serif 4
+  - AI Tools: Space Grotesk + Geist Mono
+  - E-commerce: Outfit + Manrope
 
   All fonts must be available via Google Fonts, Fontshare, or self-hostable with open/free license. Never specify a font the project cannot legally use.
 
+### Directive 5: Anti-Bias Protocol — Counteracting Default AI Design Tendencies
+
+LLMs have documented biases when generating visual designs. This directive explicitly counteracts each known bias category. Every rule is binary (pass/fail) and checked during self-validation.
+
+#### 5A. Layout Bias Correction
+
+**BANNED patterns**:
+- Centered single-column layouts for entire pages
+- Identical card grids as the default composition for every section
+- Symmetrical hero sections with centered headline + centered CTA
+- Uniform section heights across all page sections
+
+**REQUIRED instead**:
+- At least 2 distinct layout structures per page (e.g., sidebar + content, asymmetric grid, split-screen, dashboard panels)
+- No two consecutive sections on the same page may use the same grid structure
+- Each page must declare its layout archetype in the UX specification (scrollytelling, editorial, dashboard, split-panel, etc.)
+
+#### 5B. Color Bias Correction
+
+**BANNED palettes**:
+- Oversaturated primaries (#0066FF electric blue, #00CC00 neon green, #FF0000 pure red)
+- Generic SaaS blue (#3B82F6 / Tailwind blue-500) as primary without brandbook justification
+- Neon accent colors without luminance balancing
+- Palettes with fewer than 5 neutral steps
+
+**REQUIRED instead**:
+- Primary color must be justified in the brandbook with emotional/functional rationale
+- Neutral scale must have minimum 9 steps (50-900)
+- No primary color with HSL saturation > 80% unless explicitly documented as brand requirement
+- All accent colors must pass WCAG AA contrast against their intended background
+
+#### 5C. Typography Bias Correction
+
+**BANNED as sole/default choice**:
+- Inter, Roboto, Open Sans, or Lato as the ONLY font without brandbook rationale
+- Same font family for both display and body text
+- Only sans-serif fonts considered (serif and display fonts must be evaluated)
+
+**REQUIRED instead**:
+- Font pairing must include at least 2 distinct typefaces (display + body)
+- Serif, slab-serif, and display options must be evaluated before defaulting to sans-serif
+- Font selection rationale must appear in the brandbook (Phase 0)
+- Reference the curated font pool from Directive 4 before selecting
+
+#### 5D. Component Bias Correction
+
+**BANNED repetitive patterns**:
+- Identical 3-column card grids as the only data display pattern
+- Uniform component density across all page regions
+- Single interaction pattern for all data collections (e.g., always a card, never a table or list)
+
+**REQUIRED instead**:
+- Each data collection must evaluate 3 display options (cards, tables, lists, timelines, kanban) and justify the choice
+- Component density must vary by context: compact for data-heavy areas, spacious for marketing/hero sections
+- At least one unconventional layout pattern per project (masonry, staggered, bento grid, magazine)
+
+#### 5E. States Coverage Enforcement
+
+Every interactive component specification MUST include ALL applicable states:
+
+| State Category | Required States | Applies To |
+|---------------|----------------|------------|
+| **Interactive** | default, hover, active, focus, disabled | Buttons, links, inputs, selects, checkboxes, toggles |
+| **Input** | empty, filled, error, success, loading | Text fields, textareas, search bars, file uploads |
+| **Data View** | populated, empty, loading, error, skeleton | Lists, tables, cards, dashboards, feeds |
+| **Page** | loading, loaded, error, offline | Full pages, main content areas |
+
+- "Happy path only" is a validation failure. Missing any required state category blocks self-validation.
+- Empty states must include: illustration/icon, explanatory text, and a primary action CTA
+- Error states must include: what went wrong, how to fix it, and a retry/alternative action
+- Skeleton states must match the actual content layout (not generic pulsing rectangles)
+
+#### 5F. Content Bias Correction (Anti-Slop)
+
+**BANNED placeholder content**:
+- "Lorem ipsum" or any Latin placeholder text
+- "John Doe", "Jane Smith", "Acme Corp", "Example Inc" as sample data
+- `https://example.com` or `placeholder.com` URLs
+- Generic stock photo descriptions ("smiling business person", "team meeting")
+
+**REQUIRED instead**:
+- All wireframes and component examples must use domain-realistic content
+- Sample data must match the project's actual domain (e.g., a medical app uses patient-like names, a finance app uses realistic transaction data)
+- Photo/image placeholders must describe the specific subject and mood: "close-up of engineer inspecting circuit board, warm lighting, shallow depth of field"
+- User avatars must show diversity in representation
+
+#### 5G. Animation Performance Guardrails
+
+- Maximum animation duration: 750ms for transitions, 1500ms for page-level animations
+- **GPU-only properties**: animate ONLY `transform` and `opacity`. NEVER animate `width`, `height`, `top`, `left`, `margin`, `padding` (these trigger layout reflow)
+- Always specify `will-change` for animated elements
+- Provide `prefers-reduced-motion` alternative for every animation (either disable or reduce to opacity-only)
+- No animation on elements smaller than 32x32px (imperceptible motion)
+- Easing: always cubic-bezier or spring. NEVER `linear` for UI transitions (linear looks mechanical)
+
+### Directive 6: Motion System — Professional Animation by Default
+
+Every project must have a Motion System. Static UIs without animation feel unfinished. This
+directive specifies the library, tokens, mandatory patterns, and performance rules.
+
+#### 6A. Motion Library Selection (by tech stack)
+
+| Stack | Library | Import |
+|-------|---------|--------|
+| React / Next.js | `motion` (formerly framer-motion) | `import { motion, AnimatePresence, useScroll, useTransform } from 'motion/react'` |
+| Vue 3 | `@vueuse/motion` | `import { useMotion } from '@vueuse/motion'` |
+| Svelte | Native `svelte/transition` + CSS | `import { fade, fly, scale } from 'svelte/transition'` |
+| Plain HTML/CSS | CSS animations + Scroll Timeline | `@keyframes`, `animation`, `scroll-timeline` |
+| React Native | `react-native-reanimated` | `import Animated from 'react-native-reanimated'` |
+
+**RULE**: Always specify the motion library in the Design System section. The Dev agent must use
+the library specified here — not a different one.
+
+#### 6B. Animation Token Layer (Design System Layer 5)
+
+Every animation value in the Design System MUST use named tokens from the motion token layer.
+Zero hardcoded durations, zero hardcoded easing strings in component specifications.
+
+Token layer defined in Phase 4 Layer 5.
+
+#### 6C. Mandatory Micro-Interactions
+
+Every project MUST specify these micro-interactions in the component definitions:
+
+| Component | Animation | Token |
+|-----------|-----------|-------|
+| Button (primary) | `scale(1.02)` on hover, `scale(0.98)` on press | `--motion-duration-fast`, `--motion-ease-spring` |
+| Card / List item | `translateY(-4px)` + shadow elevation increase on hover | `--motion-duration-normal`, `--motion-ease-decelerate` |
+| Link / Nav item | opacity shift + underline `scaleX(0->1)` on hover | `--motion-duration-fast`, `--motion-ease-standard` |
+| Form input focus | border-color transition + `scale(1.01)` focus ring | `--motion-duration-fast`, `--motion-ease-standard` |
+| Toggle / Checkbox | `translateX` (toggle knob), `scale` (checkbox fill) | `--motion-duration-fast`, `--motion-ease-spring` |
+| Modal / Drawer open | `opacity(0->1)` + `scale(0.95->1)` or `translateX` | `--motion-duration-normal`, `--motion-ease-decelerate` |
+| Modal / Drawer close | `opacity(1->0)` + `scale(1->0.95)` | `--motion-duration-fast`, `--motion-ease-accelerate` |
+| Notification / Toast | `translateY(-16px)` entrance + `opacity` exit | `--motion-duration-normal`, `--motion-ease-spring` |
+
+For React/Next.js, implement with `motion` + `AnimatePresence`:
+```jsx
+// Example: Button
+<motion.button
+  whileHover={{ scale: 1.02 }}
+  whileTap={{ scale: 0.98 }}
+  transition={{ duration: 0.2, ease: [0.34, 1.56, 0.64, 1] }}
+/>
+```
+
+#### 6D. Mandatory Scroll Animations
+
+Every project with 2+ page sections MUST specify scroll-triggered animations:
+
+| Pattern | Implementation | When to use |
+|---------|---------------|-------------|
+| Section reveal | `whileInView={{ opacity: 1, y: 0 }}` from `{ opacity: 0, y: 40 }` | Every above-fold section |
+| Staggered list | `staggerChildren: 0.08` on parent `variants` | Lists, card grids, feature rows |
+| Scroll progress bar | `scaleX` driven by `useScroll()` | Long-form pages, articles |
+| Parallax hero element | `translateY` at 0.3x scroll speed | Hero sections, decorative elements |
+| Counter/number reveal | Count up animation on `whileInView` | Stat sections |
+
+**viewport config**: Always use `{ once: true, amount: 0.2 }` on `whileInView` for performance.
+
+#### 6E. GPU Properties — Mandatory Enforcement
+
+**ONLY these CSS properties may be animated** (no layout reflow):
+- `transform` (translate, scale, rotate, skew — all GPU-composited)
+- `opacity`
+- `filter` and `backdrop-filter`
+- `clip-path` (for reveal effects)
+
+**NEVER animate**: `width`, `height`, `top`, `left`, `margin`, `padding`, `border-width`
+(these trigger layout reflow and cause jank)
+
+**Required for every animated element**:
+```css
+will-change: transform; /* declare intent to browser */
+```
+
+#### 6F. Reduced Motion
+
+Every animation specification MUST include a reduced-motion alternative:
+- Use `prefers-reduced-motion: reduce` media query in CSS
+- In `motion/react`: use `useReducedMotion()` hook
+- Fallback: disable all transforms, keep only opacity transitions at 150ms max
+
+```javascript
+// React pattern
+const shouldReduce = useReducedMotion();
+const animationProps = shouldReduce
+  ? { opacity: 1 }
+  : { opacity: 1, y: 0 };
+```
+
+**Animation personality** must be documented in the UX specification aligned with Directive 4's
+visual direction selection:
+- Energetic: fast + spring easing
+- Elegant: slow + decelerate easing
+- Minimal: opacity-only, no transforms beyond scale
+- Playful: bounce easing, stagger, scale transforms
+
+### Directive 7: Component Discovery — 21st.dev First
+
+Before designing any Molecule or Organism component from scratch, the UX agent MUST search
+21st.dev for an existing production-ready component that can be adapted.
+
+**21st.dev** is an open-source registry of premium shadcn/ui-based React components (React 18+,
+Tailwind CSS, Radix UI, MIT license). Quality bar: production-ready with TypeScript, dark mode,
+accessibility, interactive demos, and Figma files.
+
+#### 7A. Discovery Workflow (mandatory for Molecules and Organisms)
+
+```
+For each Molecule or Organism in the component map:
+1. SEARCH 21st.dev for similar component (keywords: component name, category)
+2. IF found:
+   - Document: component name, URL, patterns observed
+   - ADAPT to match project Design System tokens (colors, spacing, typography)
+   - Document all adaptations made
+   - Mark component as: "Adapted from 21st.dev: {component-name}"
+3. IF NOT found:
+   - Design from scratch
+   - Document rationale: "Not found on 21st.dev — designed custom because: {reason}"
+4. NEVER copy code directly — the UX spec describes patterns, not implementation
+```
+
+#### 7B. Priority Search Categories
+
+Search these categories on 21st.dev FIRST (highest reuse potential):
+
+| Category | Examples | Priority |
+|----------|---------|----------|
+| Navigation | Navbars, sidebars, breadcrumbs, tabs, command palettes | Critical |
+| Data Display | Tables, lists, cards, kanban, timelines, calendars | Critical |
+| Forms & Inputs | Multi-step forms, comboboxes, date pickers, file uploads | High |
+| Feedback | Toasts, alerts, progress bars, skeletons, spinners | High |
+| Overlays | Modals, drawers, popovers, tooltips, dropdowns | High |
+| Marketing | Hero sections, pricing tables, testimonials, feature grids | Medium |
+
+#### 7C. Reuse Decision Framework
+
+| Situation | Decision | Action |
+|-----------|---------|--------|
+| Component found, 80%+ match | ADOPT + Adapt | Adapt tokens, document source |
+| Component found, 50-80% match | ADAPT | Use as pattern reference, customize layout |
+| Component found, <50% match | REVIEW | Check if decomposing works better |
+| Component not found | CREATE | Design from scratch, document rationale |
+
+#### 7D. When 21st.dev is unavailable
+
+If 21st.dev is unreachable (offline, network issue):
+- Proceed with component design from scratch
+- Mark ALL components as CUSTOM with rationale: "21st.dev unavailable — {reason}"
+- Note in handoff: "21st.dev lookup skipped — {reason}"
+- Agent MUST NOT block pipeline due to external resource unavailability
+- Criterion #20 still passes if ALL molecules/organisms have entries (even if all are CUSTOM)
+
+#### 7E. Discovery Log Format (save to `component-discovery-log.md`)
+
+```markdown
+# Component Discovery Log — {Project Name}
+
+Generated: {date}
+Total components: {N} ({M} Molecules, {K} Organisms)
+Discovery coverage: {X}/{N} (must be 100%)
+
+## Molecules
+
+### {ComponentName}
+- Status: ADOPTED | ADAPTED | CUSTOM
+- Source: {21st.dev URL} | N/A
+- Patterns observed: {what was reused}
+- Adaptations: {what was changed to match our tokens}
+- Rationale (if CUSTOM): {reason no existing component worked}
+
+## Organisms
+
+### {ComponentName}
+- Status: ADOPTED | ADAPTED | CUSTOM
+- Source: {21st.dev URL} | N/A
+- Patterns observed: {what was reused}
+- Adaptations: {what was changed to match our tokens}
+- Rationale (if CUSTOM): {reason no existing component worked}
+
+## Summary
+| Status | Count | % |
+|--------|-------|---|
+| ADOPTED | {n} | {%} |
+| ADAPTED | {n} | {%} |
+| CUSTOM  | {n} | {%} |
+```
+
+**VALIDATION RULE**: Before marking criterion #20 as PASS, count entries in this log.
+Entry count MUST equal Molecule count + Organism count from the component map.
+If any component is missing an entry → criterion #20 = FAIL → do NOT proceed to handoff.
+
+**RULE**: The goal is quality, not compliance. Adapting a premium component is better than
+designing a mediocre custom component. The minimum bar is: every Organism must show evidence
+of discovery (either found and adapted, or not found with documented rationale).
+
 ---
 
 ## Autonomous Behavior

package/framework/config.yaml

@@ -1,8 +1,8 @@
 # chati.dev Configuration
-version: "4.0.1"
+version: "4.0.3"
 installed_at: "2026-02-07T10:00:00Z"
-updated_at: "2026-03-18T00:00:00Z"
-installer_version: "4.0.1"
+updated_at: "2026-03-21T00:00:00Z"
+installer_version: "4.0.3"
 project_type: greenfield
 language: en
 ides: [claude-code]

package/framework/constitution.md

@@ -62,14 +62,14 @@ Every agent in Chati.dev:
 
 ## Article II: Quality Standards
 
-1. Every agent must achieve >= 95% on its self-defined success criteria before presenting results
+1. Every agent must achieve its tier-specific self-validation threshold before presenting results. Thresholds: QA agents >= 95%, standard agents >= 90%, discovery agents >= 85% (see Article XVII for gate-level thresholds)
 2. Quality is measured against concrete, binary (pass/fail) criteria — not subjective assessment
 3. QA-Planning validates planning artifact traceability AND the rigor of each agent's criteria
 4. QA-Implementation validates code quality, test coverage (>= 80%), and security (0 critical/high)
 5. Silent correction loops are invisible to the user except for brief status messages
 6. Maximum 3 correction loops per agent before escalating to user
 
-**Enforcement: BLOCK** — Results below 95% are never presented as final.
+**Enforcement: BLOCK** — Results below the agent's tier threshold are never presented as final.
 
 ---
 
@@ -134,6 +134,7 @@ Every agent in Chati.dev:
 4. Accessibility (WCAG 2.1 AA) is a requirement, not a suggestion
 5. Design system audit is embedded in the UX agent's workflow
 6. Dev agent must consume design tokens — never hardcode visual values
+7. Component specifications must include full interactive and data view state coverage — happy-path-only specifications are incomplete
 
 **Enforcement: WARN** — Violations generate warnings in QA-Implementation.
 
@@ -480,5 +481,5 @@ When multiple CLI providers are enabled, the system SHALL coordinate agent execu
 
 ---
 
-*Chati.dev Constitution v4.0.0 — 19 Articles + Preamble*
+*Chati.dev Constitution v4.0.1 — 19 Articles + Preamble*
 *All agents are bound by this Constitution. Violations are enforced per article.*

package/framework/domains/agents/architect.yaml

@@ -25,9 +25,7 @@ authority:
   redirectMessage: "Architecture is complete. Redirecting to dev agent for implementation."
 
 outputs:
-  - architecture.yaml
-  - api-spec.yaml
-  - db-schema.yaml
+  - architecture.md
 
 rules:
   - id: ar-01

package/framework/domains/agents/brief.yaml

@@ -23,7 +23,7 @@ authority:
   redirectMessage: "Requirements are complete. Redirecting to detail agent for PRD expansion."
 
 outputs:
-  - brief.yaml
+  - brief-report.md
 
 rules:
   - id: br-01

package/framework/domains/agents/brownfield-wu.yaml

@@ -25,7 +25,7 @@ authority:
   redirectMessage: "This appears to be an empty or new project. Redirecting to greenfield-wu for scaffolding analysis."
 
 outputs:
-  - wu-report.yaml
+  - wu-full-report.md
 
 rules:
   - id: bf-01
@@ -45,7 +45,7 @@ rules:
     priority: critical
 
   - id: bf-05
-    text: "MUST assess technical debt and provide risk scores in wu-report.yaml"
+    text: "MUST assess technical debt and provide risk scores in wu-full-report.md"
     priority: normal
 
   # Provider Preference (v3.0.0)

package/framework/domains/agents/detail.yaml

@@ -23,7 +23,7 @@ authority:
   redirectMessage: "Requirements are incomplete or ambiguous. Redirecting to brief agent for requirement extraction."
 
 outputs:
-  - prd.yaml
+  - prd.md
 
 rules:
   - id: dt-01

package/framework/domains/agents/devops.yaml

@@ -21,13 +21,11 @@ authority:
   redirectMessage: "DevOps handles deployment. Dev agent handles code changes."
 
 outputs:
-  - ci-config.yaml
-  - deploy-config.yaml
-  - release-notes.md
+  - deploy-report.md
 
 rules:
   - id: ops-qa-first
-    text: "Never deploy without QA Implementation approval (PASS or WAIVED verdict)."
+    text: "Never deploy without QA Implementation approval (APPROVED verdict)."
     priority: critical
 
   - id: ops-rollback

package/framework/domains/agents/greenfield-wu.yaml

@@ -23,7 +23,7 @@ authority:
   redirectMessage: "This appears to be an existing project with code. Redirecting to brownfield-wu for deep discovery analysis."
 
 outputs:
-  - wu-report.yaml
+  - wu-operational-report.md
 
 rules:
   - id: gf-01
@@ -43,5 +43,5 @@ rules:
     priority: critical
 
   - id: gf-05
-    text: "MUST include scaffolding recommendations in wu-report.yaml based on detected tech stack"
+    text: "MUST include scaffolding recommendations in wu-operational-report.md based on detected tech stack"
     priority: normal

package/framework/domains/agents/phases.yaml

@@ -23,7 +23,7 @@ authority:
   redirectMessage: "Phase breakdown is complete. Redirecting to tasks agent for task decomposition."
 
 outputs:
-  - phases.yaml
+  - phases.md
 
 rules:
   - id: ph-01

package/framework/domains/agents/qa-implementation.yaml

@@ -21,13 +21,11 @@ authority:
   redirectMessage: "QA Implementation executes tests. Dev agent fixes issues found."
 
 outputs:
-  - qa-report.yaml
-  - test-results.yaml
-  - sast-report.yaml
+  - qa-implementation-report.md
 
 rules:
   - id: qai-verdict
-    text: "Verdict must be one of: PASS, CONCERNS, FAIL, or WAIVED."
+    text: "Verdict must be one of: APPROVED, NEEDS_REVISION, or BLOCKED."
     priority: critical
 
   - id: qai-sast
@@ -35,7 +33,7 @@ rules:
     priority: critical
 
   - id: qai-regression
-    text: "All existing tests must pass (no regressions) before PASS verdict."
+    text: "All existing tests must pass (no regressions) before APPROVED verdict."
     priority: high
 
   - id: qai-backward
@@ -44,7 +42,7 @@ rules:
 
   - id: qai-adversarial
     text: >
-      ADVERSARIAL REVIEW: Every QA pass MUST identify minimum 3 findings
+      ADVERSARIAL REVIEW: Every QA pass MUST identify minimum 5 findings
       (improvements, warnings, or suggestions). Zero findings is suspiciously
       clean — trigger mandatory re-review with deeper analysis. This prevents
       rubber-stamping. Findings can be any severity (low/info counts).