diff --git a/.agents/skills/cmk-codebase-docs/SKILL.md b/.agents/skills/cmk-codebase-docs/SKILL.md deleted file mode 100644 index be0920e..0000000 --- a/.agents/skills/cmk-codebase-docs/SKILL.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -name: cmk:codebase-docs -description: Generate or update hierarchical, AI-navigable documentation for a codebase under `docs/ai/`. Use whenever the user asks to "document the codebase for AI", "bootstrap AI docs", "generate codebase map", "set up AI navigation docs", "update AI docs", "refresh docs after change", or mentions building progressive-disclosure docs so an AI can find the right source files quickly. Produces a tree of concise docs that *point to* code rather than duplicate it. Use even when the user only says "document this repo" without specifying the structure. -version: 0.1.0 ---- - -# Codebase Docs for AI Navigation - -Build a tree of short documentation files under `docs/ai/` whose only job is to help an AI (or a human skimming quickly) locate the right source file for a topic. Each doc describes **what a thing is and where it lives**, not how the code works line-by-line. - -The tree mirrors how a newcomer would ask questions: start broad ("what is this repo?"), then drill down ("how does the TUI input loop work?"). At each level, the reader sees a short menu of sub-topics, each a one-line hook, and only descends into the ones that matter. - -## When to use - -Two explicit entry points — never run on autopilot: - -- **Bootstrap** — user says something like "set up AI docs", "document the codebase for AI", or it's a fresh repo with nothing under `docs/ai/`. Build the whole tree from the top. -- **Update** — user says "update the AI docs for X", "I added feature Y, refresh the docs", or similar. Find the affected nodes and edit in place; don't rewrite everything. - -If the mode is ambiguous, ask. - -## Output location and shape - -``` -docs/ai/ -├── README.md # root: whole-repo overview + link menu -├── / -│ ├── README.md # area overview + link menu to topics/sub-areas -│ ├── .md # a leaf doc for a bounded concept -│ └── / -│ ├── README.md -│ └── .md -``` - -- Folders with their own `README.md` act as branch nodes; leaves are plain `.md` files named after the topic (`session-loop.md`, not `00-session-loop.md` — no numeric prefixes). -- A branch's `README.md` lists children as a flat menu of one-liners with relative links. It does **not** re-explain what children cover. -- Keep folder names lowercase-kebab, matching the vocabulary the code already uses. Whatever the codebase calls a unit — package, module, service, app, crate, workspace — mirror that name. If the source folder is `billing-service/`, the doc folder is `billing-service/`, not `billing/` or `payments/`. - -## What goes in one doc - -Every doc answers three questions, in order, and then stops: - -1. **What is this?** — one or two sentences, plain language. -2. **Why does it exist / what problem does it solve?** — only if non-obvious. Skip for things a reader can infer from the name. -3. **Where is it?** — file paths with a symbol hint (function, struct, class, or a grep-able phrase) so AI can jump directly. Use markdown bullets, not prose. - -For a branch doc (`README.md`), replace (3) with a link menu to children. - -If implementation approach matters (an unusual pattern, a deliberate trade-off, an invariant that isn't obvious from the code), add a short "Approach" section — a paragraph or two — and still point to the code for the actual details. - -### Code reference format - -Point to files with enough of a hint to let AI skip straight to the right lines. The pattern is `path → symbol-or-grep-hint`: - -``` -- One-line description of what this thing does. - → `` — `` -``` - -Use a named symbol when one exists — function, class, struct, type, const, route, config key, whatever the language offers. Fall back to a short grep-able string from the code only if no named symbol covers it (e.g., a regex, a magic number, a CLI flag). Don't invent names — if you can't quickly find a hook, open the file and grab the real one. - -**Always write paths relative to the repo root**, not bare filenames. `apps/api/src/server.ts`, not just `server.ts`. A doc about a sub-folder still writes the full path from the repo root when it references a file, because the reader (an AI or a human `find`-ing) starts at the repo root, not inside the doc's folder. Bare filenames force a guess-the-path step that the skill exists to eliminate. The only exception: when every path in a tight list is in the same directory and you've just named that directory one line above, shortening is fine — but err toward being explicit. - -## Principles - -**Progressive disclosure.** A doc should be readable in ten seconds and tell the reader where to go for more. If you catch yourself explaining a sub-concept in depth, that sub-concept probably deserves its own doc — link to it instead. - -**Don't duplicate the code.** No copy-pasted function bodies, no snippets longer than a couple of lines. If a reader needs the actual logic, they open the file. The doc's value is knowing *which* file. - -**Don't document the obvious.** Skip things whose purpose is clear from the name or from reading the first ten lines of the file. `src/main.rs: entry point` is noise. A non-obvious invariant ("this must run before `init_db` or migrations panic") is signal. - -**Coherence over splitting.** If a topic is naturally one story, keep it in one doc even if it runs a bit long. Only split when there's a genuinely bounded sub-concept *and* the parent is getting unwieldy — see the split heuristic below. - -**Match the code's vocabulary.** Use the same names the code uses. If the source folder is `rcp/` (or the package is `@org/rcp`, or the module is `rcp`), the doc folder is `rcp/` — not a more "descriptive" alias like `remote-control-protocol/`. The doc's job is to be findable from the code's own terms. - -## Split heuristic - -Split a topic into its own sub-doc when **both** are true: - -1. **Bounded** — the sub-topic has a clear boundary a reader could land on directly without needing the parent's context. -2. **Substantial** — it would take more than a few bullets or a short paragraph to cover, *or* the parent doc is pushing past ~100–150 lines and getting hard to skim. - -If only (1) holds and the sub-topic is a two-line bullet, leave it inline. If only (2) holds (the parent is long but the content is one continuous narrative), don't chop it artificially — rewrite for brevity first. - -Rule of thumb: a good branch doc is ~30–80 lines. A good leaf doc is ~20–120 lines. If a leaf is heading past 200, ask whether it's really one topic. - -## What NOT to document - -- Entry points whose role is obvious from the filename (`main.*`, `index.*`, `app.*`, `cmd/*/main.go`, etc.). -- Boilerplate: standard package manifests (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) and typical framework scaffolding. -- Anything already well-covered by a top-level `README.md` — link to it instead of restating. -- Generated code, vendored dependencies, lockfiles, migration files. -- Features that don't exist yet. Don't speculate. - -## Bootstrap workflow - -1. **Survey the repo.** Read the root `README.md`, any `CLAUDE.md` / `AGENTS.md`, the top-level directory layout, and whatever package/workspace manifest the stack uses (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) for declared workspace members or sub-packages. Identify the 3–8 major areas — apps, services, packages, modules, significant subsystems. Note anything the existing README already explains well — don't duplicate it. - -2. **Draft `docs/ai/README.md`.** One paragraph: what this repo is, what it does, who it's for. Then a link menu to the major areas, each a single sentence. Nothing else. - -3. **For each area, decide branch vs. leaf.** If the area has ≥2 substantial sub-topics, make it a folder with its own `README.md`. If it's one coherent thing, make it a single `.md` at the parent level. - -4. **Drill down recursively.** For each branch, identify its sub-topics by skimming the code (directory structure, module boundaries, key types/functions). Apply the split heuristic. Stop recursing when a sub-topic is either (a) obvious from its name + file path, or (b) small enough to fit as a bullet in its parent. - -5. **Write leaf docs.** For each, read enough of the actual code to write a truthful what/why/where. Don't paraphrase from guesswork — open the file. Grab the real symbol names. - -6. **Verify links.** All relative links resolve; all file paths exist; all symbol hints are real (grep for them). Broken references are worse than no reference. - -7. **Sanity-check length.** Every doc under the length guidance above. Any doc that runs long, either split or trim. - -## Update workflow - -1. **Locate affected nodes.** Given the change (new feature, renamed module, deleted subsystem), find every doc that mentions it. `grep -r` on the old name is usually enough. - -2. **Edit in place.** Preserve the existing structure; don't rewrite docs that still describe reality. Update file-path hints, symbol names, and one-line summaries as needed. - -3. **Add new nodes if genuinely new.** A new area gets a new folder + `README.md`; a new topic inside an existing area gets a new leaf and a line in the parent's menu. - -4. **Remove stale nodes.** If a subsystem is deleted, delete its doc and remove it from the parent's menu. Don't leave tombstones. - -5. **Re-verify links and symbols** for every edited file. - -## Working example (sketch) - -The shape is the same regardless of stack — the folder names just mirror whatever the codebase calls its parts. A typical tree for a multi-area repo: - -``` -docs/ai/ -├── README.md # one paragraph: what the repo is + a menu of areas -├── / -│ ├── README.md # menu of sub-topics in this area -│ ├── .md # leaf: what / (why) / where -│ ├── .md -│ └── / -│ ├── README.md -│ └── .md -├── / -│ ├── README.md -│ ├── .md -│ └── .md -└── / - └── README.md # small enough to stay single-doc -``` - -Concrete shape examples for different stacks: - -- **TS monorepo (`apps/`, `packages/`)** — top-level menu mirrors workspace members: `docs/ai/apps//`, `docs/ai/packages//`. -- **Rust workspace (`crates/`)** — top-level menu mirrors crate names: `docs/ai//`. -- **Python project (`src//`)** — menu mirrors top-level modules: `docs/ai//`. -- **Go services (`cmd/`, `internal/`, `pkg/`)** — menu mirrors services/packages: `docs/ai//`, `docs/ai/internal//`. -- **Single-app repo with no clear sub-packages** — group by domain concept (e.g. `auth/`, `billing/`, `ingest/`) and let the leaves point at files anywhere in `src/`. - -A leaf doc — same structure regardless of language — might read in full: - -```markdown -# Session loop - -## What -The main driver of an interactive session. Each iteration reads one user -input, dispatches to the worker, streams output back, and returns to idle. -Keeps the input handler responsive across long-running calls. - -## Approach -The loop is persistent rather than per-turn: a single task owns the input -channel and the output renderer for the whole session. Earlier versions -re-created the task per turn, which dropped events during transitions. -See commit 88af577 for the fix. - -## Where -- Entry: `` — `` -- Input source: `` — `` -- Output renderer: `` — `` -``` - -That's the whole doc — ~15 lines, three clear hooks into the code, no copied source. Replace the placeholders with real paths and real symbol names from whatever language the project uses. - -## Common failure modes - -- **Paraphrased code.** If the doc is explaining control flow line-by-line, delete that and just point to the function. -- **Essay-style prose.** Bullets and short paragraphs beat flowing prose for skim-reading. -- **Phantom references.** Never invent a function or file name. If you're unsure, open the file and check. -- **Over-splitting.** Eight three-line leaves are harder to navigate than one thirty-line doc. Err toward keeping related things together. -- **Under-splitting.** A single 500-line `README.md` with everything is exactly what this skill is trying to replace. -- **Documenting aspirations.** Only describe what's in the code now. - -## Final check before finishing - -- [ ] Root `docs/ai/README.md` exists and links to every top-level area. -- [ ] Every branch `README.md` has a link menu, not a wall of text. -- [ ] Every leaf has what / (why, if non-obvious) / where. -- [ ] Every `→` reference points to a real file and a real symbol (spot-check a few with grep). -- [ ] No doc is over the length guidance without a reason. -- [ ] No duplicated content between parent and child. diff --git a/.agents/skills/cmk-codebase-docs/eval.json b/.agents/skills/cmk-codebase-docs/eval.json deleted file mode 100644 index 4ddbb03..0000000 --- a/.agents/skills/cmk-codebase-docs/eval.json +++ /dev/null @@ -1,34 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "bootstrap-ai-devkit", - "prompt": "Set up AI navigation docs for this repository. Read skills/codebase-docs/SKILL.md and follow its bootstrap workflow. Output the full tree under docs/ai/.", - "assertions": [ - "docs/ai/README.md exists and is one paragraph + a link menu (not a wall of text)", - "Top-level menu links every major area in the repo (skills/, docs/, .claude-plugin/, .opencode/ if relevant)", - "Each branch's README.md is a link menu of one-liners, not a re-explanation of children", - "Folder names mirror the repo's own vocabulary (e.g., 'skills' not 'plugins-and-skills')", - "Every leaf doc follows the what / (why) / where structure", - "Every file path referenced in docs is relative to the repo root, not bare filenames", - "Every referenced file path actually exists in the repo (no phantom paths)", - "Symbol hints (when present) are real grep-able strings, not invented names", - "No leaf doc duplicates code blocks longer than a couple of lines", - "No leaf doc exceeds ~200 lines", - "No tombstone references to the deleted codebase-summary skill", - "docs/ai/skills/README.md (or equivalent) lists codebase-docs as one of the skills" - ] - }, - { - "eval_id": 2, - "eval_name": "update-add-new-skill", - "prompt": "Assume docs/ai/ already exists with a tree describing this repo. I just added a new skill called 'cmk:foo' at skills/foo/SKILL.md. Read skills/codebase-docs/SKILL.md and follow its update workflow to refresh docs/ai/ for the new skill. Do not rewrite docs that still describe reality.", - "assertions": [ - "Existing unrelated docs are not rewritten", - "skills/foo/SKILL.md is added as a new leaf or menu entry under docs/ai/skills/", - "Parent README's menu is updated to include the new skill in alphabetical or logical order", - "Update is in-place editing — no full bootstrap rerun", - "Symbol hints for the new skill point at real content in skills/foo/SKILL.md", - "No new doc speculates about features that don't exist yet" - ] - } -] diff --git a/.agents/skills/cmk-worktree-dev-env/SKILL.md b/.agents/skills/cmk-worktree-dev-env/SKILL.md deleted file mode 100644 index 6a85301..0000000 --- a/.agents/skills/cmk-worktree-dev-env/SKILL.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -name: cmk:worktree-dev-env -description: This skill should be used when the user asks to "set up local dev", "worktree dev environment", "port conflicts between worktrees", "headless dev mode", "mprocs config", "process-compose setup", or needs to create or iterate worktree-isolated local development environments with deterministic port isolation, coherence validation, interactive and headless service runners, and env file management. -version: 0.1.0 ---- - -# Worktree Dev Environment Setup - -Set up (or improve) a worktree-isolated local development environment. The goal is a system where multiple git worktrees of the same repo can run full local dev stacks simultaneously on the same machine — without port conflicts, stale configs, or cross-worktree contamination. - -This pattern is valuable for three audiences: -- **Human developers** who want to work on multiple branches with live-reloading services -- **AI agents** (Claude Code, OpenCode, Cursor, etc.) that need to spin up, test against, and tear down local dev in headless mode -- **CI pipelines** that run integration tests against real services - -## The Pattern (Stack-Agnostic) - -The system has eight components. Each is a shell script or config file. Adapt implementation to the project's actual tech stack, but preserve the architectural boundaries — they exist because each component has a single responsibility and can fail independently. - -### 1. Port Isolation (`scripts/worktree-env.sh`) - -**Purpose:** Derive deterministic, unique port numbers from the repo's absolute path so that two worktrees on the same machine never collide. - -**How it works:** -- Compute a numeric offset from a hash of the repo root path: `offset = SHA256(repo_root) % 200` -- Apply that offset to every port the project uses: `SERVICE_PORT = BASE_PORT + offset` -- Export all computed ports as environment variables -- Also derive a unique compose project name (e.g., `COMPOSE_PROJECT_NAME=myapp-`) so Docker containers don't collide - -**Why SHA256 mod 200:** SHA256 is deterministic (same path = same ports every time, no state file needed) and the mod 200 range keeps ports in a safe user-space band while making collisions between different paths extremely unlikely. - -**Key rules:** -- This script is **sourced**, never executed directly — it exports vars into the caller's environment -- It must be idempotent (sourcing it twice produces the same result) -- Provide an escape hatch env var (e.g., `MYAPP_WORKTREE_ISOLATION_DISABLED=1`) for cases where someone wants to override - -**Edge case — file-based databases (SQLite, DuckDB):** These don't use ports. Instead, isolate them via path — each worktree gets its own DB file under `.local/` (e.g., `.local/dev.db`). The coherence guard should validate the DB path prefix matches the current `REPO_ROOT` to prevent cross-worktree contamination. - -**Template logic:** -```bash -#!/usr/bin/env bash -# worktree-env.sh — source this, don't execute it -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -OFFSET=$(echo -n "$REPO_ROOT" | shasum -a 256 | cut -c1-4) -OFFSET=$((16#$OFFSET % 200)) - -# Adapt these to your project's services: -export MYAPP_DB_PORT=$((55432 + OFFSET)) -export MYAPP_API_PORT=$((8080 + OFFSET)) -export MYAPP_FRONTEND_PORT=$((3000 + OFFSET)) -export COMPOSE_PROJECT_NAME="myapp-$(basename "$REPO_ROOT" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g')" -``` - -### 2. Init Script (`scripts/init-worktree-dev.sh`) - -**Purpose:** One-command bootstrap that prepares a worktree for local development. This is the **mandatory entry point** — nothing else should run before it. - -**What it does (in order):** -1. Source `worktree-env.sh` to compute ports -2. Create `.local/` directory with all needed config and secret files (if they don't exist) -3. Generate default configs with safe dev values (never production credentials) -4. Normalize env files — replace placeholder values, rewrite ports/DSNs to match computed values -5. Validate coherence (call the coherence script — hard stop on failure) -6. Sync env vars to service-specific locations (call the sync script) -7. Print a summary showing all service endpoints and their ports - -**Key rules:** -- Use `set -euo pipefail` — fail fast on any error -- Use atomic writes (write to temp file, then `mv`) for config files to avoid partial writes -- Never overwrite files that already have real values — only fill in defaults/placeholders -- When rewriting DSNs or URLs, only touch localhost entries (skip remote/production DSNs) - -### 3. Coherence Guard (`scripts/ensure-worktree-coherence.sh`) - -**Purpose:** Hard-fail safety check that validates all config files, env vars, and ports are internally consistent. If this fails, **nothing starts** — the developer must fix the mismatch first. - -**What it checks:** -- All referenced config files exist and are within the current worktree (reject absolute paths pointing elsewhere) -- All database connection strings use the correct computed port (parse the DSN, don't just check the raw number) -- All service URLs reference the correct computed ports -- Compose project name is consistent -- Any inter-service references (e.g., service A's URL for reaching service B) match the computed values -- For file-based databases, the path prefix matches `REPO_ROOT` - -**Why this exists:** Without this check, it's easy to accidentally run with a stale `.env` file from before a port change, or to source config from a sibling worktree. These bugs are silent and maddening to debug — authentication failures, connection refused, or worse, writes to the wrong database. The coherence guard makes these bugs loud and immediate. - -**Key rules:** -- Support a `--quiet` flag that suppresses success output (for use in mprocs/headless wrappers) -- Exit 1 with a descriptive error on any mismatch — say exactly what's wrong and what the expected value should be -- Check every DSN, every URL, every port reference — be thorough - -### 4. Env Sync (`scripts/sync-service-envs.sh`) - -**Purpose:** Propagate worktree-computed values to the specific env files that each service reads. Many frameworks (Next.js, Vite, Rails, etc.) expect a `.env.local` in their own directory. - -**What it does:** -- Read the canonical env files from `.local/` -- Generate service-specific env files (e.g., `frontend/.env.local`, `backend/.env.local`) -- Only write the vars each service needs — don't dump everything everywhere - -**Why a separate script:** Services have different env file conventions and variable names. The frontend might need `VITE_API_URL` while the backend needs `DATABASE_URL`. This script is the translation layer. Keeping it separate from init means services can re-sync without re-running the full init. - -### 5. Interactive Mode (`mprocs.yaml` or `process-compose.yaml`) - -**Purpose:** Run all services in a single terminal with live-reload for human developers. - -**Use [mprocs](https://github.com/pvolok/mprocs) or [process-compose](https://github.com/F1bonacc1/process-compose)** — both are lightweight process multiplexers. Choose based on the team's preference. - -**Each process entry should:** -1. Source the worktree env vars -2. Run the coherence check (`--quiet` flag) -3. Start the service with file-watching/live-reload - -**Common process types:** -- **infra**: Database, message queue, cache (via docker compose). Include signal handlers (EXIT, INT, TERM) to auto-clean containers on exit. -- **backend**: Application server with watch mode (e.g., `cargo watch`, `bun --watch`, `nodemon`, `air` for Go) -- **frontend**: Dev server (Vite, Next.js dev, etc.) -- **bootstrap**: One-shot processes that seed initial data (admin accounts, dev fixtures). These should be idempotent and retry-capable since they depend on other services being ready. -- **workers**: Background job processors, if any - -**Always use live-reload tooling**, not plain run commands. The right tool depends on the stack: - -| Stack | Live-reload tool | NOT this | -|-------|-----------------|----------| -| Rust | `cargo watch -x run` | `cargo run` | -| Go | `air` or `gow` | `go run` | -| Node/Bun | `bun --watch` / `nodemon` | `node` | -| Python | `uvicorn --reload` / `watchfiles` | `python` | -| Elixir | `mix phx.server` (has built-in reload) | `mix run --no-halt` | -| Django | `python manage.py runserver` (has built-in reload) | `gunicorn` | - -### 6. Headless Mode (`scripts/start-headless.sh`) - -**Purpose:** Start all services in the background without a TTY, for use by AI agents and CI. This is what makes the project "agent-friendly." - -**Start flow:** -1. Create `tmp/pids/` and `tmp/` directories -2. Source env files + worktree isolation -3. Validate coherence (hard stop on failure) -4. Sync service envs -5. Start each service with `nohup`, writing: - - Stdout/stderr to `tmp/.log` - - PID to `tmp/pids/.pid` -6. Run health checks (HTTP endpoint probes or port readiness checks) for critical services -7. Print status summary - -**Stop flow** (`--stop` flag): -1. Read PID files from `tmp/pids/` -2. Kill each process -3. Bring down docker compose infrastructure -4. Clean up PID files - -**Key rules:** -- Start services in dependency order (infra first, then backends that other services depend on, then frontends). Think about the dependency graph — if service A calls service B, start B first. -- Health checks should have reasonable timeouts (10-30s) and clear error messages -- Use `tmp/` (gitignored) for all ephemeral state — never write PIDs or logs elsewhere -- The stop command should be graceful — try SIGTERM before SIGKILL -- For non-HTTP services (gRPC, message brokers), use TCP port checks (`nc -z`) rather than HTTP probes - -### 7. Service Logs (`scripts/logs.sh`) - -**Purpose:** Color-coded log viewer for headless services. Usable standalone by humans (`./scripts/logs.sh`) and called by `start-headless.sh --logs` internally. - -**Usage:** -- `./scripts/logs.sh` — tail all services, color-coded -- `./scripts/logs.sh api` — tail only the api service -- `./scripts/logs.sh --no-follow` — dump current logs and exit (no live tail) - -**How it works:** -- Discover services from `tmp/pids/*.pid` (same source of truth as headless start/stop) -- Assign each service a distinct ANSI color from a rotating palette -- Prefix every line with a colored `[service-name]` tag -- Default is `--follow` (live tail); `--no-follow` dumps and exits - -**Template logic:** -```bash -#!/usr/bin/env bash -set -euo pipefail -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" - -COLORS=(36 33 32 35 34) # cyan, yellow, green, magenta, blue -follow=true -service_filter="" - -for arg in "$@"; do - case "$arg" in - --no-follow) follow=false ;; - *) service_filter="$arg" ;; - esac -done - -tail_cmd="tail"; $follow && tail_cmd="tail -f" - -color_idx=0 -for pidfile in "$REPO_ROOT"/tmp/pids/*.pid; do - svc="$(basename "$pidfile" .pid)" - logfile="$REPO_ROOT/tmp/${svc}.log" - [ -n "$service_filter" ] && [ "$svc" != "$service_filter" ] && continue - [ -f "$logfile" ] || continue - - color="${COLORS[$((color_idx % ${#COLORS[@]}))]}" - color_idx=$((color_idx + 1)) - $tail_cmd "$logfile" | sed "s/^/$(printf '\033[%sm' "$color")[${svc}]$(printf '\033[0m') /" & -done - -[ $color_idx -eq 0 ] && echo "No service logs found in tmp/" && exit 1 -wait -``` - -**Integration with `start-headless.sh`:** -- `start-headless.sh --logs [service]` delegates to `scripts/logs.sh` — no duplicated logic -- After starting services and health checks pass, print a hint: `View logs: ./scripts/logs.sh` - -### 8. Agent Instructions - -**Purpose:** Tell AI agents how to use the dev environment. Without this, an agent will try to `npm start` or `docker-compose up` and get confused. - -**Add a section to the project's agent configuration file** — `CLAUDE.md` for Claude Code, `AGENTS.md` for OpenCode, or both if the project supports multiple agents: - -```markdown -# Worktrees - -- Use `.claude/worktrees/` for git worktrees (already gitignored) - -## Worktree-safe local dev (required) - -- For any request to start local development, always run `./scripts/init-worktree-dev.sh` first. -- Never source env files from another worktree path; only use `.local/` files in the current repo root. -- Never bypass `scripts/ensure-worktree-coherence.sh`; if it fails, stop and report the mismatch. -- For interactive human sessions, start services with `mprocs --config mprocs.yaml`. -- For non-interactive/headless agent runs (no TTY), use `./scripts/start-headless.sh` (stop with `--stop`). - View logs with `./scripts/logs.sh [service]`. Logs go to `tmp/*.log`, PIDs to `tmp/pids/`. -``` - -For OpenCode (`AGENTS.md`), the content is identical — just placed in the file OpenCode reads. - -## Workflow: Create - -1. **Discover the project** — Read the project structure, identify services, databases, message queues, and existing dev setup (docker-compose files, Makefiles, existing scripts). -2. **Identify ports and services** — List every network port the project uses (databases, APIs, frontends, caches, etc.). -3. **Implement each component** in order (1-8 above), adapting to the project's tech stack. -4. **Test the setup** — Run init, verify coherence, start services in headless mode, confirm health checks pass. -5. **Update .gitignore** — Ensure `.local/`, `tmp/`, and any generated env files are gitignored. - -## Workflow: Iterate - -1. **Understand what exists** — Read the current scripts, identify which components are implemented. -2. **Identify the gap or issue** — Determine what to change: new service, flaky health check, missing coherence check. -3. **Make targeted changes** — Edit the specific component, preserving the architecture. -4. **Re-validate** — Run the coherence check and a headless start/stop cycle to verify. - -## Adapting to Tech Stacks - -The pattern is the same regardless of stack. Here's how the implementation details change: - -| Component | Node/Bun project | Python project | Go project | Rust project | Elixir project | -|-----------|------------------|----------------|------------|-------------|----------------| -| **Backend watch** | `bun --watch` / `nodemon` | `watchfiles` / `uvicorn --reload` | `air` / `gow` | `cargo watch -x run` | `mix phx.server` | -| **Frontend dev** | `vite dev` / `next dev` | N/A or Jinja live-reload | N/A or templ | `trunk serve` (WASM) | N/A (Phoenix LiveView) | -| **DB migration** | `drizzle-kit` / `prisma` | `alembic` / `django migrate` | `goose` / `migrate` | `sqlx migrate` | `mix ecto.migrate` | -| **Package install** | `bun install` / `npm ci` | `pip install -e .` / `uv sync` | `go mod download` | `cargo build` | `mix deps.get` | -| **Health check** | `curl http://localhost:$PORT/health` | Same | Same | Same | Same | -| **gRPC health** | N/A | `grpc_health_probe` or `nc -z` | Same | Same | Same | - -The scripts themselves are always bash — they're the orchestration layer. The services they manage can be anything. - -## Common Pitfalls - -- **Don't hardcode ports in application code.** Services must read their port from environment variables, or the isolation layer can't work. If the project currently hardcodes ports, refactor those first. -- **Don't use `docker-compose.override.yml` for port mapping.** It's not worktree-aware. Instead, use env var substitution in the compose file: `ports: ["${MYAPP_DB_PORT}:5432"]`. -- **Don't skip the coherence check "just this once."** The whole point is that it catches silent misconfigurations. If it's too strict, fix the check — don't bypass it. -- **Don't put secrets in the init script.** Generate random dev-only secrets at init time (e.g., `openssl rand -hex 32`), but never embed real credentials. -- **Don't use plain `go run` or `cargo run` in interactive mode.** Always use a file-watching wrapper (`air`, `cargo watch`) so that code changes trigger automatic restarts. -- **Don't forget inter-service dependency ordering.** If service A depends on service B, start B first and health-check it before starting A. Think about the full dependency graph. - -## File Layout Reference - -After setup, the project should have: - -``` -project-root/ -├── .local/ # Gitignored. Per-worktree config & secrets. -│ ├── .env..local # One per service needing secrets -│ └── # Service configs, TLS certs, etc. -├── tmp/ # Gitignored. Headless runtime state. -│ ├── pids/ # PID files for headless services -│ └── *.log # Service logs from headless mode -├── scripts/ -│ ├── worktree-env.sh # Port isolation (sourced, not executed) -│ ├── init-worktree-dev.sh # Bootstrap entry point -│ ├── ensure-worktree-coherence.sh # Hard-fail validation -│ ├── sync-service-envs.sh # Env propagation to service dirs -│ ├── start-headless.sh # Headless start/stop -│ └── logs.sh # Color-coded service log viewer -├── mprocs.yaml # Interactive process multiplexer config -├── CLAUDE.md # Agent instructions for Claude Code -└── AGENTS.md # Agent instructions for OpenCode -``` diff --git a/.agents/skills/cmk-worktree-dev-env/eval.json b/.agents/skills/cmk-worktree-dev-env/eval.json deleted file mode 100644 index 2d279e2..0000000 --- a/.agents/skills/cmk-worktree-dev-env/eval.json +++ /dev/null @@ -1,89 +0,0 @@ -[ - { - "eval_id": 1, - "eval_name": "nextjs-fastapi-monorepo", - "prompt": "I have a Next.js monorepo with a PostgreSQL database, a FastAPI Python backend for ML inference, and the Next.js frontend. We use pnpm workspaces. I'm starting to use Claude Code with worktrees and I need multiple branches running at the same time without port conflicts. The frontend is on port 3000, the API on 8000, and Postgres on 5432. We also have a Redis cache on 6379. Can you set up worktree-isolated local dev for this project?", - "assertions": [ - "worktree-env.sh computes a deterministic offset from SHA256 of repo root", - "worktree-env.sh offsets all four ports (3000, 8000, 5432, 6379)", - "init-worktree-dev.sh sources worktree-env.sh and creates .local/ directory", - "init-worktree-dev.sh uses set -euo pipefail", - "ensure-worktree-coherence.sh validates DSN ports match computed ports", - "ensure-worktree-coherence.sh supports --quiet flag", - "start-headless.sh has both start and --stop modes", - "start-headless.sh writes PIDs to tmp/pids/ and logs to tmp/", - "start-headless.sh starts services in dependency order (infra first)", - "mprocs.yaml or process-compose.yaml is created with all services", - "CLAUDE.md section includes worktree-safe local dev instructions", - ".gitignore includes .local/ and tmp/" - ] - }, - { - "eval_id": 2, - "eval_name": "go-microservices", - "prompt": "We have a Go microservices project with 3 services: an API gateway (port 8080), a user service (port 8081), and a notification service (port 8082). We use MySQL on 3306 and RabbitMQ on 5672/15672. Everything runs in Docker but we want to be able to run services natively for faster iteration. I work on multiple features in parallel using git worktrees and keep hitting port conflicts. Help me set up worktree-isolated dev.", - "assertions": [ - "worktree-env.sh offsets all 6 ports (8080, 8081, 8082, 3306, 5672, 15672)", - "Docker compose file uses env var substitution for port mapping (not hardcoded ports)", - "init-worktree-dev.sh generates MySQL DSN with computed port", - "ensure-worktree-coherence.sh checks all three service URLs and MySQL DSN", - "start-headless.sh includes health checks for at least the API gateway", - "Interactive mode config includes all 3 Go services with file-watching (air, gow, or similar)", - "CLAUDE.md worktree section is included" - ] - }, - { - "eval_id": 3, - "eval_name": "rails-react-iteration", - "prompt": "I already have a worktree dev setup for my Rails + React project but it's not working well. The coherence check is too basic — it only checks if files exist but doesn't validate ports. The headless mode doesn't have health checks so agents just blindly start services and hope they're up. And there's no env sync — the React app has a hardcoded localhost:3000 for the API URL instead of reading from the worktree env. Can you help me improve this setup?", - "assertions": [ - "Coherence script is enhanced to validate port values in DSNs and URLs (not just file existence)", - "start-headless.sh gains health check logic with timeouts (curl or nc based)", - "A sync-service-envs.sh is created that generates frontend .env.local with dynamic API URL", - "The React app API URL becomes dynamic via env var (REACT_APP_API_URL or similar)", - "Existing working worktree-env.sh is preserved unchanged" - ] - }, - { - "eval_id": 4, - "eval_name": "rust-htmx-sqlite-minio", - "prompt": "I have a Rust web app using axum that serves HTMX templates with Askama. We use SQLite for the database (file-based, no server) and MinIO on port 9000 (API) and 9001 (console) for object storage. The axum server runs on port 3000. I'm using git worktrees heavily and need isolated local dev. The tricky part is SQLite — it's a file, not a network service, so each worktree needs its own DB file path rather than a different port. Can you set up worktree-isolated dev for this?", - "assertions": [ - "worktree-env.sh offsets network ports (3000 for axum, 9000 and 9001 for MinIO)", - "SQLite database path is worktree-local (e.g., .local/dev.db or similar) rather than port-isolated", - "init-worktree-dev.sh handles both port-based and file-based service isolation", - "ensure-worktree-coherence.sh validates SQLite path is within current worktree (not pointing elsewhere)", - "start-headless.sh includes MinIO startup (via docker or binary)", - "Interactive mode uses cargo watch or cargo-watch for Rust live-reload", - "CLAUDE.md worktree section is included" - ] - }, - { - "eval_id": 5, - "eval_name": "elixir-phoenix-rust-sidecar", - "prompt": "We have a polyglot stack: an Elixir Phoenix web app (port 4000) with a Rust sidecar service for heavy ML inference (port 8080). We use Postgres on 5432 for the Phoenix app's OLTP data and ClickHouse on 8123 (HTTP) and 9000 (native) for analytics. The Phoenix app talks to the Rust sidecar over HTTP. We need worktree-isolated dev because our team works on multiple features in parallel and the port conflicts are killing us. Help set this up.", - "assertions": [ - "worktree-env.sh offsets all 5 ports (4000, 8080, 5432, 8123, 9000)", - "init-worktree-dev.sh handles both Elixir and Rust service configuration", - "ensure-worktree-coherence.sh validates Phoenix-to-Rust-sidecar URL uses correct computed port", - "start-headless.sh starts services in correct dependency order (DBs, then Rust sidecar, then Phoenix)", - "Interactive mode uses mix phx.server for Phoenix and cargo watch for Rust", - "Docker compose handles both Postgres and ClickHouse with env var port substitution", - "CLAUDE.md worktree section is included" - ] - }, - { - "eval_id": 6, - "eval_name": "django-go-grpc-nats", - "prompt": "Our project has a Django monolith (port 8000) that talks to a Go gRPC microservice (port 50051) for real-time data processing. We use Redis on 6379 for caching/sessions and NATS on 4222 (client) and 8222 (monitoring) for event streaming. The Django app calls the Go service via gRPC, and the Go service publishes events to NATS that Django consumes. I need worktree-isolated local dev — we have 4 developers using worktrees and constantly stepping on each other's ports.", - "assertions": [ - "worktree-env.sh offsets all 5 ports (8000, 50051, 6379, 4222, 8222)", - "init-worktree-dev.sh generates gRPC service address with computed port for Django to connect to", - "ensure-worktree-coherence.sh validates gRPC address and NATS URL use correct computed ports", - "start-headless.sh includes health checks for the gRPC service (not just HTTP services)", - "Interactive mode uses appropriate dev tools (Django runserver, Go with air/gow)", - "NATS connection URLs in env files use computed port (not hardcoded 4222)", - "CLAUDE.md worktree section is included" - ] - } -] diff --git a/.agents/skills/ui-ux-pro-max/SKILL.md b/.agents/skills/ui-ux-pro-max/SKILL.md deleted file mode 100644 index a64d6c2..0000000 --- a/.agents/skills/ui-ux-pro-max/SKILL.md +++ /dev/null @@ -1,659 +0,0 @@ ---- -name: ui-ux-pro-max -description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples." ---- - -# UI/UX Pro Max - Design Intelligence - -Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations. - -## When to Apply - -This Skill should be used when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**. - -### Must Use - -This Skill must be invoked in the following situations: - -- Designing new pages (Landing Page, Dashboard, Admin, SaaS, Mobile App) -- Creating or refactoring UI components (buttons, modals, forms, tables, charts, etc.) -- Choosing color schemes, typography systems, spacing standards, or layout systems -- Reviewing UI code for user experience, accessibility, or visual consistency -- Implementing navigation structures, animations, or responsive behavior -- Making product-level design decisions (style, information hierarchy, brand expression) -- Improving perceived quality, clarity, or usability of interfaces - -### Recommended - -This Skill is recommended in the following situations: - -- UI looks "not professional enough" but the reason is unclear -- Receiving feedback on usability or experience -- Pre-launch UI quality optimization -- Aligning cross-platform design (Web / iOS / Android) -- Building design systems or reusable component libraries - -### Skip - -This Skill is not needed in the following situations: - -- Pure backend logic development -- Only involving API or database design -- Performance optimization unrelated to the interface -- Infrastructure or DevOps work -- Non-visual scripts or automation tasks - -**Decision criteria**: If the task will change how a feature **looks, feels, moves, or is interacted with**, this Skill should be used. - -## Rule Categories by Priority - -*For human/AI reference: follow priority 1→10 to decide which rule category to focus on first; use `--domain ` to query details when needed. Scripts do not read this table.* - -| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) | -|----------|----------|--------|--------|------------------------|------------------------| -| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels | -| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) | -| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS < 0.1) | Layout thrashing, Cumulative Layout Shift | -| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons | -| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom | -| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components | -| 7 | Animation | MEDIUM | `ux` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion | -| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront | -| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links | -| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning | - -## Quick Reference - -### 1. Accessibility (CRITICAL) - -- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design -- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD) -- `alt-text` - Descriptive alt text for meaningful images -- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG) -- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG) -- `form-labels` - Use label with for attribute -- `skip-links` - Skip to main content for keyboard users -- `heading-hierarchy` - Sequential h1→h6, no level skip -- `color-not-only` - Don't convey info by color alone (add icon/text) -- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD) -- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD) -- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD) -- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG) -- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG) - -### 2. Touch & Interaction (CRITICAL) - -- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed -- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD) -- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone -- `loading-buttons` - Disable button during async operations; show spinner or progress -- `error-feedback` - Clear error messages near problem -- `cursor-pointer` - Add cursor-pointer to clickable elements (Web) -- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll -- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web) -- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG) -- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG) -- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers) -- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG) -- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions -- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges -- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges -- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial) -- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags - -### 3. Performance (HIGH) - -- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets -- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS) -- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD) -- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant -- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet) -- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting -- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI -- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD) -- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes -- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS) -- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media -- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance -- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD) -- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG) -- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard) -- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG) -- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input) -- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile) -- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations) - -### 4. Style Selection (HIGH) - -- `style-match` - Match style to product type (use `--design-system` for recommendations) -- `consistency` - Use same style across all pages -- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis -- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`) -- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.) -- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion -- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers) -- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values -- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent -- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product -- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG) -- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG) -- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG) - -### 5. Layout & Responsive (HIGH) - -- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom) -- `mobile-first` - Design mobile-first, then scale up to tablet and desktop -- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440) -- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom) -- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars -- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width -- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design) -- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps -- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl) -- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000) -- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content -- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience -- `viewport-units` - Prefer min-h-dvh over 100vh on mobile -- `orientation-support` - Keep layout readable and operable in landscape mode -- `content-priority` - Show core content first on mobile; fold or hide secondary content -- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone - -### 6. 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 -- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32) -- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white) -- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD) -- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD) -- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system) -- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD) -- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD) -- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD) -- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG) -- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD) -- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift -- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG) - -### 7. Animation (MEDIUM) - -- `duration-timing` - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD) -- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left -- `loading-states` - Show skeleton or progress indicator when loading exceeds 300ms -- `excessive-motion` - Animate 1-2 key elements per view max -- `easing` - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitions -- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG) -- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap -- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG) -- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG) -- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations) -- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion) -- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD) -- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG) -- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG) -- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG) -- `fade-crossfade` - Use crossfade for content replacement within the same container (MD) -- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD) -- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion) -- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD) -- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel -- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible -- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD) -- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG) -- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes - -### 8. Forms & Feedback (MEDIUM) - -- `input-labels` - Visible label per input (not placeholder-only) -- `error-placement` - Show error below the related field -- `submit-feedback` - Loading then success/error state on submit -- `required-indicators` - Mark required fields (e.g. asterisk) -- `empty-states` - Helpful message and action when no content -- `toast-dismiss` - Auto-dismiss toasts in 3-5s -- `confirmation-dialogs` - Confirm before destructive actions -- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design) -- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD) -- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG) -- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD) -- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD) -- `password-toggle` - Provide show/hide toggle for password fields (MD) -- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD) -- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG) -- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD) -- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD) -- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD) -- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG) -- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG) -- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD) -- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD) -- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD) -- `focus-management` - After submit error, auto-focus the first invalid field (WCAG, MD) -- `error-summary` - For multiple errors, show summary at top with anchor links to each field (WCAG) -- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG) -- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD) -- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG) -- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG) -- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD) -- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD) - -### 9. Navigation Patterns (HIGH) - -- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design) -- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design) -- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD) -- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD) -- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG) -- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design) -- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD) -- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD) -- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD) -- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG) -- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD) -- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD) -- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD) -- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD) -- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD) -- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD) -- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD) -- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive) -- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD) -- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type -- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level -- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG) -- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG) -- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD) -- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD) -- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD) - -### 10. Charts & Data (LOW) - -- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut) -- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD) -- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG) -- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD) -- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD) -- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD) -- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile -- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks) -- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD) -- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame -- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG) -- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD) -- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD) -- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG) -- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity -- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG) -- `legend-interactive` - Legends should be clickable to toggle series visibility (MD) -- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel -- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG) -- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG) -- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens -- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed -- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data -- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data -- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG) -- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG) -- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart -- `export-option` - For data-heavy products, offer CSV/image export of chart data -- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb -- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching - -## How to Use - -Search specific domains using the CLI tool below. - ---- - -## Prerequisites - -Check if Python is installed: - -```bash -python3 --version || python --version -``` - -If Python is not installed, install it based on user's OS: - -**macOS:** -```bash -brew install python3 -``` - -**Ubuntu/Debian:** -```bash -sudo apt update && sudo apt install python3 -``` - -**Windows:** -```powershell -winget install Python.Python.3.12 -``` - ---- - -## How to Use This Skill - -Use this skill when the user requests any of the following: - -| Scenario | Trigger Examples | Start From | -|----------|-----------------|------------| -| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) | -| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) | -| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) | -| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above | -| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section | -| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) | -| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") | -| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) | -| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) | - -Follow this workflow: - -### Step 1: Analyze User Requirements - -Extract key information from user request: -- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid -- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work) -- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc. -- **Stack**: React Native (this project's only tech stack) - -### Step 2: Generate Design System (REQUIRED) - -**Always start with `--design-system`** to get comprehensive recommendations with reasoning: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py " " --design-system [-p "Project Name"] -``` - -This command: -1. Searches 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 skills/ui-ux-pro-max/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 skills/ui-ux-pro-max/scripts/search.py "" --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 skills/ui-ux-pro-max/scripts/search.py "" --design-system --persist -p "Project Name" --page "dashboard" -``` - -This also creates: -- `design-system/pages/dashboard.md` — Page-specific deviations from Master - -**How hierarchical retrieval works:** -1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md` -2. If the page file exists, its rules **override** the Master file -3. If not, use `design-system/MASTER.md` exclusively - -**Context-aware retrieval prompt:** -``` -I am building the [Page Name] page. Please read design-system/MASTER.md. -Also check if design-system/pages/[page-name].md exists. -If the page file exists, prioritize its rules. -If not, use the Master rules exclusively. -Now, generate the code... -``` - -### Step 3: Supplement with Detailed Searches (as needed) - -After getting the design system, use domain searches to get additional details: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --domain [-n ] -``` - -**When to use detailed searches:** - -| Need | Domain | Example | -|------|--------|---------| -| Product type patterns | `product` | `--domain product "entertainment social"` | -| More style options | `style` | `--domain style "glassmorphism dark"` | -| Color palettes | `color` | `--domain color "entertainment vibrant"` | -| Font pairings | `typography` | `--domain typography "playful modern"` | -| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` | -| UX best practices | `ux` | `--domain ux "animation accessibility"` | -| Alternative fonts | `typography` | `--domain typography "elegant luxury"` | -| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` | -| Landing structure | `landing` | `--domain landing "hero social-proof"` | -| React Native perf | `react` | `--domain react "rerender memo list"` | -| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` | -| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` | - -### Step 4: Stack Guidelines (React Native) - -Get React Native implementation-specific best practices: - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --stack react-native -``` - ---- - -## 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 | -| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular | -| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache | -| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type | -| `prompt` | AI prompts, CSS keywords | (style name) | - -### Available Stacks - -| Stack | Focus | -|-------|-------| -| `react-native` | Components, Navigation, Lists | - ---- - -## Example Workflow - -**User request:** "Make an AI search homepage." - -### Step 1: Analyze Requirements -- Product type: Tool (AI search engine) -- Target audience: C-end users looking for fast, intelligent search -- Style keywords: modern, minimal, content-first, dark mode -- Stack: React Native - -### Step 2: Generate Design System (REQUIRED) - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search" -``` - -**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns. - -### Step 3: Supplement with Detailed Searches (as needed) - -```bash -# Get style options for a modern tool product -python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style - -# Get UX best practices for search interaction and loading -python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux -``` - -### Step 4: Stack Guidelines - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native -``` - -**Then:** Synthesize design system + detailed searches and implement the design. - ---- - -## Output Formats - -The `--design-system` flag supports two output formats: - -```bash -# ASCII box (default) - best for terminal display -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system - -# Markdown - best for documentation -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown -``` - ---- - -## Tips for Better Results - -### Query Strategy - -- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"` -- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"` -- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about -- Always add `--stack react-native` for implementation-specific guidance - -### Common Sticking Points - -| Problem | What to Do | -|---------|------------| -| Can't decide on style/color | Re-run `--design-system` with different keywords | -| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` | -| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` | -| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` | -| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` | -| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` | -| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` | - -### Pre-Delivery Checklist - -- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation -- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review -- Test on 375px (small phone) and landscape orientation -- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size -- Check dark mode contrast independently (don't assume light mode values work) -- Confirm all touch targets ≥44pt and no content hidden behind safe areas - ---- - -## Common Rules for Professional UI - -These are frequently overlooked issues that make UI look unprofessional: -Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns. - -### Icons & Visual Elements - -| Rule | Standard | Avoid | Why It Matters | -|------|----------|--------|----------------| -| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. | -| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. | -| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. | -| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. | -| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. | -| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. | -| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. | -| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. | -| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. | -| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. | - - -### Interaction (App) - -| Rule | Do | Don't | -|------|----|----- | -| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap | -| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) | -| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal | -| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing | -| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding | -| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions | -| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics | - -### Light/Dark Mode Contrast - -| Rule | Do | Don't | -|------|----|----- | -| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy | -| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text | -| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background | -| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode | -| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only | -| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values | -| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing | - -### Layout & Spacing - -| Rule | Do | Don't | -|------|----|----- | -| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area | -| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome | -| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens | -| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm | -| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability | -| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing | -| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations | -| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers | - ---- - -## Pre-Delivery Checklist - -Before delivering UI code, verify these items: -Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter). - -### Visual Quality -- [ ] No emojis used as icons (use SVG instead) -- [ ] All icons come from a consistent icon family and style -- [ ] Official brand assets are used with correct proportions and clear space -- [ ] Pressed-state visuals do not shift layout bounds or cause jitter -- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors) - -### Interaction -- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation) -- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android) -- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing -- [ ] Disabled states are visually clear and non-interactive -- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive -- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts) - -### Light/Dark Mode -- [ ] Primary text contrast >=4.5:1 in both light and dark mode -- [ ] Secondary text contrast >=3:1 in both light and dark mode -- [ ] Dividers/borders and interaction states are distinguishable in both modes -- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black) -- [ ] Both themes are tested before delivery (not inferred from a single theme) - -### Layout -- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars -- [ ] Scroll content is not hidden behind fixed/sticky bars -- [ ] Verified on small phone, large phone, and tablet (portrait + landscape) -- [ ] Horizontal insets/gutters adapt correctly by device size and orientation -- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels -- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs) - -### Accessibility -- [ ] All meaningful images/icons have accessibility labels -- [ ] Form fields have labels, hints, and clear error messages -- [ ] Color is not the only indicator -- [ ] Reduced motion and dynamic text size are supported without layout breakage -- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly \ No newline at end of file diff --git a/.agents/skills/ui-ux-pro-max/data/_sync_all.py b/.agents/skills/ui-ux-pro-max/data/_sync_all.py deleted file mode 100644 index 37f7c3a..0000000 --- a/.agents/skills/ui-ux-pro-max/data/_sync_all.py +++ /dev/null @@ -1,414 +0,0 @@ -#!/usr/bin/env python3 -""" -Sync colors.csv and ui-reasoning.csv with the updated products.csv (161 entries). -- Remove deleted product types -- Rename mismatched entries -- Add new entries for missing product types -- Keep colors.csv aligned 1:1 with products.csv -- Renumber everything -""" -import csv, os, json - -BASE = os.path.dirname(os.path.abspath(__file__)) - -# ─── Color derivation helpers ──────────────────────────────────────────────── -def h2r(h): - h = h.lstrip("#") - return tuple(int(h[i:i+2], 16) for i in (0, 2, 4)) - -def r2h(r, g, b): - return f"#{max(0,min(255,int(r))):02X}{max(0,min(255,int(g))):02X}{max(0,min(255,int(b))):02X}" - -def lum(h): - r, g, b = [x/255.0 for x in h2r(h)] - r, g, b = [(x/12.92 if x<=0.03928 else ((x+0.055)/1.055)**2.4) for x in (r, g, b)] - return 0.2126*r + 0.7152*g + 0.0722*b - -def is_dark(bg): - return lum(bg) < 0.18 - -def on_color(bg): - return "#FFFFFF" if lum(bg) < 0.4 else "#0F172A" - -def blend(a, b, f=0.15): - ra, ga, ba = h2r(a) - rb, gb, bb = h2r(b) - return r2h(ra+(rb-ra)*f, ga+(gb-ga)*f, ba+(bb-ba)*f) - -def shift(h, n): - r, g, b = h2r(h) - return r2h(r+n, g+n, b+n) - -def derive_row(pt, pri, sec, acc, bg, notes=""): - """Generate full 16-token color row from 4 base colors.""" - dark = is_dark(bg) - fg = "#FFFFFF" if dark else "#0F172A" - on_pri = on_color(pri) - on_sec = on_color(sec) - on_acc = on_color(acc) - card = shift(bg, 10) if dark else "#FFFFFF" - card_fg = "#FFFFFF" if dark else "#0F172A" - muted = blend(bg, pri, 0.08) if dark else blend("#FFFFFF", pri, 0.06) - muted_fg = "#94A3B8" if dark else "#64748B" - border = f"rgba(255,255,255,0.08)" if dark else blend("#FFFFFF", pri, 0.12) - destr = "#DC2626" - on_destr = "#FFFFFF" - ring = pri - return [pt, pri, on_pri, sec, on_sec, acc, on_acc, bg, fg, card, card_fg, muted, muted_fg, border, destr, on_destr, ring, notes] - -# ─── Rename maps ───────────────────────────────────────────────────────────── -COLOR_RENAMES = { - "Quantum Computing": "Quantum Computing Interface", - "Biohacking / Longevity": "Biohacking / Longevity App", - "Autonomous Systems": "Autonomous Drone Fleet Manager", - "Generative AI Art": "Generative Art Platform", - "Spatial / Vision OS": "Spatial Computing OS / App", - "Climate Tech": "Sustainable Energy / Climate Tech", -} -UI_RENAMES = { - "Architecture/Interior": "Architecture / Interior", - "Autonomous Drone Fleet": "Autonomous Drone Fleet Manager", - "B2B SaaS Enterprise": "B2B Service", - "Biohacking/Longevity App": "Biohacking / Longevity App", - "Biotech/Life Sciences": "Biotech / Life Sciences", - "Developer Tool/IDE": "Developer Tool / IDE", - "Education": "Educational App", - "Fintech (Banking)": "Fintech/Crypto", - "Government/Public": "Government/Public Service", - "Home Services": "Home Services (Plumber/Electrician)", - "Micro-Credentials/Badges": "Micro-Credentials/Badges Platform", - "Music/Entertainment": "Music Streaming", - "Quantum Computing": "Quantum Computing Interface", - "Real Estate": "Real Estate/Property", - "Remote Work/Collaboration": "Remote Work/Collaboration Tool", - "Restaurant/Food": "Restaurant/Food Service", - "SaaS Dashboard": "Analytics Dashboard", - "Space Tech/Aerospace": "Space Tech / Aerospace", - "Spatial Computing OS": "Spatial Computing OS / App", - "Startup Landing": "Micro SaaS", - "Sustainable Energy/Climate": "Sustainable Energy / Climate Tech", - "Travel/Tourism": "Travel/Tourism Agency", - "Wellness/Mental Health": "Mental Health App", -} - -REMOVE_TYPES = { - "Service Landing Page", "Sustainability/ESG Platform", - "Cleaning Service", "Coffee Shop", - "Consulting Firm", "Conference/Webinar Platform", -} - -# ─── New color definitions: (primary, secondary, accent, bg, notes) ────────── -# Grouped by category for clarity. Each tuple generates a full 16-token row. -NEW_COLORS = { - # ── Old #97-#116 that never got colors ── - "Todo & Task Manager": ("#2563EB","#3B82F6","#059669","#F8FAFC","Functional blue + progress green"), - "Personal Finance Tracker": ("#1E40AF","#3B82F6","#059669","#0F172A","Trust blue + profit green on dark"), - "Chat & Messaging App": ("#2563EB","#6366F1","#059669","#FFFFFF","Messenger blue + online green"), - "Notes & Writing App": ("#78716C","#A8A29E","#D97706","#FFFBEB","Warm ink + amber accent on cream"), - "Habit Tracker": ("#D97706","#F59E0B","#059669","#FFFBEB","Streak amber + habit green"), - "Food Delivery / On-Demand": ("#EA580C","#F97316","#2563EB","#FFF7ED","Appetizing orange + trust blue"), - "Ride Hailing / Transportation":("#1E293B","#334155","#2563EB","#0F172A","Map dark + route blue"), - "Recipe & Cooking App": ("#9A3412","#C2410C","#059669","#FFFBEB","Warm terracotta + fresh green"), - "Meditation & Mindfulness": ("#7C3AED","#8B5CF6","#059669","#FAF5FF","Calm lavender + mindful green"), - "Weather App": ("#0284C7","#0EA5E9","#F59E0B","#F0F9FF","Sky blue + sun amber"), - "Diary & Journal App": ("#92400E","#A16207","#6366F1","#FFFBEB","Warm journal brown + ink violet"), - "CRM & Client Management": ("#2563EB","#3B82F6","#059669","#F8FAFC","Professional blue + deal green"), - "Inventory & Stock Management":("#334155","#475569","#059669","#F8FAFC","Industrial slate + stock green"), - "Flashcard & Study Tool": ("#7C3AED","#8B5CF6","#059669","#FAF5FF","Study purple + correct green"), - "Booking & Appointment App": ("#0284C7","#0EA5E9","#059669","#F0F9FF","Calendar blue + available green"), - "Invoice & Billing Tool": ("#1E3A5F","#2563EB","#059669","#F8FAFC","Navy professional + paid green"), - "Grocery & Shopping List": ("#059669","#10B981","#D97706","#ECFDF5","Fresh green + food amber"), - "Timer & Pomodoro": ("#DC2626","#EF4444","#059669","#0F172A","Focus red on dark + break green"), - "Parenting & Baby Tracker": ("#EC4899","#F472B6","#0284C7","#FDF2F8","Soft pink + trust blue"), - "Scanner & Document Manager": ("#1E293B","#334155","#2563EB","#F8FAFC","Document grey + scan blue"), - # ── A. Utility / Productivity ── - "Calendar & Scheduling App": ("#2563EB","#3B82F6","#059669","#F8FAFC","Calendar blue + event green"), - "Password Manager": ("#1E3A5F","#334155","#059669","#0F172A","Vault dark blue + secure green"), - "Expense Splitter / Bill Split":("#059669","#10B981","#DC2626","#F8FAFC","Balance green + owe red"), - "Voice Recorder & Memo": ("#DC2626","#EF4444","#2563EB","#FFFFFF","Recording red + waveform blue"), - "Bookmark & Read-Later": ("#D97706","#F59E0B","#2563EB","#FFFBEB","Warm amber + link blue"), - "Translator App": ("#2563EB","#0891B2","#EA580C","#F8FAFC","Global blue + teal + accent orange"), - "Calculator & Unit Converter": ("#EA580C","#F97316","#2563EB","#1C1917","Operation orange on dark"), - "Alarm & World Clock": ("#D97706","#F59E0B","#6366F1","#0F172A","Time amber + night indigo on dark"), - "File Manager & Transfer": ("#2563EB","#3B82F6","#D97706","#F8FAFC","Folder blue + file amber"), - "Email Client": ("#2563EB","#3B82F6","#DC2626","#FFFFFF","Inbox blue + priority red"), - # ── B. Games ── - "Casual Puzzle Game": ("#EC4899","#8B5CF6","#F59E0B","#FDF2F8","Cheerful pink + reward gold"), - "Trivia & Quiz Game": ("#2563EB","#7C3AED","#F59E0B","#EFF6FF","Quiz blue + gold leaderboard"), - "Card & Board Game": ("#15803D","#166534","#D97706","#0F172A","Felt green + gold on dark"), - "Idle & Clicker Game": ("#D97706","#F59E0B","#7C3AED","#FFFBEB","Coin gold + prestige purple"), - "Word & Crossword Game": ("#15803D","#059669","#D97706","#FFFFFF","Word green + letter amber"), - "Arcade & Retro Game": ("#DC2626","#2563EB","#22C55E","#0F172A","Neon red+blue on dark + score green"), - # ── C. Creator Tools ── - "Photo Editor & Filters": ("#7C3AED","#6366F1","#0891B2","#0F172A","Editor violet + filter cyan on dark"), - "Short Video Editor": ("#EC4899","#DB2777","#2563EB","#0F172A","Video pink on dark + timeline blue"), - "Drawing & Sketching Canvas": ("#7C3AED","#8B5CF6","#0891B2","#1C1917","Canvas purple + tool teal on dark"), - "Music Creation & Beat Maker": ("#7C3AED","#6366F1","#22C55E","#0F172A","Studio purple + waveform green on dark"), - "Meme & Sticker Maker": ("#EC4899","#F59E0B","#2563EB","#FFFFFF","Viral pink + comedy yellow + share blue"), - "AI Photo & Avatar Generator": ("#7C3AED","#6366F1","#EC4899","#FAF5FF","AI purple + generation pink"), - "Link-in-Bio Page Builder": ("#2563EB","#7C3AED","#EC4899","#FFFFFF","Brand blue + creator purple"), - # ── D. Personal Life ── - "Wardrobe & Outfit Planner": ("#BE185D","#EC4899","#D97706","#FDF2F8","Fashion rose + gold accent"), - "Plant Care Tracker": ("#15803D","#059669","#D97706","#F0FDF4","Nature green + sun yellow"), - "Book & Reading Tracker": ("#78716C","#92400E","#D97706","#FFFBEB","Book brown + page amber"), - "Couple & Relationship App": ("#BE185D","#EC4899","#DC2626","#FDF2F8","Romance rose + love red"), - "Family Calendar & Chores": ("#2563EB","#059669","#D97706","#F8FAFC","Family blue + chore green"), - "Mood Tracker": ("#7C3AED","#6366F1","#D97706","#FAF5FF","Mood purple + insight amber"), - "Gift & Wishlist": ("#DC2626","#D97706","#EC4899","#FFF1F2","Gift red + gold + surprise pink"), - # ── E. Health ── - "Running & Cycling GPS": ("#EA580C","#F97316","#059669","#0F172A","Energetic orange + pace green on dark"), - "Yoga & Stretching Guide": ("#6B7280","#78716C","#0891B2","#F5F5F0","Sage neutral + calm teal"), - "Sleep Tracker": ("#4338CA","#6366F1","#7C3AED","#0F172A","Night indigo + dream violet on dark"), - "Calorie & Nutrition Counter": ("#059669","#10B981","#EA580C","#ECFDF5","Healthy green + macro orange"), - "Period & Cycle Tracker": ("#BE185D","#EC4899","#7C3AED","#FDF2F8","Blush rose + fertility lavender"), - "Medication & Pill Reminder": ("#0284C7","#0891B2","#DC2626","#F0F9FF","Medical blue + alert red"), - "Water & Hydration Reminder": ("#0284C7","#06B6D4","#0891B2","#F0F9FF","Refreshing blue + water cyan"), - "Fasting & Intermittent Timer":("#6366F1","#4338CA","#059669","#0F172A","Fasting indigo on dark + eating green"), - # ── F. Social ── - "Anonymous Community / Confession":("#475569","#334155","#0891B2","#0F172A","Protective grey + subtle teal on dark"), - "Local Events & Discovery": ("#EA580C","#F97316","#2563EB","#FFF7ED","Event orange + map blue"), - "Study Together / Virtual Coworking":("#2563EB","#3B82F6","#059669","#F8FAFC","Focus blue + session green"), - # ── G. Education ── - "Coding Challenge & Practice": ("#22C55E","#059669","#D97706","#0F172A","Code green + difficulty amber on dark"), - "Kids Learning (ABC & Math)": ("#2563EB","#F59E0B","#EC4899","#EFF6FF","Learning blue + play yellow + fun pink"), - "Music Instrument Learning": ("#DC2626","#9A3412","#D97706","#FFFBEB","Musical red + warm amber"), - # ── H. Transport ── - "Parking Finder": ("#2563EB","#059669","#DC2626","#F0F9FF","Available blue/green + occupied red"), - "Public Transit Guide": ("#2563EB","#0891B2","#EA580C","#F8FAFC","Transit blue + line colors"), - "Road Trip Planner": ("#EA580C","#0891B2","#D97706","#FFF7ED","Adventure orange + map teal"), - # ── I. Safety & Lifestyle ── - "VPN & Privacy Tool": ("#1E3A5F","#334155","#22C55E","#0F172A","Shield dark + connected green"), - "Emergency SOS & Safety": ("#DC2626","#EF4444","#2563EB","#FFF1F2","Alert red + safety blue"), - "Wallpaper & Theme App": ("#7C3AED","#EC4899","#2563EB","#FAF5FF","Aesthetic purple + trending pink"), - "White Noise & Ambient Sound": ("#475569","#334155","#4338CA","#0F172A","Ambient grey + deep indigo on dark"), - "Home Decoration & Interior Design":("#78716C","#A8A29E","#D97706","#FAF5F2","Interior warm grey + gold accent"), -} - -# ─── 1. REBUILD colors.csv ─────────────────────────────────────────────────── -def rebuild_colors(): - src = os.path.join(BASE, "colors.csv") - with open(src, newline="", encoding="utf-8") as f: - reader = csv.DictReader(f) - headers = reader.fieldnames - existing = list(reader) - - # Build lookup: Product Type -> row data - color_map = {} - for row in existing: - pt = row.get("Product Type", "").strip() - if not pt: - continue - # Remove deleted types - if pt in REMOVE_TYPES: - print(f" [colors] REMOVE: {pt}") - continue - # Rename mismatched types - if pt in COLOR_RENAMES: - new_name = COLOR_RENAMES[pt] - print(f" [colors] RENAME: {pt} → {new_name}") - row["Product Type"] = new_name - pt = new_name - color_map[pt] = row - - # Read products.csv to get the correct order - with open(os.path.join(BASE, "products.csv"), newline="", encoding="utf-8") as f: - products = list(csv.DictReader(f)) - - # Build final rows in products.csv order - final_rows = [] - added = 0 - for i, prod in enumerate(products, 1): - pt = prod["Product Type"] - if pt in color_map: - row = color_map[pt] - row["No"] = str(i) - final_rows.append(row) - elif pt in NEW_COLORS: - pri, sec, acc, bg, notes = NEW_COLORS[pt] - new_row = derive_row(pt, pri, sec, acc, bg, notes) - d = dict(zip(headers, [str(i)] + new_row)) - final_rows.append(d) - added += 1 - else: - print(f" [colors] WARNING: No color data for '{pt}' - using defaults") - new_row = derive_row(pt, "#2563EB", "#3B82F6", "#059669", "#F8FAFC", "Auto-generated default") - d = dict(zip(headers, [str(i)] + new_row)) - final_rows.append(d) - added += 1 - - # Write - with open(src, "w", newline="", encoding="utf-8") as f: - writer = csv.DictWriter(f, fieldnames=headers) - writer.writeheader() - writer.writerows(final_rows) - - product_count = len(products) - print(f"\n ✅ colors.csv: {len(final_rows)} rows ({product_count} products)") - print(f" Added: {added} new color rows") - -# ─── 2. REBUILD ui-reasoning.csv ───────────────────────────────────────────── -def derive_ui_reasoning(prod): - """Generate ui-reasoning row from products.csv row.""" - pt = prod["Product Type"] - style = prod.get("Primary Style Recommendation", "") - landing = prod.get("Landing Page Pattern", "") - color_focus = prod.get("Color Palette Focus", "") - considerations = prod.get("Key Considerations", "") - keywords = prod.get("Keywords", "") - - # Typography mood derived from style - typo_map = { - "Minimalism": "Professional + Clean hierarchy", - "Glassmorphism": "Modern + Clear hierarchy", - "Brutalism": "Bold + Oversized + Monospace", - "Claymorphism": "Playful + Rounded + Friendly", - "Dark Mode": "High contrast + Light on dark", - "Neumorphism": "Subtle + Soft + Monochromatic", - "Flat Design": "Bold + Clean + Sans-serif", - "Vibrant": "Energetic + Bold + Large", - "Aurora": "Elegant + Gradient-friendly", - "AI-Native": "Conversational + Minimal chrome", - "Organic": "Warm + Humanist + Natural", - "Motion": "Dynamic + Hierarchy-shifting", - "Accessible": "Large + High contrast + Clear", - "Soft UI": "Modern + Accessible + Balanced", - "Trust": "Professional + Serif accents", - "Swiss": "Grid-based + Mathematical + Helvetica", - "3D": "Immersive + Spatial + Variable", - "Retro": "Nostalgic + Monospace + Neon", - "Cyberpunk": "Terminal + Monospace + Neon", - "Pixel": "Retro + Blocky + 8-bit", - } - typo_mood = "Professional + Clear hierarchy" - for key, val in typo_map.items(): - if key.lower() in style.lower(): - typo_mood = val - break - - # Key effects from style - eff_map = { - "Glassmorphism": "Backdrop blur (10-20px) + Translucent overlays", - "Neumorphism": "Dual shadows (light+dark) + Soft press 150ms", - "Claymorphism": "Multi-layer shadows + Spring bounce + Soft press 200ms", - "Brutalism": "No transitions + Hard borders + Instant feedback", - "Dark Mode": "Subtle glow + Neon accents + High contrast", - "Flat Design": "Color shift hover + Fast 150ms transitions + No shadows", - "Minimalism": "Subtle hover 200ms + Smooth transitions + Clean", - "Motion-Driven": "Scroll animations + Parallax + Page transitions", - "Micro-interactions": "Haptic feedback + Small 50-100ms animations", - "Vibrant": "Large section gaps 48px+ + Color shift hover + Scroll-snap", - "Aurora": "Flowing gradients 8-12s + Color morphing", - "AI-Native": "Typing indicator + Streaming text + Context reveal", - "Organic": "Rounded 16-24px + Natural shadows + Flowing SVG", - "Soft UI": "Improved shadows + Modern 200-300ms + Focus visible", - "3D": "WebGL/Three.js + Parallax 3-5 layers + Physics 300-400ms", - "Trust": "Clear focus rings + Badge hover + Metric pulse", - "Accessible": "Focus rings 3-4px + ARIA + Reduced motion", - } - key_effects = "Subtle hover (200ms) + Smooth transitions" - for key, val in eff_map.items(): - if key.lower() in style.lower(): - key_effects = val - break - - # Decision rules - rules = {} - if "dark" in style.lower() or "oled" in style.lower(): - rules["if_light_mode_needed"] = "provide-theme-toggle" - if "glass" in style.lower(): - rules["if_low_performance"] = "fallback-to-flat" - if "conversion" in landing.lower(): - rules["if_conversion_focused"] = "add-urgency-colors" - if "social" in landing.lower(): - rules["if_trust_needed"] = "add-testimonials" - if "data" in keywords.lower() or "dashboard" in keywords.lower(): - rules["if_data_heavy"] = "prioritize-data-density" - if not rules: - rules["if_ux_focused"] = "prioritize-clarity" - rules["if_mobile"] = "optimize-touch-targets" - - # Anti-patterns - anti_patterns = [] - if "minimalism" in style.lower() or "minimal" in style.lower(): - anti_patterns.append("Excessive decoration") - if "dark" in style.lower(): - anti_patterns.append("Pure white backgrounds") - if "flat" in style.lower(): - anti_patterns.append("Complex shadows + 3D effects") - if "vibrant" in style.lower(): - anti_patterns.append("Muted colors + Low energy") - if "accessible" in style.lower(): - anti_patterns.append("Color-only indicators") - if not anti_patterns: - anti_patterns = ["Inconsistent styling", "Poor contrast ratios"] - anti_str = " + ".join(anti_patterns[:2]) - - return { - "UI_Category": pt, - "Recommended_Pattern": landing, - "Style_Priority": style, - "Color_Mood": color_focus, - "Typography_Mood": typo_mood, - "Key_Effects": key_effects, - "Decision_Rules": json.dumps(rules), - "Anti_Patterns": anti_str, - "Severity": "HIGH" - } - - -def rebuild_ui_reasoning(): - src = os.path.join(BASE, "ui-reasoning.csv") - with open(src, newline="", encoding="utf-8") as f: - reader = csv.DictReader(f) - headers = reader.fieldnames - existing = list(reader) - - # Build lookup - ui_map = {} - for row in existing: - cat = row.get("UI_Category", "").strip() - if not cat: - continue - if cat in REMOVE_TYPES: - print(f" [ui-reason] REMOVE: {cat}") - continue - if cat in UI_RENAMES: - new_name = UI_RENAMES[cat] - print(f" [ui-reason] RENAME: {cat} → {new_name}") - row["UI_Category"] = new_name - cat = new_name - ui_map[cat] = row - - with open(os.path.join(BASE, "products.csv"), newline="", encoding="utf-8") as f: - products = list(csv.DictReader(f)) - - final_rows = [] - added = 0 - for i, prod in enumerate(products, 1): - pt = prod["Product Type"] - if pt in ui_map: - row = ui_map[pt] - row["No"] = str(i) - final_rows.append(row) - else: - row = derive_ui_reasoning(prod) - row["No"] = str(i) - final_rows.append(row) - added += 1 - - with open(src, "w", newline="", encoding="utf-8") as f: - writer = csv.DictWriter(f, fieldnames=headers) - writer.writeheader() - writer.writerows(final_rows) - - print(f"\n ✅ ui-reasoning.csv: {len(final_rows)} rows") - print(f" Added: {added} new reasoning rows") - - -# ─── MAIN ──────────────────────────────────────────────────────────────────── -if __name__ == "__main__": - print("=== Rebuilding colors.csv ===") - rebuild_colors() - print("\n=== Rebuilding ui-reasoning.csv ===") - rebuild_ui_reasoning() - print("\n🎉 Done!") diff --git a/.agents/skills/ui-ux-pro-max/data/app-interface.csv b/.agents/skills/ui-ux-pro-max/data/app-interface.csv deleted file mode 100644 index f34c3cd..0000000 --- a/.agents/skills/ui-ux-pro-max/data/app-interface.csv +++ /dev/null @@ -1,31 +0,0 @@ -No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity -1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"","",Critical -2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"Email","",Critical -3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"Submit","Submit",High -4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"{status}","{status}",Medium -5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"","",Medium -6,Touch,Touch Target Size,touch 44x44 hitSlop,iOS/Android/React Native,Primary touch targets must be at least 44x44pt,Increase hitSlop or padding to meet minimum,Small icons with tiny touch area,"","",Critical -7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,"