@appsforgood/next-supabase-kit 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.6
+
+- Added a repo-native UI improvement harness with command-style prompts, deterministic detector checklist, acceptance rubric, portable runtime skill, and focused Antigravity UI commands.
+- Wired UI audit, polish, layout cleanup, responsive cleanup, accessibility, distinctiveness, screenshot critique, and browser QA workflows into roster routing, docs, templates, package validation, and example snapshots.
+
 ## 0.1.5
 
 - Added computed **Agentic Engineering Level** (L3–L6) in Agent Office and setup wizard: iceberg strip, climb checklist, `/api/state` payload, and `POST /api/agentic-level/refresh`.

package/DOGFOOD.md

@@ -34,6 +34,15 @@ Mode: read-only audit; no downstream files were modified.
 - Assistant adapters and upgrade lifecycle still need real activation/dogfood evidence after publication.
 - Reference-led design critique still needs a real UI change dogfood pass with screenshots or equivalent visual evidence.
 
+## 2026-07-02 Publish Verification And Self-Install Snapshot
+
+Date: 2026-07-02
+CLI source: public npm registry (`@appsforgood/next-supabase-kit`, published) plus local `src/` for the self-install.
+Mode: post-publish verification against the live registry, and dogfooding the kit into this repo's own root.
+
+- `node scripts/post-publish-verify.mjs` against the published package passed: registry visibility confirmed, `npx` doctor ok, clean temp `init` installed 23 files, and `audit --json --min-readiness baseline-setup` returned 0 failures (readiness `baseline-setup`).
+- This repo now dogfoods its own kit at the root: `agent-kit init` installed the root docs, `.agent-kit/`, and Cursor rules; project context, council session, and overrides were filled with real evidence; `agent-kit audit --min-readiness best-practice-candidate` passes with 0 warnings and 0 failures.
+
 ## 2026-06-07 Agent Studio Dogfood Snapshot
 
 Date: 2026-06-07

package/README.md

@@ -1,5 +1,11 @@
 # Agent Skills Next/Supabase Kit
 
+[![CI](https://github.com/lukey662/agentsandskills/actions/workflows/ci.yml/badge.svg)](https://github.com/lukey662/agentsandskills/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40appsforgood%2Fnext-supabase-kit)](https://www.npmjs.com/package/@appsforgood/next-supabase-kit)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lukey662/agentsandskills/badge)](https://scorecard.dev/viewer/?uri=github.com/lukey662/agentsandskills)
+[![CodeQL](https://github.com/lukey662/agentsandskills/actions/workflows/codeql.yml/badge.svg)](https://github.com/lukey662/agentsandskills/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 `@appsforgood/next-supabase-kit` installs an agent operating system for Next.js + Supabase projects.
 
 It gives agentic coders a default council roster, reusable skills, handoff rules, model-routing guidance, markdown docs, frontend design gates, Supabase/RLS security checks, upgrade workflows, and audit commands.
@@ -14,7 +20,7 @@ It also includes a local Agent Studio workflow: project context, durable human c
 
 ## Quick Start
 
-Use this in a Next.js + Supabase project after the public package is available on npm:
+Use this in a Next.js + Supabase project:
 
 ```bash
 npx @appsforgood/next-supabase-kit init --stack next-supabase --setup --open
@@ -33,6 +39,34 @@ npx @appsforgood/next-supabase-kit adapter validate antigravity
 
 The installer preserves existing docs. If a file already exists and differs from the template, the new version is written to `.agent-kit/conflicts/` for review.
 
+### See It In Action
+
+```text
+$ agent-kit init --stack next-supabase
+agent-kit installed (stack: next-supabase)
+Created (21)
+  AGENTS.md
+  AGENT_ROSTER.md
+  ASSISTANT_ADAPTERS.md
+  ...
+  .cursor/rules/cursor-agent-kit.mdc
+  .agent-kit/agent-roster.json
+  .agent-kit/model-routing.json
+
+Manifest: .agent-kit/manifest.json
+Next: run agent-kit audit to check readiness.
+
+$ agent-kit audit
+READINESS baseline-setup: Agent kit setup is valid, but project-specific
+evidence still needs to replace starter placeholders.
+SUMMARY pass=60 warn=3 fail=0
+NEXT ACTIONS
+- Run agent-kit onboard or agent-kit init --guided so agents can start
+  with project-specific context.
+```
+
+Every command accepts `--json` for machine-readable output, and mutating commands (`init`, `update`, `add skill`) accept `--dry-run`. A `vhs` tape for regenerating the animated demo lives at `docs/demo.tape`.
+
 For local development of this repo:
 
 ```bash
@@ -63,7 +97,7 @@ Default routing:
 - Planner handles plans, roadmaps, scope, and ambiguous requests first.
 - Lead Architect reviews core changes before implementation.
 - Security Reviewer joins auth, RLS, data mutation, dependency, secret, external-call, and release-risk work.
-- Frontend Design Lead owns content-first design, reference-led critique, distinctiveness benchmarking, product-quality scoring, and visual QA.
+- Frontend Design Lead owns content-first design, reference-led critique, distinctiveness benchmarking, product-quality scoring, UI detector severity review, command-based polish/audit loops, and visual QA.
 - Marketing Copy Lead owns public-facing and conversion-facing copy, positioning, proof, objections, voice, and CTA hierarchy.
 - QA Engineer verifies behavior changes before completion.
 - Documentation Maintainer keeps the living markdown current.
@@ -160,7 +194,7 @@ Agent Kit separates the mechanisms that make AI coding repeatable:
 - Instructions: `AGENTS.md`, assistant adapters, and IDE-specific rule files.
 - Roster: `.agent-kit/agent-roster.json` chooses agents, workflows, and handoffs.
 - Skills: `.agent-kit/skills/` keeps specialist workflows reusable.
-- Runtime commands: Antigravity `commands/*.toml` expose `/setup`, `/audit`, `/plan`, `/handoff`, `/frontend`, `/security`, `/copy`, `/ship`, and `/upgrade` as native adapter entrypoints.
+- Runtime commands: Antigravity `commands/*.toml` expose `/setup`, `/audit`, `/plan`, `/handoff`, `/frontend`, focused UI improvement commands, `/security`, `/copy`, `/ship`, and `/upgrade` as native adapter entrypoints.
 - Portable skills: `runtime-skills/*/SKILL.md` wraps canonical `skills/*.md` files for runtimes that discover skill directories.
 - Model routing: `MODEL_ROUTING.md` and `.agent-kit/model-routing.json` map agents to model profiles.
 - Messaging: `MESSAGING.md` records audience, pain, outcome, proof, objections, voice, and conversion evidence for public-facing copy.
@@ -189,6 +223,8 @@ Significant UI work should prove:
 
 The Frontend Design Lead should reject work that would still look valid for another product after only changing the logo or headline.
 
+Operational UI improvement workflows live in `.agent-kit/prompts/ui-command-index.md` and ship as Antigravity commands: `/ui-audit`, `/ui-polish`, `/layout-cleanup`, `/responsive-cleanup`, `/accessibility-pass`, `/distinctiveness-pass`, `/screenshot-critique`, and `/browser-qa`. Use `.agent-kit/checklists/ui-detectors.md` for deterministic blocker/major/minor findings and `.agent-kit/checklists/ui-acceptance-rubric.md` for pass/fail decisions. High-risk UI work requires desktop and mobile screenshots plus authenticated or permission-state evidence when the surface is not public.
+
 ## Security Bar
 
 The kit treats these as defaults, not optional polish:
@@ -255,7 +291,7 @@ Release expectations:
 - Dependency Review, CodeQL, OpenSSF Scorecard, Dependabot, SBOM validation, and SBOM attestation.
 - Post-publish verification with `npm run publish:verify`.
 
-Public release remains gated until the npm scope/package exists, Trusted Publishing is configured, and post-publish `npx` verification succeeds.
+The package is published to public npm under `@appsforgood/next-supabase-kit`. Every release must pass `npm run release:check` before publish and `npm run publish:verify` after (registry visibility, clean `npx` doctor/init/audit). Post-publish verification was last run 2026-07-02 against the live registry: doctor, init, and `audit --min-readiness baseline-setup` all passed with zero failures.
 
 ## Repository Health
 

package/REPOSITORY_SETTINGS.md

@@ -31,9 +31,9 @@ Create environment `npm-publish` with:
 - Required reviewers enabled.
 - Prevent self-review enabled where available.
 - Deployment branches restricted to `main` and release events.
-- No npm publish token secret for the trusted-publishing flow.
-- Any legacy npm token secrets deleted after Trusted Publishing is confirmed.
-- Optional fallback: a maintainer npm publish token secret on the `npm-publish` environment when trusted publishing returns 404 on PUT.
+- Preferred path: no npm publish token secret once Trusted Publishing is confirmed for this package.
+- Current fallback: a maintainer npm publish token secret on the release workflow so manual publish dispatch can complete until npm Trusted Publishing is configured.
+- Any fallback npm token secrets deleted after Trusted Publishing is confirmed.
 
 The npm trusted publisher must match:
 
@@ -66,6 +66,10 @@ Create labels from `.github/labels.yml`. Required label families:
 - Status: `needs-triage`, `blocked`, `good first issue`, `help wanted`
 - Risk: `risk: security`, `risk: breaking-change`
 
+## GitHub Pages
+
+Enable GitHub Pages with source "Deploy from a branch", branch `main`, folder `/docs`. The minimal docs site lives at `docs/index.md` with the `jekyll-theme-minimal` theme configured in `docs/_config.yml`. Update `docs/index.md` when the CLI surface, readiness levels, or quick-start commands change.
+
 ## Review Cadence
 
 Review these settings before every public release and after any workflow, release, permission, package, or security-policy change.

package/SUPPLY_CHAIN.md

@@ -5,12 +5,12 @@ This package is intended for public npm distribution and downstream project boot
 ## Publish Identity
 
 - Public package: `@appsforgood/next-supabase-kit`.
-- Publish path: GitHub Actions release workflow through npm Trusted Publishing.
-- Authentication: OIDC trusted publisher, not a long-lived npm automation token.
+- Publish path: GitHub Actions release workflow through npm Trusted Publishing when configured, with a token-backed publish fallback for the current npm package setup.
+- Authentication: prefer OIDC trusted publisher; the fallback uses a scoped npm automation token stored as a GitHub Actions secret.
 - Environment: `npm-publish`.
 - Trusted publisher must be scoped to repository `lukey662/agentsandskills`, workflow `release.yml`, and allowed action `npm publish`.
 
-When npm Trusted Publishing is used from a public GitHub repository for a public package, npm generates provenance attestations automatically. The release workflow keeps `id-token: write` for this reason and does not set `NODE_AUTH_TOKEN` for publishing.
+When npm Trusted Publishing is used from a public GitHub repository for a public package, npm generates provenance attestations automatically. Until that package-level publisher is confirmed in npm, the release workflow publishes with the configured secret and `--provenance` so npm still receives GitHub Actions provenance.
 
 The release workflow also creates a deterministic package tarball, generates a CycloneDX SBOM from `package-lock.json`, uploads the tarball, SBOM, and pack metadata as release evidence, and attests the SBOM against the exact tarball path that is published to npm.
 
@@ -47,9 +47,9 @@ The release workflow and `npm run publish:verify` both use `scripts/post-publish
 
 ## Maintainer Rules
 
-- Do not use bypass-2FA npm publish tokens for automation.
+- Do not use bypass-2FA npm publish tokens for automation; any fallback token must be scoped for package publishing and stored only as a GitHub Actions secret.
 - Do not publish from unreviewed branches or untrusted workflow changes.
 - Treat workflow edits as release-risk changes requiring security and maintainer review.
-- Rotate and delete legacy publish secrets after Trusted Publishing is confirmed.
+- Rotate and delete fallback publish secrets after Trusted Publishing is confirmed.
 - Keep package contents free of secrets, private downstream data, and copied third-party source.
 - Keep SBOM generation and attestation in the shared release path; do not publish an unattested tarball when the workflow is available.

package/UPGRADE.md

@@ -78,4 +78,5 @@ Keep rollback evidence next to the upgrade:
 | Date | From | To | Scope | Evidence | Owner |
 | --- | --- | --- | --- | --- | --- |
 | 2026-06-14 | TypeScript 5 / Node 22 types | TypeScript 6 / Node 25 types | Dev dependency update for package validation and CI parity | `npm run typecheck`, `npm test`, `npm audit --audit-level=moderate` | Maintainers |
-| TBD | TBD | TBD | TBD | TBD | TBD |
+| 2026-06 | 0.1.0 | 0.1.1 | Package rename to `@appsforgood/next-supabase-kit`, harness readiness gates, adapter install on init, publish prep | `CHANGELOG.md` 0.1.1 entry, `npm run release:check` green, commit `37e1a0f` | lukey662 |
+| 2026-07-02 | none | 0.1.1 (self-install) | Dogfooded the kit into this repo's own root: `agent-kit init` installed root docs, `.agent-kit/`, and confirmed the Cursor rules' referenced files exist | `.agent-kit/manifest.json`, `agent-kit audit` zero failures, `COUNCIL.md` 2026-07-02 session | lukey662 |

package/antigravity/commands/accessibility-pass.toml

@@ -0,0 +1,16 @@
+name = "accessibility-pass"
+description = "Run a WCAG 2.1 AA-oriented UI pass for semantics, keyboard flow, focus, labels, contrast, and motion."
+
+prompt = """
+Run the accessibility pass workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/skills/accessibility-wcag.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Check semantics, headings, landmarks, forms, labels, tables, buttons, and ARIA use.
+2. Check keyboard navigation, visible focus, tab order, escape/close behavior, and skip path when applicable.
+3. Check contrast, reduced motion, error association, touch targets, and status announcements.
+4. Keep accessibility checks separate from visual-only approval.
+
+Required outputs: accessibility findings by severity, fixes made or proposed, skipped checks, test evidence, remaining risks.
+"""

package/antigravity/commands/browser-qa.toml

@@ -0,0 +1,18 @@
+name = "browser-qa"
+description = "Run a live browser QA loop with desktop, mobile, state, and authenticated screen evidence."
+
+prompt = """
+Run the live browser QA workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/prompts/screenshot-review.md, .agent-kit/prompts/visual-qa-plan.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Start or identify the dev/preview server and target routes.
+2. Open the target with required auth, role, tenant, and data state.
+3. Capture desktop and mobile screenshots.
+4. Run detector, screenshot critique, accessibility pass, and responsive cleanup.
+5. Apply scoped fixes and repeat until no blockers remain and major findings are fixed or documented.
+6. Record evidence with agent-kit session output when Agent Studio is in use.
+
+Required outputs: route, auth state, commands run, screenshots, detector results, fixes, final verdict.
+"""

package/antigravity/commands/distinctiveness-pass.toml

@@ -0,0 +1,16 @@
+name = "distinctiveness-pass"
+description = "Check that UI is product-specific, source-safe, and not generic SaaS or AI-site styling."
+
+prompt = """
+Run the visual distinctiveness pass workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/skills/frontend-distinctiveness-benchmark.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Compare the first viewport to product category, audience, workflow, and content fingerprint.
+2. Confirm references were translated into lessons without copying source layouts, copy, assets, or brand marks.
+3. Identify fake metrics, vague claims, abstract filler, interchangeable card stacks, and generic visual tropes.
+4. Re-score distinctiveness and product quality where significant UI work is involved.
+
+Required outputs: product-specific evidence, generic-risk findings, source-safety notes, required changes, final distinctiveness verdict.
+"""

package/antigravity/commands/frontend.toml

@@ -4,14 +4,15 @@ description = "Route frontend work through content-first design, accessibility,
 prompt = """
 Run the frontend-change workflow.
 
-Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/design-briefs/, .agent-kit/prompts/screenshot-review.md, and .agent-kit/skills/frontend-design-system.md.
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, MESSAGING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/design-briefs/, .agent-kit/prompts/screenshot-review.md, .agent-kit/prompts/ui-command-index.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/skills/frontend-design-system.md, and .agent-kit/skills/ui-improvement-harness.md.
 
 Workflow:
 1. Start with Frontend Design Lead before implementation.
 2. Confirm brand/content intake, user needs, real content, creative direction, references, anti-references, and source-safety notes.
 3. Require distinctiveness benchmark and product-quality scorecard for significant UI.
-4. Preserve WCAG 2.1 AA, keyboard flow, responsive states, and loading/error/empty/success states.
-5. Record visual QA and accessibility evidence with `agent-kit session output`.
+4. Apply the UI improvement command index when auditing, polishing, cleaning layout, reviewing screenshots, or running browser QA.
+5. Preserve WCAG 2.1 AA, keyboard flow, responsive states, and loading/error/empty/success states.
+6. Record UI detector findings, visual QA, and accessibility evidence with `agent-kit session output`.
 
-Required outputs: design direction, reference evidence, product-specific UI rationale, state coverage, accessibility checks, desktop/mobile visual QA.
+Required outputs: design direction, reference evidence, product-specific UI rationale, UI detector findings, state coverage, accessibility checks, desktop/mobile visual QA, authenticated screen evidence when applicable.
 """

package/antigravity/commands/layout-cleanup.toml

@@ -0,0 +1,16 @@
+name = "layout-cleanup"
+description = "Clean crowded layouts, weak hierarchy, card nesting, overflow, and inconsistent spacing."
+
+prompt = """
+Run the layout cleanup workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Identify primary task, secondary tasks, content hierarchy, and target viewport range.
+2. Remove unnecessary nesting, repeated surfaces, card-within-card patterns, arbitrary dividers, and workflow-obscuring decoration.
+3. Normalize spacing, grouping, alignment, heading scale, and responsive containers.
+4. Verify text fit, truncation, overlap, and horizontal overflow on desktop and mobile.
+
+Required outputs: layout findings, cleanup actions, preserved workflow, desktop/mobile evidence, remaining layout risks.
+"""

package/antigravity/commands/responsive-cleanup.toml

@@ -0,0 +1,16 @@
+name = "responsive-cleanup"
+description = "Verify and repair mobile and responsive UI behavior with required desktop and mobile evidence."
+
+prompt = """
+Run the responsive cleanup workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Review mobile width, desktop width, and project-specific breakpoint assumptions.
+2. Verify tap targets, text fit, navigation, primary action visibility, sticky UI, scroll behavior, and viewport-safe spacing.
+3. Verify relevant loading, empty, error, disabled, success, permission, and focus states on mobile.
+4. Capture or request desktop and mobile screenshots before acceptance.
+
+Required outputs: viewports checked, responsive findings, fixes made or proposed, screenshots, remaining risks.
+"""

package/antigravity/commands/screenshot-critique.toml

@@ -0,0 +1,16 @@
+name = "screenshot-critique"
+description = "Critique desktop, mobile, state, and authenticated screenshots against design and detector rules."
+
+prompt = """
+Run the screenshot critique workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, .agent-kit/prompts/screenshot-review.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Name each screenshot, viewport, route, auth state, data state, and UI state.
+2. Run screenshot review, detector checklist, and accessibility risk scan.
+3. Compare against DESIGN.md, STYLE_GUIDE.md, and selected creative direction.
+4. Return concrete fixes and missing screenshot evidence.
+
+Required outputs: screenshot inventory, blockers, high-value fixes, accepted areas, missing screenshots, release verdict.
+"""

package/antigravity/commands/ui-audit.toml

@@ -0,0 +1,17 @@
+name = "ui-audit"
+description = "Run a deterministic UI audit with severity-based detector findings and release evidence."
+
+prompt = """
+Run the UI audit workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Identify target route, component, workflow, auth state, data state, and risk tier.
+2. Load product/design context and relevant design brief.
+3. Review desktop and mobile evidence, or state which evidence must still be captured.
+4. Run the UI detector checklist and classify blockers, majors, minors, passes, and not-applicable items.
+5. Return required fixes, accepted exceptions, preserved capabilities, and pass/fail verdict.
+
+Required outputs: target surface, risk tier, detector findings by severity, missing evidence, release verdict.
+"""

package/antigravity/commands/ui-polish.toml

@@ -0,0 +1,17 @@
+name = "ui-polish"
+description = "Improve UI hierarchy, spacing, state feedback, and visual finish through detector-guided polish."
+
+prompt = """
+Run the UI polish workflow.
+
+Canonical sources: DESIGN.md, STYLE_GUIDE.md, TESTING.md, QUALITY_GATES.md, .agent-kit/agent-roster.json, .agent-kit/skills/ui-improvement-harness.md, .agent-kit/checklists/ui-detectors.md, .agent-kit/checklists/ui-acceptance-rubric.md, and .agent-kit/prompts/ui-command-index.md.
+
+Workflow:
+1. Start from detector findings, screenshots, or a named target surface.
+2. Preserve product behavior, auth boundaries, copy claims, data contracts, and existing component patterns.
+3. Improve hierarchy, spacing, density, alignment, component states, and interaction feedback.
+4. Remove decorative clutter and generic SaaS or AI-site defaults.
+5. Re-run detector and screenshot critique after the scoped polish pass.
+
+Required outputs: polish goals, changes made or proposed, detector deltas, screenshot evidence, residual risks.
+"""

package/antigravity/plugin.json

@@ -21,6 +21,14 @@
     { "name": "plan", "path": "commands/plan.toml" },
     { "name": "handoff", "path": "commands/handoff.toml" },
     { "name": "frontend", "path": "commands/frontend.toml" },
+    { "name": "ui-audit", "path": "commands/ui-audit.toml" },
+    { "name": "ui-polish", "path": "commands/ui-polish.toml" },
+    { "name": "layout-cleanup", "path": "commands/layout-cleanup.toml" },
+    { "name": "responsive-cleanup", "path": "commands/responsive-cleanup.toml" },
+    { "name": "accessibility-pass", "path": "commands/accessibility-pass.toml" },
+    { "name": "distinctiveness-pass", "path": "commands/distinctiveness-pass.toml" },
+    { "name": "screenshot-critique", "path": "commands/screenshot-critique.toml" },
+    { "name": "browser-qa", "path": "commands/browser-qa.toml" },
     { "name": "security", "path": "commands/security.toml" },
     { "name": "copy", "path": "commands/copy.toml" },
     { "name": "ship", "path": "commands/ship.toml" },
@@ -38,6 +46,7 @@
     { "name": "frontend-distinctiveness-benchmark", "path": "../runtime-skills/frontend-distinctiveness-benchmark/SKILL.md" },
     { "name": "frontend-product-quality-rubric", "path": "../runtime-skills/frontend-product-quality-rubric/SKILL.md" },
     { "name": "landing-page-copy", "path": "../runtime-skills/landing-page-copy/SKILL.md" },
+    { "name": "ui-improvement-harness", "path": "../runtime-skills/ui-improvement-harness/SKILL.md" },
     { "name": "nextjs-app-router", "path": "../runtime-skills/nextjs-app-router/SKILL.md" },
     { "name": "onboarding-empty-state-copy", "path": "../runtime-skills/onboarding-empty-state-copy/SKILL.md" },
     { "name": "owasp-security-review", "path": "../runtime-skills/owasp-security-review/SKILL.md" },

package/checklists/ui-acceptance-rubric.md

@@ -0,0 +1,58 @@
+# UI Acceptance Rubric
+
+Use this rubric after the UI detector checklist, screenshot critique, accessibility pass, and browser QA loop.
+
+## Pass/Fail
+
+| Verdict | Criteria |
+| --- | --- |
+| fail | Any blocker remains, required screenshot evidence is missing, or authenticated screens were not reviewed when auth is required |
+| conditional | No blockers remain, but major findings need documented owner, rationale, or follow-up before high-risk release |
+| pass | No blockers remain, major findings are fixed or explicitly accepted, and evidence covers viewports, states, and auth needs |
+| strong | Pass criteria plus clear product specificity, accessible keyboard flow, responsive resilience, and state coverage for the workflow |
+
+## Required Evidence
+
+- Target surface: route, component, flow, or screenshot set.
+- Product context source: `DESIGN.md`, `STYLE_GUIDE.md`, design brief, or documented override.
+- Viewports: desktop and mobile dimensions.
+- Auth state: public, signed-in, role, tenant, permission, or explicit not-applicable.
+- Data state: realistic, empty, loading, error, or fixture notes.
+- Screenshots: first viewport, primary workflow, mobile, and highest-risk state.
+- Checks: detector checklist, accessibility pass, screenshot critique, and visual QA tier.
+
+## Release Blocking Rules
+
+- Block release for any blocker detector.
+- Block high-risk UI release when desktop or mobile screenshot evidence is missing.
+- Block authenticated workflow release when no signed-in or permission-state evidence exists.
+- Block acceptance when loading, empty, error, disabled, success, permission, or focus states are relevant but omitted without rationale.
+- Block best-practice claims when product specificity, accessibility, or source safety is weak.
+
+## Risk Tiers
+
+| Tier | Use When | Minimum Evidence |
+| --- | --- | --- |
+| low | Copy-only or isolated cosmetic change to a stable component | Targeted screenshot or component evidence plus detector review |
+| medium | Layout, responsive, or state changes on a user-facing surface | Desktop and mobile screenshots plus relevant state evidence |
+| high | Authenticated workflow, checkout, data mutation, admin, onboarding, or shared component system | Desktop, mobile, auth/permission, error/empty/loading, keyboard/focus, and smoke evidence |
+
+## Exception Rules
+
+Exceptions are allowed only when:
+
+- The finding is not a blocker.
+- The rationale names product or technical constraints.
+- The owner and follow-up path are documented.
+- The exception does not weaken auth, accessibility, data integrity, or source safety.
+
+## Output Format
+
+Return:
+
+1. Verdict: fail, conditional, pass, or strong.
+2. Risk tier and target surface.
+3. Evidence reviewed.
+4. Blockers, majors, minors, and accepted exceptions.
+5. Required fixes before release.
+6. Follow-up work after release.

package/checklists/ui-detectors.md

@@ -0,0 +1,75 @@
+# UI Detector Checklist
+
+Use this deterministic checklist for UI audit, polish, layout cleanup, responsive cleanup, screenshot critique, and browser QA. Mark each item as `blocker`, `major`, `minor`, `pass`, or `not-applicable`.
+
+## Severity
+
+| Severity | Meaning |
+| --- | --- |
+| blocker | Prevents release because a user cannot complete the workflow, the UI is inaccessible, or required evidence is missing |
+| major | Degrades comprehension, trust, responsiveness, or state handling enough that high-risk UI should not ship without a fix or accepted exception |
+| minor | Polish issue that should be fixed when nearby but does not block normal release |
+| pass | Checked and acceptable for the target surface |
+| not-applicable | The detector does not apply to this surface or state |
+
+## Layout And Hierarchy
+
+| Detector | Blocker Signal | Major Signal |
+| --- | --- | --- |
+| Crowded layout | Primary workflow cannot be identified or completed | Too many competing sections, controls, badges, or panels |
+| Weak hierarchy | Primary action or current state is hidden | Headings, labels, and actions do not establish clear priority |
+| Inconsistent spacing | Spacing causes overlap or unusable controls | Density, gaps, padding, or alignment shift without system logic |
+| Card-within-card | Nested containers obscure the workflow or trap scroll | Decorative nested panels add visual noise without information value |
+| Poor grouping | Related controls are separated or unrelated items are grouped | Scan path is unclear or section boundaries are arbitrary |
+
+## Responsive And Mobile
+
+| Detector | Blocker Signal | Major Signal |
+| --- | --- | --- |
+| Poor tap targets | Critical control is too small, overlapped, or unreachable | Repeated controls feel cramped or hard to tap |
+| Truncation or overflow | Text, inputs, tables, or controls clip essential content | Labels wrap badly, overflow horizontally, or push layout off-screen |
+| Mobile hierarchy | Mobile first screen hides the primary task or action | Desktop order collapses into a confusing mobile sequence |
+| Sticky or fixed UI | Fixed header/footer covers content or controls | Sticky UI consumes too much viewport or causes awkward scrolling |
+| Orientation and narrow widths | Page breaks at common mobile widths | Responsive behavior is untested below tablet width |
+
+## States And Feedback
+
+| Detector | Blocker Signal | Major Signal |
+| --- | --- | --- |
+| Missing loading state | User can trigger duplicate or unsafe action while waiting | Loading state exists but does not preserve layout or context |
+| Missing empty state | Empty data leaves a dead end | Empty state lacks next action or domain-specific guidance |
+| Missing error state | Failure is silent or blocks recovery | Error is vague, unactionable, or visually disconnected |
+| Missing disabled state | Disabled action looks enabled or loses explanation | Disabled state lacks affordance, label, or contrast |
+| Missing success feedback | User cannot tell whether action completed | Success message is too subtle, transient, or ambiguous |
+| Missing permission state | Protected UI leaks actions or fails without explanation | Permission limitation is not clear to the affected role |
+| Weak interaction feedback | Focus, selected, hover, pressed, or active state is absent on critical controls | State feedback is inconsistent across similar controls |
+
+## Accessibility
+
+| Detector | Blocker Signal | Major Signal |
+| --- | --- | --- |
+| Keyboard path | Critical workflow cannot be completed by keyboard | Tab order is confusing or focus moves unexpectedly |
+| Focus visibility | Focus indicator is absent on interactive controls | Focus is low contrast or inconsistent |
+| Semantic structure | Heading, landmark, form, table, or button semantics block assistive tech use | Semantics are mostly present but incomplete |
+| Labels and errors | Inputs or controls lack accessible names or error association | Labels exist but are vague, duplicate, or visually disconnected |
+| Contrast | Text or critical controls fail WCAG 2.1 AA contrast | Secondary text or state colors are borderline |
+| Motion | Motion prevents comprehension or ignores reduced-motion need | Motion distracts from workflow or feels inconsistent |
+
+## Distinctiveness And Source Safety
+
+| Detector | Blocker Signal | Major Signal |
+| --- | --- | --- |
+| Generic SaaS styling | First screen could fit another product by changing logo and headline | Visual direction relies on common cards, gradients, fake dashboards, or vague claims |
+| Missing content fingerprint | UI hides missing product decisions behind placeholders | Real nouns, records, actions, or edge cases are too sparse |
+| Weak visual identity | No product-specific density, typography, imagery, or interaction point of view | Direction is coherent but category-generic |
+| Unsafe reference use | Copy, assets, layout signature, or brand identity appear copied | References are cited without lessons and anti-copy notes |
+| Fake or unsupported proof | Fake metrics or claims imply unavailable capability | Proof exists but is not tied to actual product behavior |
+
+## Evidence Requirements
+
+- Desktop screenshot reviewed.
+- Mobile screenshot reviewed.
+- Highest-risk state screenshot reviewed.
+- Authenticated or permission-state screenshot reviewed when applicable.
+- Browser route, viewport, data fixture, and user role named.
+- Detector exceptions documented with rationale and owner.