oh-my-opencode 4.10.0 → 4.11.0

package/packages/shared-skills/skills/frontend/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: frontend
+description: "MUST USE for ANY frontend, web UI, UX, or visual work — building, styling, or redesigning pages/components, React project setup, performance audits, design QA. Routes three rulesets: design (anti-slop taste router over 12 taste skills + 69 brand DESIGN.md refs — Apple, Stripe, Linear, Notion, Vercel, Claude, Nike — plus React dev tooling gate: react-grab, react-scan, react-doctor), perfection (Lighthouse 100 in every category via real Playwright Chromium audits, NEVER the lighthouse CLI, never by weakening UX), ui-ux-db (searchable 50+ styles, 97 palettes, 57 font pairings, 99 UX guidelines). Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, taste, premium, luxury, minimal, brutalist, Awwwards, anti-slop, polish, DESIGN.md, mockup, react setup, react-scan, react-doctor, lighthouse, performance, Core Web Vitals, LCP, CLS, INP, SEO, accessibility, a11y, WCAG, audit my site, make this faster, color palette, font pairing, looks generic, make it pretty, like X brand."
+---
+
+# Frontend
+
+This file is a router, not a rulebook. The rules live in three rulesets under `references/`; your first job is to load the smallest set of files that covers the request, state which you loaded in one sentence, then execute under their guidance. Loading nothing and freestyling produces the generic AI-slop output this skill exists to prevent; loading everything wastes context and creates contradictory instructions.
+
+## Phase 0 — Route (before any UI work)
+
+| Request involves… | Read |
+|---|---|
+| ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
+| Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
+| Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
+
+**For implementation work, design + perfection load together.** A page that hits Lighthouse 100 but looks like AI slop has failed; a page that looks beautiful but ships a 2 MB bundle has failed. Both win or neither does.
+
+## Ruleset 1 — design (`references/design/`)
+
+The reference library has one architecture file, 12 taste skills (Layer A — *how to execute*), and 69 brand design systems (Layer B — *what it should look like*). Most non-trivial tasks load **one Layer A + one Layer B**. `README.md` carries the full routing flow, stacking rules, anti-patterns, and the mandatory browser-based Design QA phase; `_INDEX.md` catalogs all 81 files with mood-to-brand mappings — read it whenever routing is not obvious from the tables below.
+
+### Layer 0 — architecture
+
+| File | Read when |
+|---|---|
+| `design-system-architecture.md` | The project has no `DESIGN.md` (defines the 7-section structure you must create first), or you are extracting a design system from existing UI code. |
+
+### Layer A — taste skills (pick AT MOST ONE style skill; they encode opposing philosophies)
+
+| File | Read when the user says… |
+|---|---|
+| `taste-skill.md` | Nothing style-specific — "make a good UI". The default all-rounder. |
+| `gpt-tasteskill.md` | "Awwwards-tier", "wow factor", "cinematic", "scroll-triggered", or `taste-skill` results felt too safe. |
+| `minimalist-skill.md` | "minimal", "clean", "Notion-like", "Linear-like", "editorial". |
+| `brutalist-skill.md` | "brutalist", "raw", "Swiss", "experimental", "anti-design". |
+| `soft-skill.md` | "premium", "luxury", "calm", "expensive", "spa", "boutique", "elegant". |
+| `redesign-skill.md` | Improving EXISTING UI — "this looks bad", "fix the design". Audit-first workflow; never use on greenfield. |
+| `image-to-code-skill.md` | "Generate the design first, then code it." Pair with one imagegen file below. |
+| `output-skill.md` | Stacks on any style skill when output is incomplete — placeholders, `// TODO`, half-done components. |
+| `stitch-skill.md` | Stacks on any style skill for Google Stitch compatibility or a `DESIGN.md` doc export. |
+| `imagegen-frontend-web.md` / `imagegen-frontend-mobile.md` / `imagegen-brandkit.md` | Image-only output (mockup, app-screen concepts, brand board). These NEVER write code — switch to `image-to-code-skill.md` if code is wanted. |
+
+### Layer B — brand design systems (orthogonal to Layer A; stack freely)
+
+When the user names a brand or site — "Linear-style", "like Stripe's landing" — load `references/design/<brand>.md` as the token source of truth (palette, type scale, components, do/don'ts). Coverage includes `apple` `stripe` `linear.app` `notion` `vercel` `claude` `figma` `airbnb` `nike` `tesla` `spotify` `raycast` `revolut` and ~56 more; the full list with mood shortcuts is in `_INDEX.md`. Extract the tokens and apply them to the project's own content — never copy logos or trademarked imagery. If the named brand is missing, fall back to a Layer A mood match or the `open-design` skill.
+
+### React dev tooling
+
+| File | Read when |
+|---|---|
+| `react-dev-tooling-skill.md` | A React project lacks react-grab / react-scan / react-doctor, or you need per-framework install snippets and the dev-only gating pattern (`NODE_ENV === 'development'`). |
+
+## Ruleset 2 — perfection (`references/perfection/`)
+
+| File | Read when |
+|---|---|
+| `README.md` | Any frontend code is written or audited. Carries the seven tenets: real-browser audits only, 100-in-every-category floor, fix-at-the-architecture, never weaken UX for points, design-system compliance checks, and the response format for audit reports. |
+| `react-perf-tooling.md` | Before ANY React audit. The Playwright + `playwright-lighthouse` + `react-scan/lite` injection recipe, per-route render budgets, and the React-specific root-cause checklist. Lighthouse 100 with 30+ unnecessary renders is NOT done. |
+
+Audit CLI (build for production first; never measure a dev server):
+
+```bash
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000
+```
+
+Run mobile AND desktop presets, 3–5 runs, take the median, diagnose from the JSON report.
+
+## Ruleset 3 — ui-ux-db (`references/ui-ux-db/`)
+
+`README.md` documents the search CLI and the master-plus-overrides persistence pattern. The CLI (run from the ruleset directory so it finds `data/`):
+
+```bash
+python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --design-system -p "Project"   # full design-system generation
+python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --domain <domain>             # targeted lookup
+python3 $SKILL_DIR/references/ui-ux-db/scripts/search.py "<query>" --stack <stack>               # stack best practices
+```
+
+Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `web` `prompt`. Stacks: `html-tailwind` (default) `react` `nextjs` `vue` `svelte` `astro` `swiftui` `react-native` `flutter` `shadcn` `jetpack-compose`.
+
+## Quick routes — most common requests
+
+| Request | Load |
+|---|---|
+| "Build a landing page" (no direction given) | `design/README.md` + `design/taste-skill.md` + `perfection/README.md` |
+| "Linear-style landing page" | `design/README.md` + `design/linear.app.md` + `design/taste-skill.md` + `perfection/README.md` |
+| "Premium SaaS hero like Stripe" | `design/README.md` + `design/stripe.md` + `design/soft-skill.md` + `perfection/README.md` |
+| "Improve this existing dashboard" | `design/README.md` + `design/redesign-skill.md` + `perfection/README.md` |
+| "Audit my site" / "make this page faster" | `perfection/README.md` (+ `perfection/react-perf-tooling.md` if React) |
+| "Mockup image of a fintech app" — no code | `design/imagegen-frontend-mobile.md` (+ a Layer B brand if named) |
+| "What palette/fonts fit a wellness brand?" | `ui-ux-db/README.md` → search CLI |
+| "Set up this React project" | `design/README.md` + `design/react-dev-tooling-skill.md` |
+
+## Shared axioms (all three rulesets agree — apply always)
+
+- **No design system = no UI work.** `DESIGN.md` exists before components do; every color, font size, and spacing value traces back to a token in it.
+- **Never weaken UX to buy points.** No dropping animations, hiding content, or simplifying interactions for a score or a deadline.
+- **No emojis as icons.** SVG icon sets only (Lucide, Heroicons, Radix, Phosphor).
+- **GPU-composited animation only** — `transform`, `opacity`, `filter`; never animate layout properties.
+- **Verify in a real browser before declaring done.** Screenshots at 375 / 768 / 1280px; hover, focus, loading, empty, and error states all exercised.
+
+## When to load something else instead
+
+| Situation | Load |
+|---|---|
+| Brand/style not among the 69 in `references/design/`, or the user says "Open Design" | `open-design` skill — the local nexu-io/open-design library (137+ design skills, 150+ design systems) |
+| Driving a browser for the Design QA phase | `agent-browser` skill |
+| Pure TypeScript/logic work with zero visual surface | `programming` skill alone — this skill adds nothing there |
+
+## Activation
+
+Use for any frontend, web UI, UX, visual, design, styling, layout, animation, performance, accessibility, or SEO work — building, redesigning, auditing, or generating mockups. Not for backend, CLI, or pure-logic tasks with no visual surface.

package/packages/shared-skills/skills/frontend/references/design/README.md

@@ -0,0 +1,240 @@
+
+# Frontend Design Router
+
+You are an elite frontend design engineer. Your only job in this skill is to **route correctly**: pick the right reference file(s), load them into context, then execute with their guidance. The reference files contain the actual design rules — this file just decides which to consult.
+
+## Why route at all
+
+`taste-skill.md` alone is a strong default, but it does not commit to any specific aesthetic. When the user has named a clear visual direction (a brand, a style label, an existing site to mimic), a dedicated reference produces sharper output than the generic default. Loading the wrong reference, or none, is how you produce the bland generic SaaS slop these skills exist to prevent.
+
+The library lives flat in this directory (`references/design/`, max depth 1) and has two conceptual layers, and **most non-trivial tasks load one from each layer**:
+
+- **Layer A — taste skills (12 files):** how to execute. Discipline, motion physics, spacing rules, anti-slop guardrails, output completeness. Filenames end in `-skill.md` or start with `imagegen-`.
+- **Layer B — design systems (69 files):** what it should look like. Concrete color/type/component tokens for one specific brand aesthetic. Filenames are brand names (`claude.md`, `notion.md`, `stripe.md`, …).
+
+A combined directory of all 81 reference files is at `_INDEX.md`. **Read that index before loading anything** unless the routing is obvious — it has the full mood-mapping and stacking rules in one place.
+
+## Open Design Library
+
+For broader brand/style coverage, load the `open-design` skill — the local `nexu-io/open-design` library (150+ design systems).
+
+Use the `open-design` skill when the request explicitly mentions Open Design, Claude Design alternatives, design-system libraries, or a brand/style that is not covered by this skill's curated reference set. Treat Open Design as the expanded reference library; keep this skill responsible for routing discipline, design-system gating, and frontend execution quality.
+
+## Phase 0 — Design System Gate (MANDATORY, runs before routing)
+
+Before touching any UI code, before routing to any reference, before even thinking about aesthetics — run this gate.
+
+### Check: Does the project have a `DESIGN.md`?
+
+**Search for it:** Look at project root, then `docs/`, then `src/`. Any file named `DESIGN.md`, `design-system.md`, or `design-tokens.md`.
+
+#### If NO design system exists → CREATE ONE FIRST
+
+1. Read `design-system-architecture.md` — it defines the exact structure.
+2. Explore the project: what is the product domain? Who are the users? What feeling should it evoke?
+3. If the project has existing UI code, **extract** the implicit system (colors, fonts, spacing already in use) rather than inventing from scratch.
+4. If the project is greenfield, **ask the user one question**: "What should this feel like?" — or infer from context.
+5. Write `DESIGN.md` at project root following the 7-section structure from the reference.
+6. **Do not proceed to any component implementation until `DESIGN.md` exists and is committed to context.**
+
+#### If YES design system exists → READ IT, FOLLOW IT
+
+1. Read the entire `DESIGN.md` into context.
+2. Every color, font size, spacing value, and component pattern you produce MUST reference tokens from this file.
+3. If you need a token that doesn't exist, **add it to `DESIGN.md` first**, then use it.
+4. Never introduce raw hex codes, arbitrary px values, or ad-hoc component patterns that bypass the system.
+
+**This gate is non-negotiable. No design system = no UI work. Period.**
+
+
+## Phase 0.5 — React Dev Tooling Gate (MANDATORY for React projects)
+
+If the project ships React (`react` in `package.json`), three dev-only tools are installed by default before any UI implementation. The user opts out, not in.
+
+### Check: are react-grab, react-scan, react-doctor wired?
+
+Grep the entry file (`app/layout.tsx`, `pages/_document.tsx`, `src/main.tsx`, `src/index.tsx`, `app/root.tsx`) for `react-grab` and `react-scan`. Check `package.json` and the skills directory for `react-doctor` traces.
+
+#### If NO → INSTALL THEM NOW
+
+Run from project root:
+
+```bash
+npx grab@latest init                    # react-grab — UI element → AI source context
+npx react-doctor@latest install         # react-doctor — agent-skill install + static scan
+npx react-scan@latest init              # react-scan — render highlighter
+```
+
+All three CLIs auto-detect the framework and gate the runtime tools on `process.env.NODE_ENV === 'development'` / `import.meta.env.DEV`. **Read `react-dev-tooling-skill.md`** for manual install snippets per framework (Next.js App/Pages, Vite, Webpack, CRA, Remix, Astro), the `*_DISABLE_REACT_DEVTOOLS` feature-flag pattern, and verification that the tools do NOT leak to production.
+
+#### If YES → CONFIRM THE DEV GATE
+
+Open the entry file. Each tool must sit behind a `NODE_ENV === 'development'` or `import.meta.env.DEV` check. If not, fix the gate before proceeding — the rest of this skill assumes these tools never reach production.
+
+### Skip ONLY when
+
+- The project is not React (Solid / Svelte / Vue / Qwik / vanilla).
+- The user said "no extra dev dependencies".
+- The project is a React library (no entry file to inject into). Static scan via react-doctor still applies.
+
+**This gate is non-negotiable for React projects.** No dev tooling = the agent flies blind on render perf and gets 2× slower edit cycles. Period.
+
+
+## Routing decision flow
+
+Run through this in order and stop at the first match. Do not skip — earlier rules dominate later ones.
+
+### Step 1 — Did the user name a specific brand or site?
+
+Phrasings: "make it look like Linear", "Stripe-style buttons", "Notion-feel sidebar", "like {brand}'s landing page", or pasting a screenshot of a known brand site.
+
+**Action:** Open `_INDEX.md`, find the brand under "Layer B — Design Systems", then load `<brand>.md`. Use it as the project's design system source of truth (color hex values, type scale, component specs, do/don'ts).
+
+**Then also load Layer A** — usually `taste-skill.md` for execution discipline (the design system says *what*, the taste-skill says *how* to write the React/CSS without slop).
+
+If the user names a brand not in the index, fall back to Step 2 + a mood-based shortcut from the index.
+
+### Step 2 — Did the user describe a clear style/mood?
+
+Map their phrasing to one taste-skill style file:
+
+| User says... | Load |
+|---|---|
+| "minimal", "clean", "Notion-like", "Linear-like", "editorial", "boring is good" | `minimalist-skill.md` |
+| "brutalist", "raw", "Swiss", "experimental", "industrial", "anti-design", "unstyled" | `brutalist-skill.md` |
+| "premium", "luxury", "calm", "expensive", "spa", "wellness", "boutique", "elegant" | `soft-skill.md` |
+| "Awwwards-level", "wow factor", "magnetic", "scroll-triggered", "high-variance", "cinematic", "make it crazy" | `gpt-tasteskill.md` |
+| Nothing specific — just "make a good UI" | `taste-skill.md` (default all-rounder) |
+
+You may also load a brand DESIGN.md from Layer B as a *concrete reference* if the user's mood maps cleanly (see the "Mood-based shortcuts" section in `_INDEX.md`).
+
+### Step 3 — Is this a *redesign* of existing UI, not a fresh build?
+
+Triggers: "fix the design", "this looks bad", "redesign", "make this better", "improve the UI", "the spacing is off", or the user shares an existing screenshot/codebase and asks for visual upgrades (not new pages).
+
+**Action:** Load `redesign-skill.md`. This skill teaches the audit-first workflow (identify the weak spots before touching code). Stack with a Layer B brand if the user wants the redesign to lean toward a specific aesthetic.
+
+Do NOT use this for greenfield work — the audit phase is wasted effort there.
+
+### Step 4 — Is this an image-first workflow?
+
+Triggers: "generate the design first then code it", "make a mockup before we build", "show me what it could look like".
+
+**Action:** Load both:
+- `image-to-code-skill.md` (the workflow: generate → analyze → implement)
+- `imagegen-frontend-web.md` for web, or `imagegen-frontend-mobile.md` for mobile screens
+
+If the user wants only the imagery (no code), load only the imagegen file.
+
+### Step 5 — Image-only requests (no code)
+
+Triggers: "generate a mockup image", "create a brand kit board", "design reference image", "moodboard".
+
+**Action:** Load only the relevant imagegen file. Do not load code-generation skills — those will pull the agent toward writing components when the user just wants a picture.
+
+| Want | Load |
+|---|---|
+| Website mockup image | `imagegen-frontend-web.md` |
+| Mobile app screen images | `imagegen-frontend-mobile.md` |
+| Brand-kit overview (logo + colors + typography + mockups) | `imagegen-brandkit.md` |
+
+### Step 6 — Stitch / DESIGN.md export
+
+Triggers: "Google Stitch", "compatible with Stitch", "also write a DESIGN.md", "give me the design as a doc".
+
+**Action:** Add `stitch-skill.md` on top of whatever you loaded in Steps 1–4.
+
+### Step 7 — The agent has been lazy
+
+Triggers (mid-conversation, not initial): "you keep leaving placeholders", "stop with the // TODO", "finish the implementation", "no half-done components".
+
+**Action:** Add `output-skill.md` on top of whatever is currently loaded. This stacks cleanly — it is purely about output completeness, not visual style.
+
+## Stacking rules (read this once, internalize it)
+
+1. **At most one Layer A *style* skill at a time.** A layout cannot be both `minimalist-skill` and `brutalist-skill` simultaneously — they encode opposite spacing and typography philosophies. Pick one.
+2. **`taste-skill.md` and `gpt-tasteskill.md` are also style-skills** — do not stack them with `minimalist`, `brutalist`, or `soft`. They are alternative defaults at different intensity levels.
+3. **`output-skill.md` and `stitch-skill.md` stack on top of any style skill.** They add discipline and output format, not visual direction.
+4. **`redesign-skill.md` replaces a style-skill** when the task is auditing, not building. Stack a Layer B brand if the user wants a specific direction.
+5. **`image-to-code-skill.md` pairs with one imagegen skill** for the full flow.
+6. **Layer B (brand DESIGN.md) is orthogonal to Layer A.** You can pair any Layer A skill with any Layer B brand. Use Layer B as the source of color/type/component tokens; let Layer A drive the execution discipline.
+
+## Anti-patterns — do not do these
+
+- **Don't load nothing and just freestyle.** That produces the exact "generic AI SaaS slop" — purple-blue gradient backgrounds, rounded-2xl-on-everything, three feature cards in a grid, generic Inter font, lorem ipsum. The skills exist precisely to prevent this.
+- **Don't load five files "to be safe".** That blows context and creates contradictory rules. Pick deliberately.
+- **Don't ignore the user's named brand.** If they say "Linear-style" and you build something that doesn't match Linear's actual aesthetic (purple, ultra-tight spacing, mono accents, etc.), you have failed the routing.
+- **Don't apply a Layer B brand verbatim if the project is not that brand.** The DESIGN.md captures *inspiration* — extract the tokens (palette, type scale, component patterns) and apply them to the project's own content. Do not copy logos or trademarked imagery.
+- **Don't use imagegen skills to write code.** They are explicitly image-only. The agent has been observed trying to "describe" the image as React code — that is the wrong skill, switch to `image-to-code-skill.md` instead.
+- **Don't suppress style differences with `as any` or `@ts-ignore` to make a borrowed component work.** That is type-safety slop. Adapt the component cleanly.
+
+## Execution checklist after routing
+
+Once references are loaded, before writing any UI code:
+
+1. **`DESIGN.md` was read** (or created) in Phase 0. If you skipped it, stop and go back now.
+2. **Verify dependencies.** Read `package.json`. Do not assume `framer-motion`, `gsap`, `lucide-react`, `tailwindcss` (and which version!) are installed. If missing, output the install command first.
+3. **Tailwind version lock.** Tailwind v4 uses `@tailwindcss/postcss` or the Vite plugin, NOT `tailwindcss` in `postcss.config.js`. v3 uses different config syntax. Pick based on what's in `package.json`.
+4. **No emojis in code, markup, alt text, or visible UI.** Replace with proper icons (Radix, Phosphor, Lucide) or clean SVG. Emojis are slop signal.
+5. **Viewport stability.** Use `min-h-[100dvh]`, never `h-screen`, for full-height heroes — `h-screen` causes catastrophic jumps on iOS Safari.
+6. **Server vs client components (Next.js).** If motion/state/portals are involved, isolate as a `'use client'` leaf component. Don't bleed `'use client'` to the page level.
+7. **Match the project's existing patterns FIRST.** If the codebase already uses CSS Modules, don't introduce Tailwind. If it uses styled-components, don't introduce CSS-in-JS variants. The references guide *style*, not *infrastructure*.
+8. **All tokens trace back to `DESIGN.md`.** No orphan hex codes, no magic px values. If you need a new token, update `DESIGN.md` first.
+9. **New reusable patterns (used 2+ times) get documented back into `DESIGN.md` Section 5.**
+
+## Quick lookup table — most common requests
+
+| User asks for... | Load these |
+|---|---|
+| "Build me a landing page" (no other info) | `taste-skill.md` |
+| "Build me a Linear-style landing page" | `linear.app.md` + `taste-skill.md` |
+| "Make it Notion-like and minimal" | `notion.md` + `minimalist-skill.md` |
+| "Premium SaaS hero, like Stripe" | `stripe.md` + `soft-skill.md` |
+| "Brutalist portfolio" | `brutalist-skill.md` (+ optional `nike.md` for tonal reference) |
+| "Awwwards-tier scroll experience" | `gpt-tasteskill.md` |
+| "Improve this existing dashboard" | `redesign-skill.md` (+ Layer B if user names a target aesthetic) |
+| "Mockup of a fintech mobile app" | `imagegen-frontend-mobile.md` (+ `revolut.md` or `stripe.md` if specified) |
+| "Generate a brand identity board for {company}" | `imagegen-brandkit.md` |
+| "Stop using placeholders" | Add `output-skill.md` to current stack |
+| "Also output a DESIGN.md doc" | Add `stitch-skill.md` to current stack |
+
+## Phase Final — Design QA (MANDATORY, runs after implementation)
+
+After implementation is complete, **before declaring the task done**, run a real browser-based Design QA.
+
+### Why
+
+Code that "looks correct" in an editor is not verified. Colors render differently, spacing collapses, fonts fail to load, responsive breakpoints break, states are missing. The only way to know is to SEE it in a real browser.
+
+### How
+
+1. **Launch the app** in a real browser (use `agent-browser` skill or the project's dev server + screenshot tool).
+2. **Take screenshots** at key breakpoints: mobile (375px), tablet (768px), desktop (1280px).
+3. **Walk the design system checklist** visually:
+   - [ ] Colors match `DESIGN.md` palette — no off-brand colors visible
+   - [ ] Typography hierarchy is clear — headings, body, captions are visually distinct
+   - [ ] Spacing rhythm feels consistent — no cramped or floating elements
+   - [ ] Interactive states work — hover every button, focus every input, toggle every switch
+   - [ ] Empty, loading, and error states exist and look intentional
+   - [ ] Dark mode (if declared in `DESIGN.md`) works completely
+   - [ ] No layout overflow, no horizontal scroll on mobile
+   - [ ] Motion/animation feels smooth — no jank, no missing transitions
+4. **If anything fails**, fix it and re-check. Do not report "done" with visual bugs.
+5. **If you cannot launch a browser** (e.g. no dev server, CI-only environment), state this explicitly and list what you would check. Never silently skip QA.
+
+### QA Report
+
+After passing QA, write a short summary:
+- Breakpoints tested
+- States verified (hover, focus, disabled, loading, error, empty)
+- Design system compliance: all tokens traced back to `DESIGN.md`
+- Issues found and fixed during QA
+- Screenshot evidence (attach or describe)
+
+
+## Final notes
+
+- The reference files are *long* and detailed (200–500 lines each). Loading two or three is fine; loading ten is wasteful and contradictory.
+- After loading references, **state which files you loaded and why** in one short sentence so the user can sanity-check your routing.
+- If the user pushes back on a routing decision ("no, I wanted minimal not soft"), **switch references**, don't argue.
+- If unclear after reading the request twice, **ask one focused question** before loading anything: "Are you going for [X] or [Y]?" — better than wasting context on the wrong reference.

package/packages/shared-skills/skills/frontend/references/design/_INDEX.md

@@ -0,0 +1,189 @@
+# Frontend Design References — Index
+
+All reference files live flat in this directory. Three layers:
+- **Layer 0 — design system architecture** (1 file): the mandatory gate. Defines `DESIGN.md` structure, creation workflow, validation rules. Always loaded by Phase 0 when no design system exists.
+- **Layer A — taste skills** (12 files): how to execute. Discipline, motion, spacing, anti-slop, output completeness.
+- **Layer B — design systems** (69 files): what it should look like. Brand-specific color/type/component tokens.
+
+**Phase 0 runs first** (check/create `DESIGN.md`), then most non-trivial tasks load **one Layer A + one Layer B** together. See the routing flow in the sibling `README.md`.
+
+---
+
+## Layer 0 — Design System Architecture (1)
+
+| File | Purpose | Load when |
+|---|---|---|
+| `design-system-architecture.md` | Defines the 7-section `DESIGN.md` structure (atmosphere, color tokens, typography scale, spacing system, components, motion, depth). Creation workflow for new and existing projects. Validation rules and memory management. | Phase 0 fires and no `DESIGN.md` exists in the project. Also load when extracting a design system from existing code. |
+
+---
+
+## Layer A — Taste Skills (12)
+
+From [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill).
+
+### Code-generation skills (write actual frontend code)
+
+| File | Purpose | Load when |
+|---|---|---|
+| `taste-skill.md` | Default all-rounder. Premium frontend without forcing one narrow visual style. Has 3 dials: DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY. | The user wants a "good-looking" website/app and gives no specific aesthetic direction. Safe default. |
+| `gpt-tasteskill.md` | Stricter, more opinionated. High-variance layouts, stronger GSAP motion, more aggressive anti-slop. Tuned for GPT/Codex. | The user wants something genuinely *Awwwards-tier* — bold layouts, magnetic interactions, scroll-triggered scenes. Or `taste-skill.md` results felt "too safe". |
+| `image-to-code-skill.md` | Image-first workflow: generate premium reference images → analyze → implement to match. | The user says "generate the design first, then code it", or visual quality is the main challenge. Pair with `imagegen-frontend-web.md`. |
+| `redesign-skill.md` | Audits existing UI and surgically fixes weak layout, spacing, hierarchy, color, type. Does NOT rewrite from scratch. | Existing project + "make this better", "improve the UI", "redesign", "this looks bad". DO NOT use on greenfield. |
+| `soft-skill.md` | Polished, calm, expensive-looking. Softer contrast, generous whitespace, premium fonts (Geist, Inter Display), spring motion. | The user says "premium", "luxurious", "calm", "expensive", "spa", "wellness", "boutique", "editorial". Or shows references like Linear, Vercel, Stripe, Apple marketing. |
+| `minimalist-skill.md` | Editorial product UI inspired by Notion/Linear. Restrained monochrome palette, crisp structure, generous whitespace. | The user says "minimal", "clean", "Notion-style", "Linear-style", "editorial", "boring is good", "remove decoration". |
+| `brutalist-skill.md` | BETA. Mechanical visual language. Swiss typography, sharp contrast, raw structure, experimental composition. | The user says "brutalist", "raw", "Swiss", "experimental", "industrial", "unstyled", "anti-design". |
+| `output-skill.md` | Pushes for complete output: no placeholder comments, no `// TODO`, no skipped implementation, no half-done components. | Stack on top of any other skill when the agent has been lazy or the user complains "you keep leaving things undone". Do not use alone. |
+| `stitch-skill.md` | Google Stitch-compatible semantic design rules. Includes the extra DESIGN.md export format. | The user is working with Google Stitch, or explicitly wants Stitch-format output, or wants a DESIGN.md alongside the code. |
+
+### Image-generation skills (do NOT write code, only produce reference imagery)
+
+| File | Purpose | Load when |
+|---|---|---|
+| `imagegen-frontend-web.md` | Generates Awwwards-level website design reference *images*. Strong typography, generous spacing, anti-slop visual discipline. | "Generate a mockup", "design reference image", "show me what it could look like", before any code. Pair with `image-to-code-skill.md` for the full image-to-code flow. |
+| `imagegen-frontend-mobile.md` | Generates premium mobile app screen concepts and flows. iOS, Android, cross-platform. Phone mockup framing, multi-screen consistency. | Mobile app screen mockups, app flow images, iOS/Android UI references — image only, no code. |
+| `imagegen-brandkit.md` | Generates premium brand-kit overview images: logo concepts, color systems, typography specimens, mockups, identity boards. | Brand identity moodboard, logo direction, full brand-kit board. Image only. |
+
+### Layer A stacking rules
+
+1. **At most one *style* skill at a time** (`taste-skill`, `gpt-tasteskill`, `minimalist-skill`, `brutalist-skill`, `soft-skill`, `redesign-skill`, `image-to-code-skill`). They encode opposite philosophies — picking two creates contradictions.
+2. **`output-skill.md` and `stitch-skill.md` stack on top of any style skill.** They add discipline and output format, not visual direction.
+3. **`image-to-code-skill.md` pairs with one imagegen skill** for the full flow.
+4. **Imagegen skills are image-only.** Do not load them when the user actually wants code.
+
+---
+
+## Layer B — Design Systems (69)
+
+From [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md), based on [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/overview/). Each file captures one website's complete visual language: color palette, typography, components, layout principles, depth, do/don't, responsive behavior, and an agent prompt guide.
+
+### How to use
+
+When the user says **"make it look like [Brand]"**, **"[Brand]-style"**, **"like [Brand]'s site"**, or shows that brand's site as a reference, load the corresponding `<brand>.md` file and treat it as the project's design system. Combine with one Layer A taste-skill for execution discipline.
+
+Each file ships with: visual theme, hex color palette + semantic roles, full type hierarchy, button/card/input/nav specs with hover/active states, spacing scale, shadow system, do/don't list, breakpoints, and a ready-to-use agent prompt.
+
+### AI & LLM Platforms (12)
+
+| File | Aesthetic |
+|---|---|
+| `claude.md` | Anthropic's AI assistant. Warm terracotta accent, parchment canvas, literary salon mood, clean editorial layout. |
+| `cohere.md` | Enterprise AI platform. Vibrant gradients, data-rich dashboard aesthetic. |
+| `elevenlabs.md` | AI voice platform. Dark cinematic UI, audio-waveform aesthetics. |
+| `minimax.md` | AI model provider. Bold dark interface with neon accents. |
+| `mistral.ai.md` | Open-weight LLM provider. French-engineered minimalism, purple-toned. |
+| `ollama.md` | Run LLMs locally. Terminal-first, monochrome simplicity. |
+| `opencode.ai.md` | AI coding platform. Developer-centric dark theme. |
+| `replicate.md` | Run ML models via API. Clean white canvas, code-forward. |
+| `runwayml.md` | AI video generation. Cinematic dark UI, media-rich layout. |
+| `together.ai.md` | Open-source AI infrastructure. Technical, blueprint-style design. |
+| `voltagent.md` | AI agent framework. Void-black canvas, emerald accent, terminal-native. |
+| `x.ai.md` | Elon Musk's AI lab. Stark monochrome, futuristic minimalism. |
+
+### Developer Tools & IDEs (7)
+
+| File | Aesthetic |
+|---|---|
+| `cursor.md` | AI-first code editor. Sleek dark interface, gradient accents. |
+| `expo.md` | React Native platform. Dark theme, tight letter-spacing, code-centric. |
+| `lovable.md` | AI full-stack builder. Playful gradients, friendly dev aesthetic. |
+| `raycast.md` | Productivity launcher. Sleek dark chrome, vibrant gradient accents. |
+| `superhuman.md` | Fast email client. Premium dark UI, keyboard-first, purple glow. |
+| `vercel.md` | Frontend deployment platform. Black and white precision, Geist font. |
+| `warp.md` | Modern terminal. Dark IDE-like interface, block-based command UI. |
+
+### Backend, Database & DevOps (8)
+
+| File | Aesthetic |
+|---|---|
+| `clickhouse.md` | Fast analytics database. Yellow-accented, technical documentation style. |
+| `composio.md` | Tool integration platform. Modern dark with colorful integration icons. |
+| `hashicorp.md` | Infrastructure automation. Enterprise-clean, black and white. |
+| `mongodb.md` | Document database. Green leaf branding, developer documentation focus. |
+| `posthog.md` | Product analytics. Playful hedgehog branding, developer-friendly dark UI. |
+| `sanity.md` | Headless CMS. Red accent, content-first editorial layout. |
+| `sentry.md` | Error monitoring. Dark dashboard, data-dense, pink-purple accent. |
+| `supabase.md` | Open-source Firebase alternative. Dark emerald theme, code-first. |
+
+### Productivity & SaaS (7)
+
+| File | Aesthetic |
+|---|---|
+| `cal.md` | Open-source scheduling. Clean neutral UI, developer-oriented simplicity. |
+| `intercom.md` | Customer messaging. Friendly blue palette, conversational UI patterns. |
+| `linear.app.md` | Project management for engineers. Ultra-minimal, precise, purple accent. |
+| `mintlify.md` | Documentation platform. Clean, green-accented, reading-optimized. |
+| `notion.md` | All-in-one workspace. Warm minimalism, serif headings, soft surfaces. |
+| `resend.md` | Email API for developers. Minimal dark theme, monospace accents. |
+| `zapier.md` | Automation platform. Warm orange, friendly illustration-driven. |
+
+### Design & Creative Tools (6)
+
+| File | Aesthetic |
+|---|---|
+| `airtable.md` | Spreadsheet-database hybrid. Colorful, friendly, structured data aesthetic. |
+| `clay.md` | Creative agency. Organic shapes, soft gradients, art-directed layout. |
+| `figma.md` | Collaborative design tool. Vibrant multi-color, playful yet professional. |
+| `framer.md` | Website builder. Bold black and blue, motion-first, design-forward. |
+| `miro.md` | Visual collaboration. Bright yellow accent, infinite canvas aesthetic. |
+| `webflow.md` | Visual web builder. Blue-accented, polished marketing site aesthetic. |
+
+### Fintech & Crypto (7)
+
+| File | Aesthetic |
+|---|---|
+| `binance.md` | Crypto exchange. Bold Binance Yellow on monochrome, trading-floor urgency. |
+| `coinbase.md` | Crypto exchange. Clean blue identity, trust-focused, institutional feel. |
+| `kraken.md` | Crypto trading platform. Purple-accented dark UI, data-dense dashboards. |
+| `mastercard.md` | Global payments network. Warm cream canvas, orbital pill shapes, editorial warmth. |
+| `revolut.md` | Digital banking. Sleek dark interface, gradient cards, fintech precision. |
+| `stripe.md` | Payment infrastructure. Signature purple gradients, weight-300 elegance. |
+| `wise.md` | International money transfer. Bright green accent, friendly and clear. |
+
+### E-commerce & Retail (5)
+
+| File | Aesthetic |
+|---|---|
+| `airbnb.md` | Travel marketplace. Warm coral accent, photography-driven, rounded UI. |
+| `meta.md` | Tech retail store. Photography-first, binary light/dark surfaces, Meta Blue CTAs. |
+| `nike.md` | Athletic retail. Monochrome UI, massive uppercase Futura, full-bleed photography. |
+| `shopify.md` | E-commerce platform. Dark-first cinematic, neon green accent, ultra-light display type. |
+| `starbucks.md` | Coffee retail flagship. Four-tier earth-green system, warm cream canvas, SoDoSans typography. |
+
+### Media & Consumer Tech (11)
+
+| File | Aesthetic |
+|---|---|
+| `apple.md` | Consumer electronics. Premium white space, SF Pro, cinematic imagery. |
+| `ibm.md` | Enterprise technology. Carbon design system, structured blue palette. |
+| `nvidia.md` | GPU computing. Green-black energy, technical power aesthetic. |
+| `pinterest.md` | Visual discovery platform. Red accent, masonry grid, image-first. |
+| `playstation.md` | Gaming console retail. Three-surface channel layout, cyan hover-scale interaction. |
+| `spacex.md` | Space technology. Stark black and white, full-bleed imagery, futuristic. |
+| `spotify.md` | Music streaming. Vibrant green on dark, bold type, album-art-driven. |
+| `theverge.md` | Tech editorial media. Acid-mint and ultraviolet accents, Manuka display type. |
+| `uber.md` | Mobility platform. Bold black and white, tight type, urban energy. |
+| `vodafone.md` | Global telecom brand. Monumental uppercase display, Vodafone Red chapter bands. |
+| `wired.md` | Tech magazine. Paper-white broadsheet density, custom serif, ink-blue links. |
+
+### Automotive (6)
+
+| File | Aesthetic |
+|---|---|
+| `bmw.md` | Luxury automotive. Dark premium surfaces, precise German engineering aesthetic. |
+| `bugatti.md` | Luxury hypercar. Cinema-black canvas, monochrome austerity, monumental display type. |
+| `ferrari.md` | Luxury automotive. Chiaroscuro black-white editorial, Ferrari Red with extreme sparseness. |
+| `lamborghini.md` | Luxury automotive. True black cathedral, gold accent, LamboType custom Neo-Grotesk. |
+| `renault.md` | French automotive. Vivid aurora gradients, NouvelR proprietary typeface, zero-radius buttons. |
+| `tesla.md` | Electric vehicles. Radical subtraction, cinematic full-viewport photography, Universal Sans. |
+
+### Mood-based shortcuts (when user describes feeling, not naming a brand)
+
+- **"Premium / luxurious / expensive"** → `apple.md`, `stripe.md`, `vercel.md`, `linear.app.md`
+- **"Editorial / paper-like / readable"** → `notion.md`, `wired.md`, `claude.md`
+- **"Brutal / Swiss / industrial"** → `nike.md`, `bugatti.md`, `vodafone.md`
+- **"Dark cinematic"** → `runwayml.md`, `elevenlabs.md`, `superhuman.md`, `shopify.md`
+- **"Terminal / developer-native"** → `vercel.md`, `warp.md`, `voltagent.md`, `ollama.md`
+- **"Warm / approachable / soft"** → `airbnb.md`, `notion.md`, `intercom.md`, `mastercard.md`
+- **"Data-dense / dashboard"** → `sentry.md`, `kraken.md`, `posthog.md`, `clickhouse.md`
+- **"Bold / sporty / monochrome punch"** → `nike.md`, `uber.md`, `tesla.md`, `binance.md`
+- **"Playful / colorful / friendly"** → `figma.md`, `airtable.md`, `zapier.md`, `lovable.md`