oh-my-opencode 4.9.2 → 4.11.0

package/packages/omo-codex/plugin/skills/frontend/references/perfection/README.md

@@ -0,0 +1,160 @@
+
+# Frontend Perfectionist
+
+You are a senior frontend engineer with one binding standard: **every page hits 100 in EVERY Lighthouse category, measured on a REAL browser, without sacrificing a single drop of UX quality.**
+
+## TENETS. NON-NEGOTIABLE.
+
+### 1. AUDIT THROUGH A REAL BROWSER. NEVER THROUGH THE CLI.
+
+The `lighthouse` CLI runs `chrome-headless-shell` with default settings. That is **NOT** what your users see, and the number it produces will lie to you. **REJECT** any report based on the CLI, even if the CI shows green.
+
+The correct path:
+
+1. Build the app in production mode (`next build && next start`, `vite build && vite preview`, `astro build && astro preview`, `bun run build && bun run start`). **NEVER** measure a dev server.
+2. Launch Playwright with `channel: "chrome"` (real Chrome stable, not the headless-shell binary).
+3. Run Lighthouse against the Playwright-controlled page via `playwright-lighthouse` OR via `chrome-launcher` + the `lighthouse` Node API, attaching to the Playwright CDP endpoint so cookies, auth state, and warmed caches mirror what a real returning user sees.
+4. Use the **mobile** preset (4x CPU throttle, Fast 3G) for the primary number, AND the **desktop** preset for the secondary number. Report both.
+
+If the `playwright` skill is not loaded in this session, load it now via the `skill` tool.
+
+### 2. 100 IN EVERY CATEGORY IS THE FLOOR.
+
+A 99 is a regression. A 95 is a fire. You do NOT report "performance 93, accessibility 100, SEO 100, best-practices 100" as a pass. You diagnose what cost the 7 points, fix the root cause, re-run, and only report when all four panels show 100. On mobile AND desktop.
+
+### 3. WIN THE SCORE IN THE ARCHITECTURE.
+
+Performance is decided at architecture and code-quality level. Bundle size, render path, hydration strategy, asset pipeline, image format and dimensions, font loading, third-party scripts, critical CSS, deferred JS, route-level code splitting. These are the LEVERS that move the score. Slapping `loading="lazy"` on a hero image is not optimization. It is panic.
+
+For EVERY failing audit, trace it back to a SPECIFIC line of code or a SPECIFIC build-config choice. Fix it at the source. No band-aids.
+
+### 4. NEVER WEAKEN UX TO BUY POINTS.
+
+If your fix removes a hover state, drops a CSS transition, replaces an animated mount with an abrupt one, swaps a smooth scroll-into-view for an instant jump, degrades a 60fps interaction to 30fps, or hides content you would normally render, **REJECT THE FIX**. The animation language, motion design, and tactile feel of the product are load-bearing.
+
+Find another way:
+
+- Split the bundle further (route-level, then component-level, then feature-flag-level).
+- Defer non-critical paint work to `requestIdleCallback`.
+- Move expensive work off the main thread via Web Workers (use Comlink for ergonomics).
+- Use the `View Transitions API` for cross-route transitions.
+- Use `content-visibility: auto` plus `contain-intrinsic-size` for offscreen sections.
+- Use `will-change` precisely, ONLY on the property actually animating, ONLY for the duration of the animation.
+- Preload the LCP image: `<link rel="preload" as="image" fetchpriority="high" imagesrcset="...">`.
+- HTTP/2 server-push or `<link rel="modulepreload">` for the critical chunk.
+- GPU-composited animations only (`transform`, `opacity`, `filter`). NEVER animate `width`, `height`, `top`, `left`, `margin`, `padding`.
+
+### 5. LOAD THE DESIGN RULESET IN LOCKSTEP.
+
+You **MUST** read the design ruleset (`../design/README.md`) alongside this one for any visual or layout work. That skill carries the brand-grade taste references (Apple, Stripe, Linear, Vercel, Claude, Notion, Airbnb, Figma, etc.) and the anti-AI-SaaS-slop posture.
+
+A page that scores 100 but looks like AI SaaS slop has failed. Speed serves design; design rides on speed. **Both win or neither does.**
+
+Use the design ruleset:
+
+- BEFORE writing JSX/CSS: pull a relevant brand reference to ground the visual direction.
+- DURING implementation: cross-check against the anti-slop guardrails.
+- BEFORE declaring done: verify the page passes the design taste bar, not just the Lighthouse bar.
+
+### 6. DESIGN SYSTEM COMPLIANCE IS NOT OPTIONAL.
+
+The design ruleset (`../design/README.md`) enforces a **Phase 0 Design System Gate** — every project must have a `DESIGN.md` before any UI work begins. This skill enforces the other side: **every audit must verify compliance.**
+
+During the audit loop, after Lighthouse scores pass, run a Design System Compliance check:
+
+- **Colors**: grep the codebase for raw hex/rgb values not declared in `DESIGN.md`. Each is a violation.
+- **Typography**: every font-size in CSS/Tailwind must map to the type scale in `DESIGN.md`. No arbitrary sizes.
+- **Spacing**: every margin/padding/gap value must be a multiple of the base unit (4px) and ideally use a declared token.
+- **Components**: any component used 2+ times must be documented in `DESIGN.md` Section 5. If it isn't, add it.
+- **Depth**: if `DESIGN.md` says "borders-only", there must be zero `box-shadow` declarations. If "tonal-shift", zero borders for surface separation.
+
+A page that scores Lighthouse 100 but uses 14 undeclared hex codes and 8 magic spacing values is **NOT DONE**. The design system is the architecture — Lighthouse measures the performance of that architecture.
+
+### 7. REACT-SPECIFIC PERF TOOLING IS PART OF THE AUDIT.
+
+If the project ships React, Lighthouse alone does NOT see render-layer issues by component. You MUST also run:
+
+- **`react-doctor`** (static): cheapest. `npx react-doctor@latest --json` before any browser audit. Treat perf-category findings as audit failures.
+- **`react-scan/lite`** (runtime, headless): injected via `page.addInitScript` in the Playwright run. Drain its `onEvent` stream and fail the audit if any commit is classified `unnecessary`.
+
+The full recipe — including the Playwright + `playwright-lighthouse` + `react-scan/lite` integration, the per-route render budget assertion, and the React-specific root-cause checklist that EXTENDS the one below — lives in **[react-perf-tooling.md](react-perf-tooling.md)**. Read it before any React audit.
+
+Lighthouse 100 with `react-scan` reporting 30+ unnecessary renders per route is **NOT DONE**. Both gates must clear: synthetic score AND render quality. The synthetic score lies under real load if the React layer is thrashing.
+
+For initial install of react-scan + react-doctor (and react-grab) in a fresh React project, the canonical install snippets live in `../design/react-dev-tooling-skill.md`. Use them if the project doesn't yet have the tools wired.
+
+## AUDIT WORKFLOW
+
+Quick audit via the cross-platform Python CLI (macOS, Linux, Windows):
+
+```bash
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --threshold 95
+uv run $SKILL_DIR/scripts/perfection/lighthouse-audit.py https://localhost:3000 --desktop-only
+```
+
+Or use the TypeScript approach directly in your test suite:
+
+```ts
+// scripts/audit.ts
+import { chromium } from "playwright";
+import { playAudit } from "playwright-lighthouse";
+
+const browser = await chromium.launch({ channel: "chrome" });
+const context = await browser.newContext();
+const page = await context.newPage();
+await page.goto("http://localhost:3000/<route>");
+
+await playAudit({
+  page,
+  port: 9222,
+  thresholds: { performance: 100, accessibility: 100, "best-practices": 100, seo: 100 },
+  reports: { formats: { html: true, json: true }, name: "lighthouse-<route>" },
+  config: { extends: "lighthouse:default", settings: { formFactor: "mobile" } },
+});
+
+await browser.close();
+```
+
+Run twice per route: once `formFactor: "mobile"`, once `formFactor: "desktop"`. Both must hit 100/100/100/100.
+
+**Diagnose from the JSON report, not the HTML.** Parse `audits[*].score < 1` programmatically to find the offenders. Do not eyeball the HTML report.
+
+**Run 3-5 times and take the median.** A single audit can be noisy. CI must enforce the threshold on every PR.
+
+## ROOT-CAUSE CHECKLIST (HIT THESE FIRST, ALMOST ALWAYS THE CULPRIT)
+
+- **Render-blocking JS/CSS in the critical path.** Defer, code-split by route, inline critical CSS only.
+- **Unsized media.** Every `<img>`, `<video>`, `<iframe>` MUST have explicit `width`/`height` or an aspect-ratio container. Unsized media causes CLS.
+- **Wrong image format or dimensions.** Serve AVIF first, WebP fallback, JPEG last. Generate ALL responsive sizes in the build. NEVER ship an image larger than the rendered box. Use `fetchpriority="high"` on the LCP image.
+- **Fonts.** `font-display: swap` minimum, `optional` for non-critical fonts, preload the one critical font, subset to only the characters actually used.
+- **Third-party scripts in `<head>` synchronously.** Defer, lazy-load on first interaction, OR proxy through your own origin to remove a third-party DNS + TLS handshake from the critical path.
+- **Hydration on routes that do not need it.** React Server Components, islands, `client:load`, ONLY where the interactivity is real. Static routes ship zero JS.
+- **Missing semantic HTML.** `<button>` for buttons, `<a href>` for links, `<nav>` / `<main>` / `<header>` / `<footer>` landmarks, label every form input, alt-text every meaningful image, unique `<title>` per route.
+- **Tab order, focus rings, contrast ratios, prefers-reduced-motion, ARIA correctness.** Accessibility 100 means a screen-reader user can drive the page end-to-end without help.
+- **Meta tags.** `<title>`, `<meta name="description">`, OpenGraph, Twitter cards, structured data (JSON-LD), `lang` on `<html>`, `viewport`, canonical URL.
+
+## ANTI-PATTERNS. REJECT ON SIGHT.
+
+- Reporting a CLI Lighthouse score. **REJECT.** Tenet 1.
+- Removing an animation to fix INP. **REJECT.** Switch to a CSS-only transform/opacity animation. Debounce listeners. Move heavy work off the main thread.
+- Replacing a hero image with a placeholder to "fix" LCP. **REJECT.** Properly sized AVIF + `fetchpriority="high"` + preconnect to the image CDN is the actual fix.
+- Disabling JS for a route to "score 100". **REJECT.** Score 100 ON the JS-enabled production build, on a real user device profile.
+- Setting `display: none` on offscreen content to dodge audits. **REJECT.** Use `content-visibility: auto` plus proper lazy mounting. Never lie about the page.
+- Declaring victory after a single audit run. **REJECT.** Run 3-5 times, take the median. CI must enforce the threshold.
+- Scoring 100 on `localhost` and shipping without re-measuring against the deployed URL. **REJECT.** The CDN, real DNS, and real TLS handshake matter.
+
+## RESPONSE FORMAT (what to return when the user asks for a frontend audit or build)
+
+1. **Scores before / after**, mobile AND desktop, all four categories.
+2. **Design system compliance**: orphan tokens found / fixed, components documented.
+3. **Each fix** in one line, traceable to the audit it cleared.
+4. **What you intentionally did NOT do**, and why. Especially every tempting "easy point" you rejected to preserve UX.
+5. **Browser-based Design QA result**: breakpoints tested, visual bugs found/fixed, states verified.
+6. **The next audit you would run** if you had another iteration.
+
+If the run did not hit 100 in every category, you are NOT done. State so explicitly. Continue iterating.
+
+## MANTRA
+
+> **100 on every Lighthouse category, on a real browser, with full features and full animations intact. Or it is not done.**

package/packages/omo-codex/plugin/skills/frontend/references/perfection/react-perf-tooling.md

@@ -0,0 +1,127 @@
+# React Perf Tooling for Lighthouse 100
+
+You are auditing or optimizing a React app for Lighthouse 100. Two tools belong in this workflow alongside Playwright + lighthouse — they catch the React-specific perf issues that Lighthouse counts but doesn't diagnose by component:
+
+| Tool | Surface | What it gives you |
+|---|---|---|
+| **react-scan** (`react-scan/lite`) | Runtime instrumentation, headless | Per-fiber `commit` events with `changeDescription` — "this component re-rendered because <prop / state / context / parent / hook> changed". Correlates with `long-animation-frame` to attribute LoAF to specific components. |
+| **react-doctor** | Static scan, CI-friendly | Deterministic findings across state/effects, perf (memoization, list keys, expensive children), architecture, security, a11y. One-shot `npx react-doctor@latest` produces a JSON report. From the Million.dev team. |
+
+Use both. They are complementary: `react-scan` tells you *what's slow right now*; `react-doctor` tells you *what's structurally wrong*. Both are dev-only and free.
+
+If the project does not yet have react-scan and react-doctor wired into its dev environment, read `../design/react-dev-tooling-skill.md` first and install them — they should be on by default for every React project this skill audits.
+
+## Lighthouse run + react-scan/lite
+
+`playwright-lighthouse` already drives a real Chrome. Inject `react-scan/lite` BEFORE React mounts via `page.addInitScript`. Then drain its `onEvent` stream during the run and assert on render budgets at the end.
+
+```ts
+// scripts/audit-with-react-scan.ts
+import { chromium } from "playwright";
+import { playAudit } from "playwright-lighthouse";
+
+const browser = await chromium.launch({ channel: "chrome" });
+const context = await browser.newContext();
+
+// Inject react-scan/lite BEFORE the app boots
+await context.addInitScript(() => {
+  // @ts-ignore — pulled from the project's node_modules or a self-hosted bundle
+  import("react-scan/lite").then(({ instrument }) => {
+    (window as any).__renderEvents = [];
+    instrument({
+      onEvent: (event: any) => {
+        if (event.kind === "commit") (window as any).__renderEvents.push(event);
+      },
+      recordChangeDescriptions: true,
+      includeFiberSource: true,
+      includeFiberIdentity: true,
+    });
+  });
+});
+
+const page = await context.newPage();
+await page.goto("http://localhost:3000/<route>");
+
+await playAudit({
+  page,
+  port: 9222,
+  thresholds: { performance: 100, accessibility: 100, "best-practices": 100, seo: 100 },
+  reports: { formats: { html: true, json: true }, name: "lighthouse-<route>" },
+  config: { extends: "lighthouse:default", settings: { formFactor: "mobile" } },
+});
+
+// Pull render events and assert on render quality
+const events = await page.evaluate(() => (window as any).__renderEvents);
+const unnecessary = events.filter((e: any) =>
+  e.tree?.some((node: any) => node.changeDescription?.kind === "unnecessary"),
+);
+
+if (unnecessary.length > 0) {
+  console.error(`FAIL: ${unnecessary.length} unnecessary renders detected during audit`);
+  for (const e of unnecessary.slice(0, 10)) console.error("  -", JSON.stringify(e, null, 2));
+  process.exit(1);
+}
+
+await browser.close();
+```
+
+This is the canonical integration. Run twice per route (mobile + desktop), same as the base Lighthouse workflow. Both must hit 100/100/100/100 AND zero unnecessary renders.
+
+## react-doctor — static perf gate
+
+Before the Playwright run, fail fast on structural issues. The scan is fast and doesn't need a browser, so put it earlier in the pipeline.
+
+```bash
+npx react-doctor@latest --json > .react-doctor-report.json
+```
+
+Parse `.react-doctor-report.json` for perf-category findings. Treat any perf finding as a blocker for the same reason you treat a Lighthouse score < 100 as a blocker — these are deterministic issues that *will* show up in Lighthouse eventually under throttling.
+
+Wire it into CI as a separate job (cheap, fast, no browser needed):
+
+```yaml
+- name: React Doctor static perf scan
+  uses: millionco/react-doctor@main
+```
+
+Or run inline with a fail filter:
+
+```yaml
+- name: React Doctor static perf scan
+  run: npx react-doctor@latest --json --fail-on perf
+```
+
+## When to load which during an audit
+
+Run them in this order, stop at the first failure:
+
+1. **`react-doctor`** — cheapest. Catches missing memoization, broken list keys, unstable callback refs, expensive children that re-render unnecessarily. Fix everything it reports BEFORE running Lighthouse — half the perf score wins live here.
+2. **`react-scan` interactive in dev** — load the page in real Chrome with `npx react-scan@latest init` already wired (see the dev-tooling reference). Walk the LCP route, the most-clicked CTA, and any animation-heavy view. The toolbar shows render counts; the overlay highlights unnecessary renders in gray. Fix until clean.
+3. **`react-scan/lite` in the Lighthouse run** — once interactive is clean, run the Playwright audit above. This catches anything that only shows under throttling or only on first paint.
+4. **Playwright + Lighthouse** — standard run from `README.md` audit workflow. Score 100 + zero unnecessary renders from step 3 = done.
+
+## React-specific perf root causes (extends `README.md` ROOT-CAUSE CHECKLIST)
+
+These are the failures `react-scan` and `react-doctor` surface that base Lighthouse won't directly name:
+
+- **Context value identity churn.** A provider value `useMemo` was forgotten; every consumer re-renders on every render of the provider's parent. → `useMemo` the value, or split contexts so high-churn fields don't sit next to stable ones.
+- **Inline object/array/callback props on memoized children.** `<Child config={{ a: 1 }} />` breaks `React.memo` every render. → Hoist, `useMemo`, or `useCallback`.
+- **List keys = array index.** Reordering shreds the reconciler. → Use a stable id from the data.
+- **Expensive components rendered unconditionally above the fold.** → `lazy()` + `Suspense`, or move below the LCP, or pre-render server-side.
+- **Effects that fire on every render.** Missing dependency arrays or unstable deps. → Stabilize deps, or split state, or extract to `useEvent`-style ref.
+- **Spreading the entire context value into props.** Couples every consumer to every field. → Destructure only the fields used.
+- **Hydration mismatches.** SSR markup doesn't equal client first-render. → react-doctor flags structurally; fix the source of the divergence (Date.now, locale, randomness, browser-only APIs).
+
+`react-doctor` finds these statically. `react-scan` confirms the symptom in the running app. Both must come clean before Lighthouse 100 is meaningful.
+
+## Anti-patterns specific to this workflow
+
+- **Forgetting `page.addInitScript` (using `page.evaluate` instead).** `evaluate` runs AFTER React mounts; you'll miss every initial-render event. Use `addInitScript`.
+- **`react-scan` non-lite during a Lighthouse run.** The full UI (toolbar, canvas overlay) adds overhead and skews the score. Use `react-scan/lite` ONLY for measurement; the full version is for interactive dev.
+- **Reporting Lighthouse 100 with `react-scan` showing 30+ unnecessary renders per route.** The score is meaningless if the React layer is thrashing — INP and CLS will degrade under real load even if the synthetic run passed. Both gates must clear.
+- **Treating `trackUnnecessaryRenders` as free.** It has measurable overhead; in a Lighthouse run it can drag the perf score by 2-3 points. Use it for interactive diagnosis, not for the audit run.
+- **Skipping react-doctor because "it's just a linter".** It's not. It detects React-specific defects (missing keys, broken memo, unstable refs, hydration mismatches) that ESLint plugins miss because they require fiber-level reasoning.
+
+## Mantra
+
+> **Lighthouse 100 + react-doctor clean + zero unnecessary renders from react-scan. All three or it is not done.**

package/packages/omo-codex/plugin/skills/frontend/references/ui-ux-db/README.md

@@ -0,0 +1,273 @@
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+Reference these guidelines when:
+- Designing new UI components or pages
+- Choosing color palettes and typography
+- Reviewing code for UX issues
+- Building landing pages or dashboards
+- Implementing accessibility requirements
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Domain |
+|----------|----------|--------|--------|
+| 1 | Accessibility | CRITICAL | `ux` |
+| 2 | Touch & Interaction | CRITICAL | `ux` |
+| 3 | Performance | HIGH | `ux` |
+| 4 | Layout & Responsive | HIGH | `ux` |
+| 5 | Typography & Color | MEDIUM | `typography`, `color` |
+| 6 | Animation | MEDIUM | `ux` |
+| 7 | Style Selection | MEDIUM | `style`, `product` |
+| 8 | Charts & Data | LOW | `chart` |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text
+- `focus-states` - Visible focus rings on interactive elements
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons
+- `keyboard-nav` - Tab order matches visual order
+- `form-labels` - Use label with for attribute
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Minimum 44x44px touch targets
+- `hover-vs-tap` - Use click/tap for primary interactions
+- `loading-buttons` - Disable button during async operations
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP, srcset, lazy loading
+- `reduced-motion` - Check prefers-reduced-motion
+- `content-jumping` - Reserve space for async content
+
+### 4. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1
+- `readable-font-size` - Minimum 16px body text on mobile
+- `horizontal-scroll` - Ensure content fits viewport width
+- `z-index-management` - Define z-index scale (10, 20, 30, 50)
+
+### 5. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+
+### 6. Animation (MEDIUM)
+
+- `duration-timing` - Use 150-300ms for micro-interactions
+- `transform-performance` - Use transform/opacity, not width/height
+- `loading-states` - Skeleton screens or spinners
+
+### 7. Style Selection (MEDIUM)
+
+- `style-match` - Match style to product type
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons, not emojis
+
+### 8. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type
+- `color-guidance` - Use accessible color palettes
+- `data-table` - Provide table alternative for accessibility
+
+## How to Use
+
+Search specific domains using the CLI tool below. The search script and data files are located in this skill directory:
+- Search script: @scripts/search.py
+- Data files: @data/
+
+
+## How to Use This Skill
+
+When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc.
+- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc.
+- **Industry**: healthcare, fintech, gaming, education, etc.
+- **Stack**: React, Vue, Next.js, or default to `html-tailwind`
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 @scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches 5 domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 @scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 @scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 @scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 @scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+### Step 4: Stack Guidelines (Default: html-tailwind)
+
+Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**.
+
+```bash
+python3 @scripts/search.py "<keyword>" --stack html-tailwind
+```
+
+Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`
+
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) |
+| `react` | State, hooks, performance, patterns |
+| `nextjs` | SSR, routing, images, API routes |
+| `vue` | Composition API, Pinia, Vue Router |
+| `svelte` | Runes, stores, SvelteKit |
+| `swiftui` | Views, State, Navigation, Animation |
+| `react-native` | Components, Navigation, Lists |
+| `flutter` | Widgets, State, Layout, Theming |
+| `shadcn` | shadcn/ui components, theming, forms, patterns |
+| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition |
+
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+
+### Icons & Visual Elements
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis as UI icons |
+| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
+| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
+
+### Interaction & Cursor
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements |
+| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive |
+| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) |
+| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text |
+| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter |
+| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` |
+| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements |
+| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths |
+
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] Brand logos are correct (verified from Simple Icons)
+- [ ] Hover states don't cause layout shift
+- [ ] Use theme colors directly (bg-primary) not var() wrapper
+
+### Interaction
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback
+- [ ] Transitions are smooth (150-300ms)
+- [ ] Focus states visible for keyboard navigation
+
+### Light/Dark Mode
+- [ ] Light mode text has sufficient contrast (4.5:1 minimum)
+- [ ] Glass/transparent elements visible in light mode
+- [ ] Borders visible in both modes
+- [ ] Test both modes before delivery
+
+### Layout
+- [ ] Floating elements have proper spacing from edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Form inputs have labels
+- [ ] Color is not the only indicator
+- [ ] `prefers-reduced-motion` respected

package/packages/omo-codex/plugin/skills/frontend/references/ui-ux-db/data/charts.csv

@@ -0,0 +1,26 @@
+No,Data Type,Keywords,Best Chart Type,Secondary Options,Color Guidance,Performance Impact,Accessibility Notes,Library Recommendation,Interactive Level
+1,Trend Over Time,"trend, time-series, line, growth, timeline, progress",Line Chart,"Area Chart, Smooth Area",Primary: #0080FF. Multiple series: use distinct colors. Fill: 20% opacity,⚡ Excellent (optimized),✓ Clear line patterns for colorblind users. Add pattern overlays.,"Chart.js, Recharts, ApexCharts",Hover + Zoom
+2,Compare Categories,"compare, categories, bar, comparison, ranking",Bar Chart (Horizontal or Vertical),"Column Chart, Grouped Bar",Each bar: distinct color. Category: grouped same color. Sorted: descending order,⚡ Excellent,✓ Easy to compare. Add value labels on bars for clarity.,"Chart.js, Recharts, D3.js",Hover + Sort
+3,Part-to-Whole,"part-to-whole, pie, donut, percentage, proportion, share",Pie Chart or Donut,"Stacked Bar, Treemap",Colors: 5-6 max. Contrasting palette. Large slices first. Use labels.,⚡ Good (limit 6 slices),⚠ Hard for accessibility. Better: Stacked bar with legend. Avoid pie if >5 items.,"Chart.js, Recharts, D3.js",Hover + Drill
+4,Correlation/Distribution,"correlation, distribution, scatter, relationship, pattern",Scatter Plot or Bubble Chart,"Heat Map, Matrix",Color axis: gradient (blue-red). Size: relative. Opacity: 0.6-0.8 to show density,⚠ Moderate (many points),⚠ Provide data table alternative. Use pattern + color distinction.,"D3.js, Plotly, Recharts",Hover + Brush
+5,Heatmap/Intensity,"heatmap, heat-map, intensity, density, matrix",Heat Map or Choropleth,"Grid Heat Map, Bubble Heat",Gradient: Cool (blue) to Hot (red). Scale: clear legend. Divergent for ±data,⚡ Excellent (color CSS),⚠ Colorblind: Use pattern overlay. Provide numerical legend.,"D3.js, Plotly, ApexCharts",Hover + Zoom
+6,Geographic Data,"geographic, map, location, region, geo, spatial","Choropleth Map, Bubble Map",Geographic Heat Map,Regional: single color gradient or categorized colors. Legend: clear scale,⚠ Moderate (rendering),⚠ Include text labels for regions. Provide data table alternative.,"D3.js, Mapbox, Leaflet",Pan + Zoom + Drill
+7,Funnel/Flow,funnel/flow,"Funnel Chart, Sankey",Waterfall (for flows),Stages: gradient (starting color → ending color). Show conversion %,⚡ Good,✓ Clear stage labels + percentages. Good for accessibility if labeled.,"D3.js, Recharts, Custom SVG",Hover + Drill
+8,Performance vs Target,performance-vs-target,Gauge Chart or Bullet Chart,"Dial, Thermometer",Performance: Red→Yellow→Green gradient. Target: marker line. Threshold colors,⚡ Good,✓ Add numerical value + percentage label beside gauge.,"D3.js, ApexCharts, Custom SVG",Hover
+9,Time-Series Forecast,time-series-forecast,Line with Confidence Band,Ribbon Chart,Actual: solid line #0080FF. Forecast: dashed #FF9500. Band: light shading,⚡ Good,✓ Clearly distinguish actual vs forecast. Add legend.,"Chart.js, ApexCharts, Plotly",Hover + Toggle
+10,Anomaly Detection,anomaly-detection,Line Chart with Highlights,Scatter with Alert,Normal: blue #0080FF. Anomaly: red #FF0000 circle/square marker + alert,⚡ Good,✓ Circle/marker for anomalies. Add text alert annotation.,"D3.js, Plotly, ApexCharts",Hover + Alert
+11,Hierarchical/Nested Data,hierarchical/nested-data,Treemap,"Sunburst, Nested Donut, Icicle",Parent: distinct hues. Children: lighter shades. White borders 2-3px.,⚠ Moderate,⚠ Poor - provide table alternative. Label large areas.,"D3.js, Recharts, ApexCharts",Hover + Drilldown
+12,Flow/Process Data,flow/process-data,Sankey Diagram,"Alluvial, Chord Diagram",Gradient from source to target. Opacity 0.4-0.6 for flows.,⚠ Moderate,⚠ Poor - provide flow table alternative.,"D3.js (d3-sankey), Plotly",Hover + Drilldown
+13,Cumulative Changes,cumulative-changes,Waterfall Chart,"Stacked Bar, Cascade",Increases: #4CAF50. Decreases: #F44336. Start: #2196F3. End: #0D47A1.,⚡ Good,✓ Good - clear directional colors with labels.,"ApexCharts, Highcharts, Plotly",Hover
+14,Multi-Variable Comparison,multi-variable-comparison,Radar/Spider Chart,"Parallel Coordinates, Grouped Bar",Single: #0080FF 20% fill. Multiple: distinct colors per dataset.,⚡ Good,⚠ Moderate - limit 5-8 axes. Add data table.,"Chart.js, Recharts, ApexCharts",Hover + Toggle
+15,Stock/Trading OHLC,stock/trading-ohlc,Candlestick Chart,"OHLC Bar, Heikin-Ashi",Bullish: #26A69A. Bearish: #EF5350. Volume: 40% opacity below.,⚡ Good,⚠ Moderate - provide OHLC data table.,"Lightweight Charts (TradingView), ApexCharts",Real-time + Hover + Zoom
+16,Relationship/Connection Data,relationship/connection-data,Network Graph,"Hierarchical Tree, Adjacency Matrix",Node types: categorical colors. Edges: #90A4AE 60% opacity.,❌ Poor (500+ nodes struggles),❌ Very Poor - provide adjacency list alternative.,"D3.js (d3-force), Vis.js, Cytoscape.js",Drilldown + Hover + Drag
+17,Distribution/Statistical,distribution/statistical,Box Plot,"Violin Plot, Beeswarm",Box: #BBDEFB. Border: #1976D2. Median: #D32F2F. Outliers: #F44336.,⚡ Excellent,"✓ Good - include stats table (min, Q1, median, Q3, max).","Plotly, D3.js, Chart.js (plugin)",Hover
+18,Performance vs Target (Compact),performance-vs-target-(compact),Bullet Chart,"Gauge, Progress Bar","Ranges: #FFCDD2, #FFF9C4, #C8E6C9. Performance: #1976D2. Target: black 3px.",⚡ Excellent,✓ Excellent - compact with clear values.,"D3.js, Plotly, Custom SVG",Hover
+19,Proportional/Percentage,proportional/percentage,Waffle Chart,"Pictogram, Stacked Bar 100%",10x10 grid. 3-5 categories max. 2-3px spacing between squares.,⚡ Good,✓ Good - better than pie for accessibility.,"D3.js, React-Waffle, Custom CSS Grid",Hover
+20,Hierarchical Proportional,hierarchical-proportional,Sunburst Chart,"Treemap, Icicle, Circle Packing",Center to outer: darker to lighter. 15-20% lighter per level.,⚠ Moderate,⚠ Poor - provide hierarchy table alternative.,"D3.js (d3-hierarchy), Recharts, ApexCharts",Drilldown + Hover
+21,Root Cause Analysis,"root cause, decomposition, tree, hierarchy, drill-down, ai-split",Decomposition Tree,"Decision Tree, Flow Chart",Nodes: #2563EB (Primary) vs #EF4444 (Negative impact). Connectors: Neutral grey.,⚠ Moderate (calculation heavy),✓ clear hierarchy. Allow keyboard navigation for nodes.,"Power BI (native), React-Flow, Custom D3.js",Drill + Expand
+22,3D Spatial Data,"3d, spatial, immersive, terrain, molecular, volumetric",3D Scatter/Surface Plot,"Volumetric Rendering, Point Cloud",Depth cues: lighting/shading. Z-axis: color gradient (cool to warm).,❌ Heavy (WebGL required),❌ Poor - requires alternative 2D view or data table.,"Three.js, Deck.gl, Plotly 3D",Rotate + Zoom + VR
+23,Real-Time Streaming,"streaming, real-time, ticker, live, velocity, pulse",Streaming Area Chart,"Ticker Tape, Moving Gauge",Current: Bright Pulse (#00FF00). History: Fading opacity. Grid: Dark.,⚡ Optimized (canvas/webgl),⚠ Flashing elements - provide pause button. High contrast.,Smoothed D3.js, CanvasJS
+24,Sentiment/Emotion,"sentiment, emotion, nlp, opinion, feeling",Word Cloud with Sentiment,"Sentiment Arc, Radar Chart",Positive: #22C55E. Negative: #EF4444. Neutral: #94A3B8. Size = Frequency.,⚡ Good,⚠ Word clouds poor for screen readers. Use list view.,"D3-cloud, Highcharts, Nivo",Hover + Filter
+25,Process Mining,"process, mining, variants, path, bottleneck, log",Process Map / Graph,"Directed Acyclic Graph (DAG), Petri Net",Happy path: #10B981 (Thick). Deviations: #F59E0B (Thin). Bottlenecks: #EF4444.,⚠ Moderate to Heavy,⚠ Complex graphs hard to navigate. Provide path summary.,"React-Flow, Cytoscape.js, Recharts",Drag + Node-Click