@mohammadhprp/system-prompt 0.11.0 → 0.11.2

package/framework/skills/tlc-spec-driven/scripts/validate_state.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+validate_state.py - deterministic completion gate for a feature.
+
+The skill's strongest invariant is "the Verifier is always-on, never prompted;
+Execute is not done until validation.md reports PASS." That is prose the model
+must remember. This turns it into a checkable pass/fail the closing step runs
+automatically, so declaring a feature done without a real Verifier report fails
+loudly instead of slipping through.
+
+It does NOT merely check that validation.md exists - a report that exists but is
+empty, still holds the template placeholder, or has no evidence would pass a
+shallow existence check while proving nothing. This gate requires a real,
+filled verdict plus at least one file:line evidence citation.
+
+Operates only on the .specs/ markdown artifacts (stack- and tool-agnostic). No
+dependencies. Run from the project root (the dir that contains .specs), or pass
+--root. Meant to be invoked by the skill as the closing gate of Execute, the
+same way lessons.py is invoked at distillation - not a manual step.
+
+Usage:
+  python3 <skill-dir>/scripts/validate_state.py [feature]
+  python3 <skill-dir>/scripts/validate_state.py
+
+  Invoke from the skill directory that ships this script (not the project root).
+  Pass --root when cwd is not the project that contains .specs/.
+
+Exit codes: 0 ok, 1 a completed feature is missing a real PASS report,
+            2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+# A file:line citation: a path with an extension, then :<line>. e.g. src/a.ts:42
+EVIDENCE_RE = re.compile(r"[\w./-]+\.[A-Za-z0-9]+:\d+")
+
+
+def _feature_dirs(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return base, []
+    dirs = [
+        d for d in sorted(os.listdir(base))
+        if os.path.isdir(os.path.join(base, d))
+    ]
+    return base, dirs
+
+
+def _verdict(text):
+    """Return 'pass', 'fail', 'unfilled', or None from a validation report."""
+    # Look at the '## Validation' heading first, then a '**Result**' line.
+    lines = text.splitlines()
+    candidates = [
+        ln for ln in lines
+        if re.search(r"^#{1,4}\s*validation\b", ln.strip(), re.IGNORECASE)
+        or re.search(r"\*{0,2}result\*{0,2}\s*:", ln.strip(), re.IGNORECASE)
+    ]
+    hay = " ".join(candidates) if candidates else text
+    has_pass = re.search(r"\bPASS\b", hay) is not None
+    has_fail = re.search(r"\bFAIL\b", hay) is not None
+    if has_pass and has_fail:
+        # Both present on the verdict line = unfilled template "[PASS | FAIL]".
+        return "unfilled"
+    if has_pass:
+        return "pass"
+    if has_fail:
+        return "fail"
+    return None
+
+
+def _appears_complete(fdir):
+    """Conservative completeness heuristic for the cross-check mode.
+
+    A feature 'appears complete' if it already has a validation.md, or if it has
+    a tasks.md with at least one task and no unchecked '- [ ]' boxes left. When
+    the signal is ambiguous (no tasks.md, Tasks phase skipped), returns False so
+    an in-flight feature is never falsely flagged.
+    """
+    if os.path.exists(os.path.join(fdir, "validation.md")):
+        return True
+    tasks = os.path.join(fdir, "tasks.md")
+    if not os.path.exists(tasks):
+        return False
+    body = open(tasks, encoding="utf-8", errors="replace").read()
+    if not re.search(r"^#{2,4}\s+T\d+\s*:", body, re.MULTILINE):
+        return False
+    if re.search(r"^\s*-\s*\[\s\]", body, re.MULTILINE):
+        return False  # unchecked box remains -> still in progress
+    return True
+
+
+def _check_feature(fdir, name):
+    """Return list of error strings for one feature (empty = pass)."""
+    errors = []
+    vpath = os.path.join(fdir, "validation.md")
+    if not os.path.exists(vpath):
+        errors.append(
+            f"{name}: no validation.md - Execute is not done until the Verifier "
+            f"writes it (author != verifier). Dispatch validation before marking done."
+        )
+        return errors
+    text = open(vpath, encoding="utf-8", errors="replace").read()
+    verdict = _verdict(text)
+    if verdict is None:
+        errors.append(f"{name}: validation.md has no PASS/FAIL verdict (a prose-only report does not count)")
+    elif verdict == "unfilled":
+        errors.append(f"{name}: validation.md verdict is still the template placeholder '[PASS | FAIL]' - not filled")
+    elif verdict == "fail":
+        errors.append(f"{name}: validation.md verdict is FAIL - route the ranked gaps to fix tasks, then re-verify (feature is not done)")
+    if verdict == "pass" and not EVIDENCE_RE.search(text):
+        errors.append(f"{name}: validation.md is PASS but cites no file:line evidence - evidence-or-zero not satisfied")
+    return errors
+
+
+def _resolve(root, feature):
+    base, dirs = _feature_dirs(root)
+    if not os.path.isdir(base):
+        print(f"validate_state: no {base} directory - nothing to check.")
+        return []
+    if feature:
+        fdir = feature if os.path.isdir(feature) else os.path.join(base, feature)
+        if not os.path.isdir(fdir):
+            print(f"validate_state: feature not found: {feature}", file=sys.stderr)
+            raise SystemExit(2)
+        return [(fdir, os.path.basename(fdir.rstrip("/")))]
+    if len(dirs) == 1:
+        return [(os.path.join(base, dirs[0]), dirs[0])]
+    if not dirs:
+        print("validate_state: no features under .specs/features/ - nothing to check.")
+        return []
+    # Cross-check mode: only features that appear complete.
+    picked = [(os.path.join(base, d), d) for d in dirs if _appears_complete(os.path.join(base, d))]
+    if not picked:
+        print("validate_state: no completed feature detected (all in progress) - nothing to gate.")
+    return picked
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_state.py", description="Deterministic completion gate: a done feature must have a real PASS validation report.")
+    p.add_argument("feature", nargs="?", default=None, help="Feature dir or name (default: sole feature, else cross-check all completed)")
+    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
+    args = p.parse_args(argv)
+    root = os.path.abspath(args.root)
+
+    targets = _resolve(root, args.feature)
+    all_errors = []
+    for fdir, name in targets:
+        all_errors += _check_feature(fdir, name)
+
+    for e in all_errors:
+        print(f"  ERROR {e}")
+    n = len(all_errors)
+    checked = ", ".join(name for _, name in targets) or "(none)"
+    print(f"\nvalidate_state: {n} error(s) across [{checked}]")
+    return 1 if n else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/framework/skills/tlc-spec-driven/scripts/validate_tasks.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+validate_tasks.py - deterministic pre-approval checks for a feature tasks.md.
+
+Turns the three pre-approval checks (task granularity, diagram-vs-definition
+cross-check, test co-location) into a checkable pass/fail run BEFORE tasks are
+presented for approval, instead of trusting the model to build the tables by
+hand. Pure standard library, zero dependencies. Operates only on the tasks.md
+markdown artifact, so it is stack-agnostic and tool-agnostic.
+
+What it checks (heuristic markdown inspection, not a full parser):
+  ERROR  - a required section is missing
+  ERROR  - a task is missing its `Tests` or `Gate` field
+  ERROR  - a task depends on a task in a LATER phase (dependencies point back only)
+  ERROR  - a dependency edge shown in the diagram has no matching `Depends on`
+           (and vice-versa) when both sides are parseable
+  WARN   - a task's `Where` names multiple files (granularity smell -> split it)
+  WARN   - a task says `Tests: none` (confirm the coverage matrix agrees)
+  WARN   - the diagram could not be parsed confidently (cross-check skipped)
+
+Usage:
+  python3 <skill-dir>/scripts/validate_tasks.py [target] [--root DIR] [--strict]
+
+  Invoke from the skill directory that ships this script (not the project root).
+  target    Path to a tasks.md, a feature directory, or a project root.
+            Omitted -> auto-detect the single feature under <root>/.specs/features/.
+  --root    Project root that contains .specs/ (default: current dir).
+  --strict  Treat warnings as errors.
+
+Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+REQUIRED_SECTIONS = ["Test Coverage Matrix", "Gate Check Commands", "Execution Plan", "Task Breakdown"]
+TASK_RE = re.compile(r"^#{2,4}\s+(T\d+)\s*:", re.IGNORECASE)
+EDGE_RE = re.compile(r"\bT\d+\b")
+FILE_HINT_RE = re.compile(r"[\w./-]+\.\w{1,6}\b")
+
+
+def resolve_tasks(target, root):
+    if target:
+        if os.path.isfile(target):
+            return target
+        if os.path.isdir(target):
+            cand = os.path.join(target, "tasks.md")
+            if os.path.isfile(cand):
+                return cand
+            return _autodetect(target)
+        # Not a path: treat as a feature name under <root>/.specs/features/<name>/
+        cand = os.path.join(root, ".specs", "features", target, "tasks.md")
+        if os.path.isfile(cand):
+            return cand
+        return None
+    return _autodetect(root)
+
+
+def _autodetect(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return None
+    features = [d for d in sorted(os.listdir(base)) if os.path.isfile(os.path.join(base, d, "tasks.md"))]
+    if len(features) == 1:
+        return os.path.join(base, features[0], "tasks.md")
+    if len(features) == 0:
+        return None
+    raise SystemExit(
+        "validate_tasks: multiple features found; pass one explicitly:\n  "
+        + "\n  ".join(os.path.join(base, f, "tasks.md") for f in features)
+    )
+
+
+def section_present(lines, name):
+    return any(re.match(r"^#{1,4}\s+" + re.escape(name) + r"\b", ln.strip()) for ln in lines)
+
+
+def parse_tasks(lines):
+    """Return a dict: task_id -> {'deps': set, 'tests': str|None, 'gate': str|None, 'where': str}."""
+    tasks = {}
+    current = None
+    for ln in lines:
+        m = TASK_RE.match(ln.strip())
+        if m:
+            current = m.group(1).upper()
+            tasks[current] = {"deps": set(), "tests": None, "gate": None, "where": ""}
+            continue
+        if current is None:
+            continue
+        stripped = ln.strip()
+        dm = re.match(r"^\*{0,2}Depends on\*{0,2}\s*:\s*(.*)$", stripped, re.IGNORECASE)
+        if dm:
+            body = dm.group(1)
+            if "none" not in body.lower():
+                for e in EDGE_RE.findall(body.upper()):
+                    tasks[current]["deps"].add(e)
+        wm = re.match(r"^\*{0,2}Where\*{0,2}\s*:\s*(.*)$", stripped, re.IGNORECASE)
+        if wm:
+            tasks[current]["where"] = wm.group(1)
+        tm = re.match(r"^\*{0,2}Tests\*{0,2}\s*:\s*(.*)$", stripped, re.IGNORECASE)
+        if tm:
+            tasks[current]["tests"] = tm.group(1).strip()
+        gm = re.match(r"^\*{0,2}Gate\*{0,2}\s*:\s*(.*)$", stripped, re.IGNORECASE)
+        if gm:
+            tasks[current]["gate"] = gm.group(1).strip()
+    return tasks
+
+
+def parse_phase_membership(lines):
+    """Map task_id -> phase index, read from '### Phase N' headers in the Execution Plan."""
+    membership = {}
+    phase_idx = 0
+    in_phase = False
+    for ln in lines:
+        pm = re.match(r"^#{2,4}\s+Phase\s+(\d+)", ln.strip(), re.IGNORECASE)
+        if pm:
+            phase_idx = int(pm.group(1))
+            in_phase = True
+            continue
+        if in_phase:
+            # Map a task to a phase ONLY when it appears as a task header (### Tn:),
+            # never when it is merely referenced (e.g. in a `Depends on:` line or a
+            # diagram arrow), which would misattribute the referenced task to this phase.
+            hm = TASK_RE.match(ln.strip())
+            if hm:
+                membership[hm.group(1).upper()] = phase_idx
+    return membership
+
+
+def parse_diagram_edges(lines):
+    """Best-effort: parse 'Tx -> Ty' / 'Tx → Ty' arrow chains from fenced blocks.
+    Returns (edges:set[(src,dst)], parsed:bool)."""
+    edges = set()
+    in_fence = False
+    found_any_arrow = False
+    for ln in lines:
+        if ln.strip().startswith("```"):
+            in_fence = not in_fence
+            continue
+        if not in_fence:
+            continue
+        # normalize arrow glyphs
+        norm = ln.replace("→", "->").replace("──", "-").replace("-", "-")
+        if "->" not in norm:
+            continue
+        chain = EDGE_RE.findall(norm.upper())
+        # only treat as a chain if arrows connect them left-to-right
+        segments = [s for s in re.split(r"->", norm)]
+        seq = []
+        for seg in segments:
+            ids = EDGE_RE.findall(seg.upper())
+            seq.append(ids[-1] if ids else None)
+        for a, b in zip(seq, seq[1:]):
+            if a and b:
+                edges.add((a, b))
+                found_any_arrow = True
+    return edges, found_any_arrow
+
+
+def check(tasks_path):
+    with open(tasks_path, "r", encoding="utf-8") as f:
+        lines = f.read().splitlines()
+    errors, warnings = [], []
+
+    for name in REQUIRED_SECTIONS:
+        if not section_present(lines, name):
+            errors.append(f"missing required section: ## {name}")
+
+    tasks = parse_tasks(lines)
+    if not tasks:
+        warnings.append("no tasks (### T1: ...) parsed - is this file filled in?")
+        return errors, warnings
+
+    # Field presence + granularity smell.
+    for tid, t in tasks.items():
+        if t["tests"] is None:
+            errors.append(f"{tid}: missing `Tests` field")
+        elif t["tests"].lower().startswith("none"):
+            warnings.append(f"{tid}: Tests: none - confirm the Test Coverage Matrix says 'none' for this layer")
+        if t["gate"] is None:
+            errors.append(f"{tid}: missing `Gate` field")
+        files = FILE_HINT_RE.findall(t["where"])
+        if len(set(files)) > 1:
+            warnings.append(f"{tid}: `Where` names multiple files {sorted(set(files))} - granularity smell, consider splitting")
+
+    # Forward-phase dependency.
+    membership = parse_phase_membership(lines)
+    for tid, t in tasks.items():
+        p_here = membership.get(tid)
+        if p_here is None:
+            continue
+        for dep in t["deps"]:
+            p_dep = membership.get(dep)
+            if p_dep is not None and p_dep > p_here:
+                errors.append(f"{tid} (phase {p_here}) depends on {dep} (phase {p_dep}) - dependencies must point backward or within the same phase")
+
+    # Diagram vs definition cross-check (best effort).
+    edges, parsed = parse_diagram_edges(lines)
+    if not parsed:
+        warnings.append("diagram arrows not parsed confidently - diagram/definition cross-check skipped (verify by hand)")
+    else:
+        def intra_phase(a, b):
+            # Parity applies only within a phase. A backward cross-phase dependency
+            # is validated by the forward-phase check above and needs no diagram arrow;
+            # phase diagrams are drawn per phase, so cross-phase edges are out of scope here.
+            pa, pb = membership.get(a), membership.get(b)
+            if pa is None or pb is None:
+                return True  # unknown phase -> keep best-effort parity
+            return pa == pb
+
+        dep_edges = set()
+        for tid, t in tasks.items():
+            for dep in t["deps"]:
+                dep_edges.add((dep, tid))  # arrow points dep -> task
+        only_in_diagram = {(a, b) for (a, b) in (edges - dep_edges) if intra_phase(a, b)}
+        only_in_defs = {(a, b) for (a, b) in (dep_edges - edges) if intra_phase(a, b)}
+        for a, b in sorted(only_in_diagram):
+            if a in tasks and b in tasks:
+                errors.append(f"diagram shows {a} -> {b} but {b} has no matching `Depends on: {a}`")
+        for a, b in sorted(only_in_defs):
+            errors.append(f"{b} declares `Depends on: {a}` but the diagram has no {a} -> {b} arrow")
+
+    return errors, warnings
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_tasks.py", description="Pre-approval checks for a feature tasks.md.")
+    p.add_argument("target", nargs="?", default=None)
+    p.add_argument("--root", default=".")
+    p.add_argument("--strict", action="store_true")
+    args = p.parse_args(argv)
+
+    tasks_path = resolve_tasks(args.target, args.root)
+    if not tasks_path:
+        print("validate_tasks: could not locate a tasks.md. Pass a path or run from the project root.", file=sys.stderr)
+        return 2
+
+    errors, warnings = check(tasks_path)
+    for w in warnings:
+        print(f"  WARN  {w}")
+    for e in errors:
+        print(f"  ERROR {e}")
+    fail = errors or (warnings and args.strict)
+    print(f"\nvalidate_tasks: {len(errors)} error(s), {len(warnings)} warning(s) in {tasks_path}")
+    return 1 if fail else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/framework/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". Focuses on visual design and interaction patterns. Do NOT use for performance audits (use core-web-vitals), SEO (use seo), or comprehensive site audits (use web-quality-audit).
+metadata:
+  author: vercel
+  version: '1.0.0'
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Read the guidelines from `#[[file:references/guideline.md]]`
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Reference
+
+All rules and output format instructions are in:
+
+```
+#[[file:references/guideline.md]]
+```
+
+The guidelines cover:
+
+- Accessibility (ARIA, semantic HTML, keyboard navigation)
+- Focus states and keyboard interaction
+- Forms (autocomplete, validation, labels)
+- Animation (reduced motion, performance)
+- Typography (proper characters, number formatting)
+- Content handling (overflow, empty states)
+- Images (dimensions, lazy loading)
+- Performance (virtualization, DOM reads)
+- Navigation & state (URL sync, deep linking)
+- Touch & interaction (tap delays, safe areas)
+- Dark mode & theming
+- Locale & i18n
+- Hydration safety
+- Common anti-patterns to flag
+
+## Usage
+
+When a user provides a file or pattern argument:
+
+1. Read the guidelines from `references/guideline.md`
+2. Read the specified files
+3. Apply all rules from the guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
+
+## Output Format
+
+Follow the format in the guidelines:
+
+- Group findings by file
+- Use `file:line` format (VS Code clickable)
+- Terse, high signal-to-noise
+- State issue + location
+- Skip explanation unless fix is non-obvious

package/framework/skills/web-design-guidelines/examples.md

@@ -0,0 +1,32 @@
+# Web Design Guidelines Examples
+
+## Review a component for accessibility
+
+User: "Review my dropdown component."
+
+Good agent behavior:
+
+- Read the guidelines from `references/guideline.md` first, then the specified file.
+- Check ARIA usage, keyboard navigation, focus states, and semantic HTML against the rules.
+- Output findings grouped by file in `file:line` format, state the issue and location, and skip explanations unless the fix is non-obvious.
+
+## Audit a page's interaction patterns
+
+User: "Check my checkout page against best practices."
+
+Good agent behavior:
+
+- Apply the rules for forms (labels, validation, autocomplete), touch targets, tap delays, and reduced motion.
+- Flag focus visibility and safe-area issues on mobile.
+- Keep the output terse and high signal-to-noise: issue + `file:line` location.
+- Redirect the user to the right skill when a request is out of scope, such as a performance audit.
+
+## Review without a file specified
+
+User: "Audit my site."
+
+Good agent behavior:
+
+- Ask which files or pattern to review before starting, since the skill needs a target.
+- Once provided, read the files and check them against all rules in the guidelines.
+- Produce the grouped `file:line` findings rather than a prose essay.

package/framework/skills/web-design-guidelines/references/guideline.md

@@ -0,0 +1,174 @@
+# Web Interface Guidelines
+
+Review these files for compliance: $ARGUMENTS
+
+Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+
+### Focus States
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders end with `…` and show example pattern
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`—list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible—respond to user input mid-animation
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `"` `"` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content Handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `min-w-0` to allow text truncation
+- Handle empty states—don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+### Navigation & State
+
+- URL reflects state—filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
+- Destructive actions need confirmation modal or undo window—never immediate
+
+### Touch & Interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- During drag: disable text selection, `inert` on dragged elements
+- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
+
+### Safe Areas & Layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale & i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+
+### Hydration Safety
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover & Interactive States
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Title Case for headings/buttons (Chicago style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+
+## Output Format
+
+Group by file. Use `file:line` format (VS Code clickable). Terse findings.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all → list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." → "…"
+
+## src/Card.tsx
+
+✓ pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.