@minhduydev/mdpi 0.4.0 → 0.4.1

package/dist/index.js

@@ -10,7 +10,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { mkdir, readdir } from "node:fs/promises";
 //#region package.json
-var version = "0.4.0";
+var version = "0.4.1";
 //#endregion
 //#region src/utils/manifest.ts
 /**

package/dist/template/.pi/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

package/dist/template/.pi/extensions/templates-injector.ts

@@ -21,7 +21,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-const ALWAYS_INJECT = ["project.md", "tech-stack.md", "state.md"];
+const ALWAYS_INJECT = ["project.md", "tech-stack.md", "state.md", "DESIGN.md"];
 
 function readTemplate(cwd: string, name: string): string | null {
 	// Prefer live file at .pi/{name} (filled by /init — real project state);

package/dist/template/.pi/skills/INDEX.md

@@ -5,7 +5,7 @@ description: "Task-to-skill routing table with File Match + Keyword triggers, Ph
 
 # Skills Index — Task → Skill Mapping
 
-This file helps the agent (and humans) discover which skill to load for a given task. Skills are auto-loaded into the system prompt at startup (Tier 1), triggered by File/Keyword Match rules, or loaded on-demand via `/skill:<name>` (Tier 2). All 70 skills are available directly in `.pi/skills/`.
+This file helps the agent (and humans) discover which skill to load for a given task. Skills are auto-loaded into the system prompt at startup (Tier 1), triggered by File/Keyword Match rules, or loaded on-demand via `/skill:<name>` (Tier 2). All skills are available directly in `.pi/skills/`.
 
 **How routing works:** File Match → Keyword Match → Quick Routing Table → Decision Tree (if ambiguous).
 
@@ -24,9 +24,10 @@ When the agent edits files matching these patterns, the listed skills auto-load.
 | `.github/workflows/**,Dockerfile,docker-compose*.yml` | `ci-cd-and-automation` | Pipeline design + caching |
 | `.pi/skills/*/SKILL.md` | `writing-skills` | Skill authoring best practices |
 | `.pi/loops/**`,`loop-orchestrator.*`,`loop-guard.ts` | `loop-engineering`, `loop-audit` | Loop design/qualification + readiness scoring |
-| `*.css,*.scss,*.less` | `frontend-design`, `design-taste-frontend` | Design system consistency |
-| `*.tsx,*.jsx` | `frontend-ui-engineering` | Production-quality UI standards |
+| `*.css,*.scss,*.less` | `baseline-ui`, `frontend-design`, `design-taste-frontend` | Deslop pass + design system consistency |
+| `*.tsx,*.jsx` | `baseline-ui`, `frontend-ui-engineering` | Deslop pass + production-quality UI standards |
 | `*.md,docs/**,ADR*.md` | `documentation-and-adrs` | Doc structure + ADR format |
+| `.pi/**/DESIGN.md` | `frontend-design`, `design-taste-frontend` | Project design identity — load aesthetic skills when DESIGN.md is edited |
 
 ---
 
@@ -43,7 +44,13 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | refactor, cleanup, simplify, clean code, complex | `code-cleanup`, `code-simplification`, `deep-module-design` |
 | test, spec, verify, assert, coverage, TDD | `test-driven-development`, `testing-anti-patterns` |
 | review, audit, quality, check, PR | `code-review-and-quality`, `agent-code-quality-gate` |
-| design, UI, component, style, layout, CSS, tailwind | `frontend-design`, `design-taste-frontend` |
+| design, UI, component, style, layout, CSS, tailwind, DESIGN.md, design identity, design token, brand identity | `frontend-design`, `design-taste-frontend` |
+| accessibility, a11y, WCAG, ARIA, keyboard, focus, fix a11y | `fixing-accessibility` |
+| craft, polish, detail, micro-interaction, concentric, optical, border-radius | `ui-craft-principles` |
+| i18n, internationalization, RTL, edge case, error state, empty state, harden, text overflow | `production-hardening` |
+| audit, quality score, UI audit, anti-pattern detection, P0 P1 P2 | `ui-quality-audit` |
+| OKLCH, color system, color palette, color space, gamut, color conversion | `oklch-color-workflow` |
+| deslop, quick fix, baseline, fix AI patterns, auto-fix UI | `baseline-ui` |
 | database, query, SQL, postgres, supabase, RLS, migration | `supabase`, `supabase-postgres-best-practices` |
 | docs, documentation, README, ADR, changelog | `documentation-and-adrs` |
 | commit, branch, merge, rebase, git, worktree | `git-workflow-and-versioning`, `using-git-worktrees` |
@@ -60,6 +67,7 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | Jira, Confluence, Atlassian, issue, ticket | `jira` |
 | browser, e2e, screenshot, playwright, chrome | `playwright`, `chrome-devtools`, `browser-testing-with-devtools` |
 | dependency, package, library, npm, PyPI, source | `opensrc` |
+| scrape, crawl, webclaw, bot protection, 403, webfetch fail, extract web content, web scraping | `webclaw` |
 | loop, unattended loop, nightly triage, loop-readiness, loop-cost, loop-check, loop-review | `loop-engineering`, `loop-audit`, `loop-cost` |
 | Swift, iOS, macOS, actor, async/await, Sendable | `swift-concurrency`, `swiftui-expert-skill`, `core-data-expert` |
 
@@ -134,17 +142,23 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 
 | Skill | Use when | Phase | Risk |
 |-------|----------|-------|------|
-| `frontend-ui-engineering` | Production-quality UIs — component architecture, design systems, WCAG 2.1 AA, avoid AI aesthetic | Build | Medium |
-| `frontend-design` | Building any web UI with React-based frameworks | Build | Medium |
+| `accessibility-audit` | ⚠️ DEPRECATED — use `fixing-accessibility` instead | Review | Medium |
+| `baseline-ui` | Quick deslop pass — fixes common AI-generated UI anti-patterns automatically | Build | Low |
+| `design-system-audit` | Auditing an existing design system for consistency | Review | Medium |
 | `design-taste-frontend` | BASE aesthetic layer to override default LLM design biases | Build | Low |
+| `fixing-accessibility` | Actionable WCAG 2.1 AA accessibility fixes — before/after code examples | Build + Review | Medium |
+| `frontend-design` | Building any web UI with React-based frameworks | Build | Medium |
+| `frontend-ui-engineering` | Production-quality UIs — component architecture, design systems, WCAG 2.1 AA, avoid AI aesthetic | Build | Medium |
 | `high-end-visual-design` | Premium, agency-quality, or luxury visual design | Build | Low |
-| `minimalist-ui` | Clean, editorial, or minimalist aesthetics | Build | Low |
 | `industrial-brutalist-ui` | Brutalist, military-terminal, or raw mechanical aesthetics | Build | Low |
+| `minimalist-ui` | Clean, editorial, or minimalist aesthetics | Build | Low |
+| `mockup-to-code` | Converting UI mockups, screenshots, Figma/Sketch designs into code | Build | Medium |
+| `oklch-color-workflow` | Complete OKLCH color system — syntax, palette generation, contrast, Tailwind v4 | Build | Low |
+| `production-hardening` | Production hardening — i18n, error states, edge cases, cross-browser | Ship | High |
 | `react-best-practices` | Writing, reviewing, or refactoring React/Next.js code for performance | Build | Medium |
 | `redesign-existing-projects` | Upgrading an existing website or app's visual design | Build | High |
-| `mockup-to-code` | Converting UI mockups, screenshots, Figma/Sketch designs into code | Build | Medium |
-| `accessibility-audit` | Auditing UI components or pages for accessibility compliance | Review | Medium |
-| `design-system-audit` | Auditing an existing design system for consistency | Review | Medium |
+| `ui-craft-principles` | 16 craft principles — concentric radius, optical alignment, interruptible animations | Build | Low |
+| `ui-quality-audit` | 5-dimension UI quality scoring (0-4) with P0-P3 severity tags | Review | Medium |
 
 ### Platform / Infrastructure
 
@@ -227,8 +241,15 @@ Maps user intent to skill(s). `→` = sequential pipeline (execute in order). `+
 | "add payment" / "subscription" / "checkout" | `polar` | Build | High |
 | "Figma to code" / "mockup to code" / "design to code" | `figma` → `mockup-to-code` → `frontend-design` | Build | Medium |
 | "redisign" / "visual upgrade" / "restyle" | `redesign-existing-projects` | Build | High |
-| "accessibility" / "a11y" / "WCAG" | `accessibility-audit` | Review | Medium |
+| "color system" / "OKLCH" / "color palette" | `oklch-color-workflow` | Build | Low |
+| "fix accessibility" / "a11y fix" / "WCAG fix" | `fixing-accessibility` | Build | Medium |
+| "make it feel better" / "craft details" / "UI polish" | `ui-craft-principles` | Build | Low |
+| "production ready" / "harden UI" / "edge cases" | `production-hardening` | Ship | High |
+| "quick polish" / "deslop" / "baseline fix" | `baseline-ui` | Build | Low |
+| "UI audit" / "quality score" / "score my UI" | `ui-quality-audit` | Review | Medium |
+| "accessibility" / "a11y" / "WCAG" | `fixing-accessibility` | Review | Medium |
 | "dependency issue" / "how does library X work" | `opensrc` | Build | Low |
+| "scrape this" / "extract from" / "webclaw" / "crawl site" / "webfetch failed" | `webclaw` | Build | Low |
 | "browser test" / "e2e test" / "playwright" | `playwright` \| `browser-testing-with-devtools` | Verify | Medium |
 | "migrate" / "deprecate" / "remove old API" | `deprecation-and-migration` | Ship | High |
 | "create skill" / "write skill" / "edit skill" | `writing-skills` | Build | Low |
@@ -246,6 +267,7 @@ Execute skills in order — output of one feeds the next.
 brainstorming → spec-driven-development → planning-and-task-breakdown → incremental-implementation
 figma → mockup-to-code → frontend-design
 root-cause-tracing → debugging-and-error-recovery → verification-before-completion
+baseline-ui → frontend-design → ui-craft-principles → production-hardening → ui-quality-audit
 ```
 
 ### Parallel Load (`+`)
@@ -253,7 +275,7 @@ Load multiple skills simultaneously for independent concerns.
 
 ```
 code-review-and-quality + performance-optimization + security-and-hardening
-frontend-design + design-taste-frontend + accessibility-audit
+frontend-design + design-taste-frontend + fixing-accessibility
 test-driven-development + testing-anti-patterns + defense-in-depth
 ```
 
@@ -267,6 +289,15 @@ Phase 3 (Review):  code-review-and-quality + code-simplification
 Phase 4 (Ship):    verification-before-completion → shipping-and-launch
 ```
 
+```
+Phase 1 (Deslop):   baseline-ui
+Phase 2 (Design):   design-taste-frontend → frontend-design  
+Phase 3 (Craft):    ui-craft-principles + oklch-color-workflow
+Phase 4 (Build):    frontend-ui-engineering + incremental-implementation
+Phase 5 (Harden):   production-hardening + fixing-accessibility
+Phase 6 (Audit):    ui-quality-audit
+```
+
 ### Choose One (`|`)
 Pick the best single skill when options are context-dependent.
 

package/dist/template/.pi/skills/accessibility-audit/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: accessibility-audit
-description: Use when auditing UI components or pages for accessibility compliance, checking WCAG conformance, identifying keyboard navigation issues, color contrast problems, and pre-launch accessibility verification
+description: ⚠️ DEPRECATED — Use fixing-accessibility instead. Previously used for auditing UI components or pages for accessibility compliance.
 ---
 
-# Accessibility Audit Skill
+> **⚠️ DEPRECATED — This skill has been replaced by [`fixing-accessibility`](../fixing-accessibility/SKILL.md).**
+> 
+> `fixing-accessibility` provides actionable WCAG 2.1 AA fixes with before/after code examples, not just audit checklists. It covers 9 priority categories with concrete fix recipes.
+> 
+> This file is retained for backward compatibility. All references should redirect to `fixing-accessibility`.
+
+# Accessibility Audit Skill (Deprecated)
 
 ## When to Use
 

package/dist/template/.pi/skills/baseline-ui/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: baseline-ui
+description: Auto-load when editing *.tsx,*.jsx,*.css — quick deslop pass that fixes common AI-generated UI anti-patterns before any design work begins
+---
+
+# Baseline UI
+
+## When to Use
+
+- Auto-load when editing `*.tsx`, `*.jsx`, `*.css`, `*.scss` — runs a quick deslop pass first
+- Before loading any aesthetic overlay (`design-taste-frontend`, `minimalist-ui`, etc.)
+- When reviewing or cleaning up existing UI that looks "AI-generated"
+- First step in any frontend implementation pipeline
+
+## When NOT to Use
+
+- When `design-taste-frontend` or a specific aesthetic overlay is already loaded (they supersede these rules)
+- When building non-UI code (backend, CLI, data processing, APIs)
+- When working with an established design system that already bakes in these rules
+
+---
+
+## Quick Deslop Pass — Three Rule Tiers
+
+Apply these rules in order. **MUST** rules are hard errors — fix before proceeding. **SHOULD** rules are warnings — fix unless there's a deliberate exception. **NEVER** rules are blocking patterns — rewrite entirely.
+
+### MUST Rules (Hard Errors)
+
+Patterns that are never acceptable in production UI. Fix before any other work.
+
+| Rule | Anti-pattern | Fix |
+|------|-------------|-----|
+| **No purple gradients** | `bg-gradient-to-r from-purple-500 to-indigo-600` | Use a single flat accent color from the project palette, or a subtle tonal gradient within the same hue |
+| **No Inter/Roboto/Arial** | `font-['Inter']`, `font-['Roboto']`, or bare `sans-serif` fallback to Arial | Use `Geist`, `Outfit`, `Satoshi`, `Cabinet Grotesk`, or system font stack (`-apple-system, BlinkMacSystemFont`) |
+| **No emojis in code** | `🎉`, `🚀`, `✨` in React components, headings, or alt text | Replace with SVG icons (Phosphor, Radix) or clean primitives |
+| **No `h-screen`** | `h-screen` on hero sections or full-page layouts | Use `min-h-[100dvh]` to prevent mobile browser chrome layout jump |
+| **No `div` onClick as button** | `<div onClick={...} className="cursor-pointer">` | Use `<button type="button">` or `<button type="submit">` with proper styling |
+| **No lorem ipsum** | `Lorem ipsum dolor sit amet...` or any lorem ipsum variant | Use real or realistic domain-appropriate text. For placeholder text, use context-aware content (e.g., "Product launch strategy Q3 2026" not "Lorem ipsum"). |
+| **No generic data** | "Jane Doe", "John Smith", "$99/mo", "amazing", "powerful" | Use realistic names, numbers, and domain-appropriate language. No filler testimonials, no startup slop words. |
+
+**Before/After examples:**
+
+```tsx
+// BEFORE — MUST fix: purple gradient + emoji + h-screen
+<section className="h-screen bg-gradient-to-r from-purple-500 to-indigo-600">
+  <h1>🚀 Launch Your App</h1>
+</section>
+
+// AFTER
+<section className="min-h-[100dvh] bg-zinc-900">
+  <h1 className="text-white">Launch Your App</h1>
+</section>
+```
+
+```tsx
+// BEFORE — MUST fix: div as button
+<div onClick={handleSubmit} className="cursor-pointer rounded px-4 py-2 bg-blue-500 text-white">
+  Submit
+</div>
+
+// AFTER
+<button type="button" onClick={handleSubmit} className="rounded px-4 py-2 bg-blue-500 text-white">
+  Submit
+</button>
+```
+
+---
+
+### SHOULD Rules (Warnings)
+
+Patterns that signal low-quality AI output. Fix unless you have a specific reason not to.
+
+| Rule | Anti-pattern | Fix |
+|------|-------------|-----|
+| **Use 4pt spacing scale** | Arbitrary spacing: `p-3`, `gap-3`, `m-5` | Use 4pt increments: `p-2` (8px), `p-4` (16px), `p-6` (24px), `p-8` (32px), `p-12` (48px) |
+| **Use semantic color tokens** | Raw hex: `text="#3B82F6"`, `bg="#1E40AF"` | Use Tailwind semantic tokens: `text-primary`, `bg-primary-700`, `text-muted-foreground` |
+| **Max 1 accent color** | Two+ accent colors competing: blue buttons + green badges + orange links | Pick one accent hue. Use it for all interactive elements. Use neutrals for everything else. |
+| **Skeleton loaders, not spinners** | Full-page spinner: `<div className="flex justify-center"><Spinner /></div>` | Match the layout with skeleton bars: `<div className="space-y-4"><div className="h-4 w-3/4 rounded bg-zinc-200 animate-pulse" />...` |
+| **Left-align content by default** | Every section centered (`text-center`, `mx-auto`) | Left-align content blocks. Reserve center for short hero headlines only. |
+| **Use CSS Grid for layouts** | `flex-wrap` with `w-[calc(33%-1rem)]` math | Use `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6` |
+| **Consistent border-radius** | Mixed: `rounded-sm` on cards, `rounded-2xl` on inputs, `rounded-full` on buttons | Pick one radius tier: `rounded-md` (6px) for cards/buttons, `rounded-lg` (8px) for modals. Don't mix. |
+
+**Before/After examples:**
+
+```tsx
+// BEFORE — SHOULD fix: arbitrary spacing, raw hex, flex percentage
+<div className="flex flex-wrap p-3 gap-3">
+  {items.map(i => (
+    <div className="w-[calc(50%-6px)] bg="#F3F4F6" p-2.5">
+      {i.name}
+    </div>
+  ))}
+</div>
+
+// AFTER
+<div className="grid grid-cols-1 sm:grid-cols-2 gap-4 p-4">
+  {items.map(i => (
+    <div className="bg-muted p-4 rounded-md">
+      {i.name}
+    </div>
+  ))}
+</div>
+```
+
+```tsx
+// BEFORE — SHOULD fix: spinner loading state
+{loading && <div className="flex justify-center py-12"><Spinner /></div>}
+
+// AFTER
+{loading && (
+  <div className="space-y-4 p-4">
+    <div className="h-4 w-3/4 rounded bg-zinc-200 animate-pulse" />
+    <div className="h-4 w-1/2 rounded bg-zinc-200 animate-pulse" />
+    <div className="h-4 w-5/6 rounded bg-zinc-200 animate-pulse" />
+  </div>
+)}
+```
+
+---
+
+### NEVER Rules (Blocking — Rewrite Entirely)
+
+Patterns that signal complete design failure. Block the output and rewrite.
+
+| Rule | Why it's blocked |
+|------|-----------------|
+| **Pure black `#000`** | Never looks good in UI. Destroys depth. Use `#111`, `#18181b`, or `#1c1c1e` instead. |
+| **Centered hero with low variance** | Forces boring landing pages. Use split-screen or left-aligned content. Establish a layout variance baseline (see `design-taste-frontend` for DESIGN_VARIANCE dial if loaded). |
+| **3-column identical cards** | Three identical feature cards is the #1 sign of AI-generated UI. Vary layout: 2-col then 1-col, or 4-col grid, or asymmetric bento. |
+| **Glassmorphism as decoration** | `backdrop-blur-xl bg-white/10` applied to elements with no functional need for depth. Use flat surfaces or layered shadows instead. |
+| **Bounce/elastic easing** | `cubic-bezier(0.68, -0.55, 0.265, 1.55)` or CSS `bounce` animation on UI elements. Use `ease-out` or spring-based motion instead. |
+| **Gray text on colored backgrounds** | White text on pastel backgrounds or gray text on white. Always meet 4.5:1 contrast. |
+
+**Before/After examples:**
+
+```tsx
+// BEFORE — NEVER: pure black + 3 identical cards + glassmorphism
+<div className="bg-black text-white">
+  <div className="backdrop-blur-xl bg-white/10 rounded-2xl p-8">
+    <div className="grid grid-cols-3 gap-4">
+      <div className="text-center p-6"><h3>Feature 1</h3><p>Description</p></div>
+      <div className="text-center p-6"><h3>Feature 2</h3><p>Description</p></div>
+      <div className="text-center p-6"><h3>Feature 3</h3><p>Description</p></div>
+    </div>
+  </div>
+</div>
+
+// AFTER
+<div className="bg-[#111] text-zinc-100">
+  <div className="max-w-7xl mx-auto px-6 py-24">
+    <div className="grid grid-cols-1 lg:grid-cols-3 gap-8">
+      <div className="lg:col-span-2 bg-zinc-900 border border-zinc-800 rounded-lg p-8">
+        <h3 className="text-xl font-semibold">Feature 1</h3>
+        <p className="text-zinc-400 mt-2">Description</p>
+      </div>
+      <div className="bg-zinc-900 border border-zinc-800 rounded-lg p-8">
+        <h3 className="text-xl font-semibold">Feature 2</h3>
+        <p className="text-zinc-400 mt-2">Description</p>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## Pipeline Position
+
+```
+baseline-ui ──► design-taste-frontend ──► frontend-design ──► frontend-ui-engineering
+   ↑
+   Quick deslop pass before any design or implementation work
+```
+
+Run `baseline-ui` first when starting any frontend work. It catches the most common AI-generation artifacts so downstream skills can focus on real design quality.
+
+## Don't
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Purple/indigo gradients as primary palette | Single flat accent color from project palette | Purple gradient is the #1 AI-generation fingerprint |
+| Inter, Roboto, Arial fonts | Geist, Outfit, Satoshi, or system font stack | Overused fonts signal generic AI output |
+| Emojis in JSX/TSX or CSS content | SVG icons (Phosphor, Radix) or clean primitives | Emojis look unprofessional in production UI |
+| `h-screen` on hero sections | `min-h-[100dvh]` | h-screen causes layout jump on mobile browsers |
+| `<div onClick>` as interactive element | `<button type="button">` with proper styling | div onClick breaks keyboard and screen reader access |
+| Pure black `#000` in UI | Off-black (`#111`, Zinc-950, or `#1c1c1e`) | Pure black destroys visual depth |
+| 3-column identical card grids | Varied 2-col, asymmetric bento, or alternating layouts | Three identical cards is the #1 AI UI tell |
+| Glassmorphism without functional purpose | Flat surfaces or layered shadows | Decorative glassmorphism adds visual noise |
+| Bounce/elastic CSS easing on UI elements | `ease-out` or spring-based motion | Bounce easing feels unnatural for UI |
+
+## Verification
+
+- [ ] No `h-screen` — all full-height containers use `min-h-[100dvh]`
+- [ ] No `div` with `onClick` used as a button — all interactive elements use `<button>`, `<a>`, or proper ARIA roles
+- [ ] No emojis in any JSX/TSX or CSS content
+- [ ] No purple/indigo-blue gradients
+- [ ] No Inter, Roboto, or Arial font references
+- [ ] No pure black (`#000`/`#000000`) color values
+- [ ] Spacing uses 4pt scale (multiples of 4: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96)
+- [ ] No 3-column identical card patterns
+- [ ] No glassmorphism (`backdrop-blur` + semi-transparent bg) used purely decoratively
+- [ ] No bounce/elastic CSS easing curves on UI elements
+- [ ] Skeleton loaders used instead of spinners for content loading states
+
+### Self-Critique (Run Before Output)
+
+1. **Contrast Check:** Are all text/background combinations ≥ 4.5:1 ratio? No low-contrast gray text on colored backgrounds.
+2. **Data Check:** Is every text string real or realistic? No "Lorem ipsum", "Jane Doe", "$99", or filler words ("amazing", "powerful").
+3. **Grid Check:** Do all spacing values use the 4pt scale (4, 8, 12, 16, 24, 32, 48, 64)? No arbitrary pixel values.
+4. **Font Check:** No Inter, Roboto, Arial, or other AI-default fonts. No oversized H1 (>40px without explicit design reason).
+5. **Color Check:** No pure black `#000`, no purple/indigo gradients, no oversaturated accents like `#FF4500`.

package/dist/template/.pi/skills/design-taste-frontend/SKILL.md

@@ -3,6 +3,8 @@ name: design-taste-frontend
 description: Use when building any web UI as the BASE aesthetic layer to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
 ---
 
+**Aesthetic Context:** This is a premium aesthetic layer. Read `.pi/DESIGN.md` first to internalize the project's visual identity — every typographic, color, and spacing rule here is shaped by that mood. Design taste means the design feels intentional, not AI-generated.
+
 ## When to Use
 
 - When building any web UI that needs to override default LLM design biases
@@ -15,7 +17,7 @@ description: Use when building any web UI as the BASE aesthetic layer to overrid
 - For non-UI tasks (backend, CLI, data processing)
 
 
-# High-Agency Frontend Skill
+# Design Taste Frontend
 
 ## 1. ACTIVE BASELINE CONFIGURATION
 * DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
@@ -43,7 +45,6 @@ Unless the user explicitly specifies a different stack, adhere to these structur
   * **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
 * **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
 
-
 ## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
 LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
 
@@ -55,7 +56,7 @@ LLMs have statistical biases toward specific UI cliché patterns. Proactively co
 
 **Rule 2: Color Calibration**
 * **Constraint:** Max 1 Accent Color. Saturation < 80%.
-* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
+* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g., Emerald, Electric Blue, or Deep Rose).
 * **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
 
 **Rule 3: Layout Diversification**
@@ -106,36 +107,50 @@ To actively combat generic AI designs, systematically implement these high-end c
 * **4-7 (Daily App Mode):** Normal spacing for standard web apps.
 * **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
 
-## 7. AI TELLS (Forbidden Patterns)
-To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
+## 7. Don't
 
 ### Visual & CSS
-* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
-* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
-* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
-* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
-* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Neon/outer box-shadow glows | Inner borders or subtle tinted shadows | Glows are an instant AI-design signature |
+| Pure black `#000000` | Off-black, Zinc-950, or Charcoal | Pure black destroys visual depth |
+| Oversaturated accent colors | Desaturated accents blending with neutrals | High-saturation colors look amateurish |
+| Gradient text on large headers | Single solid heading color | Gradient text is an AI design cliché |
+| Custom mouse cursors | Default system cursor | Custom cursors hurt performance and accessibility |
 
 ### Typography
-* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
-* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
-* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Inter as display typeface | Geist, Outfit, Cabinet Grotesk, or Satoshi | Inter signals default AI-generated output |
+| Oversized H1 (>40px without reason) | Control hierarchy with weight and color, not just massive scale | Giant headings scream without communicating |
+| Serif fonts on dashboards or data UIs | Sans-serif for data; serif only for editorial/creative contexts | Serifs on dashboards feel out of place |
 
 ### Layout & Spacing
-* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
-* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
 
-### Content & Data (The "Jane Doe" Effect)
-* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
-* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
-* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
-* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
-* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| 3-column identical card layouts | 2-column zig-zag, asymmetric grid, or horizontal scroll | Three equal cards is the #1 AI UI tell |
+| Floating elements with awkward gaps | Mathematically perfect padding and margin alignment | Misaligned spacing reads as sloppy |
+
+### Content & Data
 
-### External Resources & Components
-* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
-* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
-* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Generic placeholder names (John Doe, Sarah Chan) | Creative, realistic-sounding names (Dr. Sarah Chen, Marcus Okonkwo) | Generic names feel fake and unprofessional |
+| Emoji avatars or Lucide user icons | Creative photo placeholders or styled SVGs | Emoji avatars degrade perceived quality |
+| Fake or predictable numbers (`99.99%`, `50%`, `$99/mo`) | Organic, messy data (`47.2%`, `$12,450`, `+18.3%`) | Round numbers look fabricated |
+| Startup slop names (Acme, Nexus, SmartFlow) | Premium, contextual brand names | Startup-slop names are a dead AI giveaway |
+| Filler words (Elevate, Seamless, Unleash, Next-Gen) | Concrete, specific verbs and descriptions | AI copywriting clichés destroy credibility |
+| Unsplash URLs in image sources | `picsum.photos/seed/{seed}/800/600` or SVG placeholders | Unsplash links break and leave broken images |
+| Default shadcn/ui appearance | Customized radii, colors, and shadows | Default shadcn reads as AI-generated |
+
+### Code Quality
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Sloppy output — misaligned elements, poor spacing, generic feel | Meticulously refined, visually striking, memorable output | Production-ready cleanliness is non-negotiable for premium UI |
 
 ## 8. THE CREATIVE ARSENAL (High-End Inspiration)
 Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
@@ -143,7 +158,7 @@ Do not default to generic UI. Pull from this library of advanced concepts to ens
 ### The Standard Hero Paradigm
 * Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
 
-### Navigation & Menüs
+### Navigation & Menus
 * **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
 * **Magnetic Button:** Buttons that physically pull toward the cursor.
 * **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
@@ -237,19 +252,15 @@ Evaluate your code against this matrix before outputting. This is the **last** f
 - [ ] Are cards omitted in favor of spacing where possible?
 - [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?
 
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "Default LLM styles are acceptable" | Default LLM styles are generic. Aesthetic intent signals craftsmanship. |
-| "Typography doesn't matter for functionality" | Typography is 95% of web design. Bad type ruins even good layouts. |
-| "I'll refine the design later" | Design debt compounds like technical debt. Fix it in the first pass. |
-| "Users won't notice the details" | Users may not articulate it, but they feel quality. Details accumulate into perception. |
-
-## Red Flags
-
-- Default LLM spacing and typography used without adjustment
-- No explicit font pairing decisions documented
-- Color palette not extracted from project context
-- Components lack hover/focus/active state differentiation
-- Visual hierarchy is flat — everything looks equally important
+## Verification
+
+- [ ] Aesthetic baseline config (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY) respected throughout output
+- [ ] No banned fonts (Inter, Roboto, Arial, system-ui) used as display font
+- [ ] No AI purple/blue gradients, no neon glows, no pure black (`#000000`)
+- [ ] No centered Hero/H1 when DESIGN_VARIANCE > 4
+- [ ] No 3-column identical card layouts
+- [ ] All interactive states (loading, empty, error) implemented
+- [ ] Mobile layout collapse verified at 320px, 768px
+- [ ] `min-h-[100dvh]` used instead of `h-screen` for full-height sections
+- [ ] No emojis in code, markup, or alt text
+- [ ] Perpetual animations isolated in their own Client Components