@appsforgood/next-supabase-kit 0.1.0

package/research/scan-config.json

@@ -0,0 +1,261 @@
+{
+  "maxRepos": 100,
+  "minStars": 100,
+  "activeSince": "2024-12-01",
+  "excludeRepos": [
+    "appwrite/appwrite"
+  ],
+  "seedRepos": [
+    {
+      "fullName": "dubinc/dub",
+      "category": "production-saas"
+    },
+    {
+      "fullName": "documenso/documenso",
+      "category": "production-saas"
+    },
+    {
+      "fullName": "formbricks/formbricks",
+      "category": "production-saas"
+    },
+    {
+      "fullName": "triggerdotdev/trigger.dev",
+      "category": "production-saas"
+    },
+    {
+      "fullName": "unkeyed/unkey",
+      "category": "security-quality"
+    },
+    {
+      "fullName": "better-auth/better-auth",
+      "category": "security-quality"
+    },
+    {
+      "fullName": "nextauthjs/next-auth",
+      "category": "security-quality"
+    },
+    {
+      "fullName": "tailwindlabs/headlessui",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "shadcn-ui/ui",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "google-labs-code/design.md",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "google-labs-code/stitch-sdk",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "storybookjs/design-system",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "primer/react",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "radix-ui/primitives",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "carbon-design-system/carbon",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "Shopify/polaris",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "uswds/uswds",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "Shopify/polaris-tokens",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "alphagov/govuk-design-system",
+      "category": "design-systems"
+    },
+    {
+      "fullName": "t3-oss/create-t3-app",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "storybookjs/storybook",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "storybookjs/test-runner",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "chromaui/chromatic-cli",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "argos-ci/argos",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "oblador/loki",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "openai/openai-agents-js",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "openai/openai-agents-python",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "langchain-ai/langgraphjs",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "langchain-ai/langgraph-supervisor-py",
+      "category": "testing-docs-agents"
+    },
+    {
+      "fullName": "github/docs",
+      "category": "repo-health-maintainers"
+    },
+    {
+      "fullName": "github/codeql-action",
+      "category": "repo-health-maintainers"
+    },
+    {
+      "fullName": "dependabot/dependabot-core",
+      "category": "repo-health-maintainers"
+    },
+    {
+      "fullName": "ossf/scorecard",
+      "category": "repo-health-maintainers"
+    },
+    {
+      "fullName": "actions/dependency-review-action",
+      "category": "supply-chain-security"
+    },
+    {
+      "fullName": "ossf/scorecard-action",
+      "category": "supply-chain-security"
+    },
+    {
+      "fullName": "npm/provenance",
+      "category": "supply-chain-security"
+    },
+    {
+      "fullName": "slsa-framework/slsa-github-generator",
+      "category": "supply-chain-security"
+    }
+  ],
+  "categories": [
+    {
+      "name": "official-nextjs",
+      "targetCount": 15,
+      "queries": [
+        "org:vercel nextjs",
+        "org:vercel app-router",
+        "org:nextjs"
+      ]
+    },
+    {
+      "name": "supabase-nextjs",
+      "targetCount": 15,
+      "queries": [
+        "supabase nextjs language:TypeScript",
+        "\"createServerClient\" supabase language:TypeScript",
+        "\"row level security\" supabase nextjs",
+        "\"supabase\" \"app/\" \"middleware.ts\" language:TypeScript",
+        "\"supabase\" \"rls\" language:TypeScript"
+      ]
+    },
+    {
+      "name": "production-saas",
+      "targetCount": 20,
+      "queries": [
+        "nextjs saas language:TypeScript",
+        "nextjs dashboard language:TypeScript",
+        "app router saas language:TypeScript",
+        "open source saas starter nextjs language:TypeScript",
+        "nextjs admin dashboard language:TypeScript"
+      ]
+    },
+    {
+      "name": "design-systems",
+      "targetCount": 15,
+      "queries": [
+        "react design system language:TypeScript",
+        "component library react accessibility language:TypeScript",
+        "radix tailwind components language:TypeScript",
+        "shadcn components language:TypeScript",
+        "\"DESIGN.md\" \"design system\" language:Markdown",
+        "\"creative direction\" \"design tokens\" language:Markdown",
+        "\"design critique\" \"reference set\" language:Markdown",
+        "\"anti-reference\" \"creative direction\" language:Markdown",
+        "\"product quality\" \"scorecard\" \"frontend\" language:Markdown",
+        "\"user task\" \"content\" \"accessibility\" \"design system\" language:Markdown"
+      ]
+    },
+    {
+      "name": "security-quality",
+      "targetCount": 15,
+      "queries": [
+        "nextjs security language:TypeScript",
+        "codeql typescript nextjs",
+        "zod route handlers nextjs",
+        "auth middleware nextjs security language:TypeScript",
+        "csrf rate limit nextjs language:TypeScript"
+      ]
+    },
+    {
+      "name": "testing-docs-agents",
+      "targetCount": 20,
+      "queries": [
+        "playwright nextjs language:TypeScript",
+        "\"toHaveScreenshot\" playwright language:TypeScript",
+        "\"visual regression\" storybook language:TypeScript",
+        "chromatic storybook visual testing language:TypeScript",
+        "argos visual testing playwright language:TypeScript",
+        "vitest playwright nextjs language:TypeScript",
+        "contributing security testing nextjs language:TypeScript",
+        "AGENTS.md language:TypeScript",
+        "CLAUDE.md nextjs",
+        "\"agent handoff\" \"tracing\" language:TypeScript",
+        "\"json schema\" \"agents\" language:TypeScript",
+        "\"AGENTS.md\" \"handoff\" language:Markdown"
+      ]
+    },
+    {
+      "name": "repo-health-maintainers",
+      "targetCount": 10,
+      "queries": [
+        "\".github/ISSUE_TEMPLATE\" \"pull_request_template\" language:Markdown",
+        "\"dependabot.yml\" \"CODEOWNERS\" language:Markdown",
+        "\"CodeQL\" \"dependabot\" \"PULL_REQUEST_TEMPLATE\" language:Markdown",
+        "\"SECURITY.md\" \"SUPPORT.md\" \"CODE_OF_CONDUCT.md\" language:Markdown",
+        "\"research\" \"CONTRIBUTING.md\" \"security advisory\" language:Markdown",
+        "\"branch protection\" \"required status checks\" \"CODEOWNERS\" language:Markdown",
+        "\"private vulnerability reporting\" \"security advisories\" language:Markdown",
+        "\"labels.yml\" \"labeler.yml\" \".github\" language:YAML"
+      ]
+    },
+    {
+      "name": "supply-chain-security",
+      "targetCount": 10,
+      "queries": [
+        "\"npm publish\" \"id-token: write\" \"provenance\" language:YAML",
+        "\"trusted publishing\" \"npm publish\" \"GitHub Actions\" language:Markdown",
+        "\"dependency-review-action\" \"fail-on-severity\" language:YAML",
+        "\"ossf/scorecard-action\" \"publish_results\" language:YAML",
+        "\"OpenSSF Scorecard\" \"CodeQL\" \"Dependabot\" language:Markdown"
+      ]
+    }
+  ]
+}

package/research/scan-plan.md

@@ -0,0 +1,24 @@
+# 100 Repo Research Plan
+
+## Objective
+
+Discover repeatable, evidence-backed best practices for Next.js + Supabase project setup, then promote only durable patterns into this package.
+
+## Method
+
+1. Discover candidates through GitHub API queries.
+2. Filter for active, non-archived repositories.
+3. Shallow clone selected repos.
+4. Score architecture, security, Supabase/Auth/RLS, frontend design, accessibility, testing, docs, CI, and agent readiness.
+5. Write one finding per repo.
+6. Summarize repeated patterns.
+7. Update templates only when a pattern is repeated and defensible.
+
+## Do Not Copy
+
+- Source code
+- Proprietary assets
+- Project-specific copy
+- Security-sensitive implementation details
+
+Extract patterns and rationale only.

package/research/summaries/.gitkeep

@@ -0,0 +1 @@
+

package/research/summaries/agent-workflow-patterns.md

@@ -0,0 +1,37 @@
+# Agent Workflow And Handoff Trace Patterns
+
+Generated from a focused follow-up review of multi-agent workflow systems and configuration-validation practices.
+
+## Why This Pass Was Needed
+
+The kit had a default roster and audit checks, but mature agent systems also expose schemas, structured handoffs, guardrails, and traces. Without those, council routing can become prose-only and hard to verify after work is complete.
+
+## Focused Sources Reviewed
+
+- `openai/openai-agents-js` and OpenAI Agents SDK docs: handoffs expose schemas, parse handoff inputs locally, and tracing records what happened during agent runs.
+- `openai/openai-agents-python`: lightweight multi-agent framework with agents, tools, guardrails, handoffs, and tracing.
+- `langchain-ai/langgraphjs`: graph-based orchestration for resilient agent workflows and role-specific agents.
+- `langchain-ai/langgraph-supervisor-py`: supervisor pattern and explicit handoff tooling for routing between specialist agents.
+- JSON Schema / SchemaStore-style config validation patterns: machine-readable schemas help editors, CI, and audit tools detect configuration drift.
+
+## Repeated Patterns To Adopt
+
+- Treat the roster as a contract, not just documentation.
+- Ship schemas beside machine-readable config.
+- Keep handoffs explicit: owner, decision, risk, next owner, and evidence.
+- Record required outputs and whether each is missing, partial, complete, or not applicable.
+- Keep human-readable notes and machine-readable traces compatible.
+- Validate routing drift in audit so downstream projects cannot silently bypass core roles.
+
+## Promoted Updates
+
+- Add `schemas/agent-roster.schema.json`.
+- Add `schemas/council-session.schema.json`.
+- Add `COUNCIL.md` as the human-readable council evidence log.
+- Add Agent Handoff Tracing skill.
+- Add agent council checklist.
+- Add council-session review prompt.
+- Add schema folder to installed assets and public package contents.
+- Add audit coverage for schema presence and council evidence guidance.
+
+Do not tie the kit to a single runtime agent framework. The package should stay provider-neutral while adopting broadly useful schema, handoff, guardrail, and trace concepts.

package/research/summaries/creative-design-patterns.md

@@ -0,0 +1,38 @@
+# Creative Design And Agent-Readable UI Patterns
+
+Generated from a focused second-pass review after the initial 100-repo scan showed that frontend scoring over-weighted reusable components, tokens, and states.
+
+## Why This Pass Was Needed
+
+The first scan correctly promoted design tokens, component states, accessibility, screenshot review, and anti-generic UI rules. It did not fully enforce creative discovery: audience, content inventory, brand direction, visual identity, category references, and multiple design directions before implementation.
+
+## Focused Sources Reviewed
+
+- `google-labs-code/design.md`: first-class design identity document for coding agents, with machine-readable tokens and human-readable rationale.
+- `google-labs-code/stitch-sdk`: design-generation workflow with project design systems, generated screens, screenshots, and variants.
+- `storybookjs/design-system`: open design system repository with shared components, Storybook docs, packaging, CI, and visual regression testing.
+- `storybookjs/storybook`: component workshop pattern for building, documenting, and testing UI states in isolation.
+- `primer/react`: product design-system implementation with contributor/testing expectations.
+- `Shopify/polaris-react` and `Shopify/polaris-tokens`: design-system and token packaging patterns for product-specific admin UI.
+- `govuk-design-system` and GOV.UK service/content guidance: user-need-first service design and content that maps to real user tasks.
+
+## Repeated Patterns To Adopt
+
+- Keep a persistent design-identity document beside agent instructions, not only a style guide.
+- Treat tokens as normative values and prose as usage rationale.
+- Require content and user needs before visual styling.
+- Generate or compare multiple creative directions before implementation.
+- Keep screenshots or visual states as acceptance evidence, not optional polish.
+- Prefer product/category-specific briefs over generic SaaS templates.
+- Make missing real content or assets explicit instead of masking gaps with generic placeholders.
+
+## Promoted Updates
+
+- Add `DESIGN.md` as an installed root document.
+- Add a content-first design skill.
+- Add brand/content intake and creative-direction prompts.
+- Add brand/content checklist.
+- Expand design briefs for ecommerce, portfolio/venue, education/course, community/social, and AI workflow products.
+- Require frontend audit coverage for content, brand, creative direction, and screenshot evidence.
+
+Do not copy source code, design files, or proprietary brand systems from reviewed repositories. Adopt only generalized practices with clear rationale.

package/research/summaries/design-critique-patterns.md

@@ -0,0 +1,34 @@
+# Reference-Led Design Critique Patterns
+
+Generated from a follow-up design-quality review after the kit already had content-first design, design adapters, and visual QA.
+
+## Why This Pass Was Needed
+
+The existing frontend guidance required brand/content intake, creative-direction options, design tokens, component states, screenshot review, and visual QA. That reduced generic AI-site defaults, but it still allowed a weak design to pass if it had enough checklist artifacts. A best-practice frontend setup also needs a critique loop that compares the work to relevant references, names anti-references, and records why the result is distinct for the product.
+
+## Focused Sources Reviewed
+
+- `shadcn-ui/ui`: registry-oriented component distribution and reusable UI skill guidance.
+- `primer/design` and Primer accessibility guidance: design-system guidelines, inclusive design, product-context review, and reusable pattern discipline.
+- `radix-ui/primitives`: accessible low-level primitives that separate behavior foundations from project-specific styling.
+- Carbon Design System guidance: accessibility status, component guidance, and standards-backed review expectations.
+- Storybook documentation: component state, interaction, accessibility, and visual testing workflows.
+
+## Repeated Patterns To Adopt
+
+- Separate reusable primitives from product-specific visual direction.
+- Use references to learn hierarchy, density, state treatment, and interaction patterns without copying source designs.
+- Record anti-references so agents know which category tropes and AI-generated defaults to avoid.
+- Treat accessibility and component-state behavior as foundations, not as visual differentiation by themselves.
+- Use screenshots, stories, or visual tests to make critique evidence reviewable after implementation.
+- Require a written verdict before accepting significant UI work.
+
+## Promoted Updates
+
+- Add Reference-Led Design Critique skill.
+- Add design-critique gate prompt and checklist.
+- Add reference set, anti-reference, source-safety, distinctiveness, and critique verdict fields to `DESIGN.md`.
+- Wire the Frontend Design Lead and frontend-change workflow to require reference-set evidence and a design critique verdict.
+- Add audit warnings when `DESIGN.md` lacks the critique gate.
+
+Do not copy third-party source code, design files, protected visual identity, brand marks, or proprietary copy from reviewed repositories. Adopt generalized practices only.

package/research/summaries/docs-and-agent-patterns.md

@@ -0,0 +1,64 @@
+# Docs And Agent Patterns
+
+Generated from 31 relevant repository findings.
+
+## Focus Areas
+- documentation
+- agentReadiness
+
+## Aggregate Evidence
+- Average normalized focus score: 0.42
+- Repositories considered: 31
+
+## Strongest Repositories For This Topic
+- sno-ai/mda (testing-docs-agents) - focus score 9, total 19/45
+- thedaviddias/souls-directory (testing-docs-agents) - focus score 8, total 29/45
+- vercel/next.js (official-nextjs) - focus score 7, total 30/45
+- vercel/ai (official-nextjs) - focus score 7, total 29/45
+- microsoft/skills (testing-docs-agents) - focus score 7, total 26/45
+- Piebald-AI/tweakcc (testing-docs-agents) - focus score 7, total 20/45
+- vercel/next-forge (official-nextjs) - focus score 6, total 23/45
+- wasp-lang/open-saas (testing-docs-agents) - focus score 6, total 21/45
+- AndreaPontrandolfo/sheriff (testing-docs-agents) - focus score 6, total 21/45
+- MrLesk/Backlog.md (testing-docs-agents) - focus score 6, total 20/45
+- brocoders/extensive-react-boilerplate (testing-docs-agents) - focus score 6, total 19/45
+- vercel/examples (official-nextjs) - focus score 5, total 26/45
+
+## Repeated Strengths
+- Test setup includes meaningful automated and browser-level coverage. (12)
+- Documentation is strong enough for external contributors or agents to onboard. (9)
+- Frontend implementation shows reusable components, states, and design-system signals. (9)
+- Security posture is explicit through docs, validation, CI, or review tooling. (6)
+
+## Repeated Gaps
+- Supabase RLS/Auth practices are not clearly discoverable. (31)
+- Accessibility signals are weak or absent. (23)
+- Agent handoff and AI-workflow instructions are not mature. (20)
+- Security expectations are implicit or incomplete. (19)
+
+## Source Findings
+- research/findings/sno-ai__mda.md
+- research/findings/thedaviddias__souls-directory.md
+- research/findings/Piebald-AI__tweakcc.md
+- research/findings/microsoft__skills.md
+- research/findings/vercel__ai.md
+- research/findings/vercel__next.js.md
+- research/findings/AndreaPontrandolfo__sheriff.md
+- research/findings/MrLesk__Backlog.md.md
+- research/findings/brocoders__extensive-react-boilerplate.md
+- research/findings/vercel__next-forge.md
+- research/findings/wasp-lang__open-saas.md
+- research/findings/google-labs-code__design.md.md
+- research/findings/ixartz__Next-js-Boilerplate.md
+- research/findings/vercel__examples.md
+- research/findings/vercel__next-devtools-mcp.md
+- research/findings/agentsmd__agents.md.md
+- research/findings/antiwork__shortest.md
+- research/findings/zero-one-group__monorepo.md
+- research/findings/RichardHruby__login-machine.md
+- research/findings/kaje94__menufic.md
+- research/findings/vercel__chatbot.md
+- research/findings/vercel__nextjs-postgres-nextauth-tailwindcss-template.md
+- research/findings/vercel__swr.md
+- research/findings/connectrpc__examples-es.md
+- research/findings/vercel__kirimase.md

package/research/summaries/dogfood-adoption-patterns.md

@@ -0,0 +1,33 @@
+# Dogfood And Adoption Evidence Patterns
+
+Generated from a focused follow-up review after current read-only dogfood audits showed that older installs fail the hardened setup standard.
+
+## Why This Pass Was Needed
+
+The kit already had broad 100-repo research, public release gates, and two earlier dogfood installs. Those dogfood notes were stale after later hardening added schema-backed council routing, assistant adapters, upgrade lifecycle, maturity gates, visual QA, and reference-led design critique.
+
+A public best-practice repo needs adoption evidence that stays current as standards change. Dogfood should not only prove that an install once worked; it should also prove that the audit catches drift when the kit improves.
+
+## Focused Sources Reviewed
+
+- GitHub community profile guidance for public repositories: community health files such as README, license, conduct, and contributing files are treated as visible project-health signals.
+- npm Trusted Publishing guidance: publish identity should avoid long-lived tokens, use workflow-bound OIDC, and produce provenance for public packages when conditions are met.
+- npm provenance guidance: publish workflows should support provenance and public access, and consumers can verify registry signatures and attestations.
+- Storybook testing guidance: stories can become reusable accessibility, interaction, visual, and end-to-end testing inputs.
+
+## Repeated Patterns To Adopt
+
+- Keep a public-safe dogfood summary separate from detailed local-path evidence.
+- Treat stale dogfood as a signal, not a failure to hide.
+- Record whether audits were read-only or changed downstream files.
+- Capture pass/warn/fail counts and readiness level for each adoption pass.
+- Promote repeated downstream gaps into installed assets, audit checks, tests, release gates, or decisions.
+- Keep post-publish `npx` verification separate from local package smoke.
+
+## Promoted Updates
+
+- Add `DOGFOOD.md` as a public-safe package asset.
+- Update detailed `dogfood/*` notes with current read-only audit results.
+- Add public-readiness tests that require dogfood evidence while preventing local project paths from leaking into the package.
+
+Do not publish local project paths, private project details, or screenshots without review. Public dogfood summaries should use project archetypes and generalized findings.

package/research/summaries/frontend-design-patterns.md

@@ -0,0 +1,64 @@
+# Frontend Design Patterns
+
+Generated from 41 relevant repository findings.
+
+## Focus Areas
+- frontendDesign
+- accessibility
+
+## Aggregate Evidence
+- Average normalized focus score: 0.57
+- Repositories considered: 41
+
+## Strongest Repositories For This Topic
+- triggerdotdev/trigger.dev (production-saas) - focus score 7, total 32/45
+- formbricks/formbricks (production-saas) - focus score 7, total 29/45
+- shadcn-ui/ui (design-systems) - focus score 7, total 27/45
+- dubinc/dub (production-saas) - focus score 7, total 27/45
+- documenso/documenso (production-saas) - focus score 7, total 27/45
+- boxyhq/saas-starter-kit (production-saas) - focus score 7, total 25/45
+- nextify-limited/saasfly (production-saas) - focus score 7, total 20/45
+- Blazity/next-saas-starter (production-saas) - focus score 7, total 16/45
+- michaelshimeles/nextjs-starter-kit (production-saas) - focus score 7, total 15/45
+- mui/base-ui (design-systems) - focus score 6, total 28/45
+- carbon-design-system/carbon (design-systems) - focus score 6, total 27/45
+- chakra-ui/zag (design-systems) - focus score 6, total 26/45
+
+## Repeated Strengths
+- Documentation is strong enough for external contributors or agents to onboard. (15)
+- Frontend implementation shows reusable components, states, and design-system signals. (14)
+- Security posture is explicit through docs, validation, CI, or review tooling. (11)
+- Test setup includes meaningful automated and browser-level coverage. (9)
+
+## Repeated Gaps
+- Supabase RLS/Auth practices are not clearly discoverable. (41)
+- Agent handoff and AI-workflow instructions are not mature. (26)
+- Security expectations are implicit or incomplete. (22)
+- Accessibility signals are weak or absent. (17)
+
+## Source Findings
+- research/findings/Blazity__next-saas-starter.md
+- research/findings/boxyhq__saas-starter-kit.md
+- research/findings/documenso__documenso.md
+- research/findings/dubinc__dub.md
+- research/findings/formbricks__formbricks.md
+- research/findings/michaelshimeles__nextjs-starter-kit.md
+- research/findings/nextify-limited__saasfly.md
+- research/findings/shadcn-ui__ui.md
+- research/findings/triggerdotdev__trigger.dev.md
+- research/findings/Davronov-Alimardon__canva-clone.md
+- research/findings/DouyinFE__semi-design.md
+- research/findings/LubomirGeorgiev__cloudflare-workers-nextjs-saas-template.md
+- research/findings/async-labs__saas.md
+- research/findings/carbon-design-system__carbon.md
+- research/findings/chakra-ui__ark.md
+- research/findings/chakra-ui__zag.md
+- research/findings/cloudscape-design__components.md
+- research/findings/cosscom__coss.md
+- research/findings/cossistantcom__cossistant.md
+- research/findings/dodopayments__billingsdk.md
+- research/findings/keyshade-xyz__keyshade.md
+- research/findings/mui__base-ui.md
+- research/findings/nextacular__nextacular.md
+- research/findings/palantir__blueprint.md
+- research/findings/primer__react.md

package/research/summaries/frontend-distinctiveness-benchmark-patterns.md

@@ -0,0 +1,38 @@
+# Frontend Distinctiveness Benchmark Patterns
+
+Generated after reviewing the frontend gap raised during public-readiness hardening: a broad repo scan can identify strong component and documentation patterns, but frontend quality still needs a product-specific acceptance benchmark.
+
+## Why This Pass Was Needed
+
+The 100-repo scan and focused follow-up reviews already promoted design tokens, component states, accessibility, visual QA, content-first design, reference-led critique, and a product-quality scorecard. That is better than a normal prompt bundle, but it still left one practical failure mode: a design could satisfy many checklist items while still feeling interchangeable with other AI-generated sites in the same category.
+
+The fix is to require proof that the first screen, content, references, assets, states, and screenshots are specific to the product before accepting significant frontend work.
+
+## Focused Sources Reviewed
+
+- Primer React and Primer design guidance: product-context components, accessibility foundations, and reviewable pattern discipline.
+- Shopify Polaris: product-specific admin patterns, content guidance, tokens, and stateful component guidance.
+- GOV.UK Design System and service/content guidance: user-need-first design, task language, accessibility, and trust.
+- Storybook documentation: component state review, interaction tests, accessibility checks, and visual testing evidence.
+- Radix UI Primitives: accessible behavior foundations separated from product-specific styling.
+- Carbon Design System and USWDS: standards-backed accessibility, state, and service-design expectations.
+
+## Repeated Patterns To Adopt
+
+- Components and tokens are foundations, not proof of product fit.
+- The first viewport should expose the real product object, task, workflow, content, or decision.
+- Product nouns, data shapes, actions, and edge cases should drive layout before styling.
+- References should become named lessons and anti-references, not copied layouts or visual signatures.
+- Asset provenance should be explicit so generated, licensed, placeholder, and real media are not blurred together.
+- State evidence and visual QA should be tied to the product workflow, not only to isolated component polish.
+
+## Promoted Updates
+
+- Add Frontend Distinctiveness Benchmark skill.
+- Add frontend-distinctiveness checklist and benchmark prompt.
+- Update `DESIGN.md` with first-screen proof, content fingerprint, reference benchmark, asset provenance, state proof, and visual QA proof fields.
+- Wire Frontend Design Lead and frontend-change workflow to require distinctiveness benchmark evidence.
+- Add audit warnings when `DESIGN.md` lacks the distinctiveness benchmark.
+- Add public-readiness tests for distinctiveness assets and routing.
+
+Do not copy third-party source code, design files, protected visual identity, brand marks, proprietary layouts, exact copy, or visual signatures from reviewed repositories. Adopt generalized practices only.

package/research/summaries/frontend-product-quality-rubric-patterns.md

@@ -0,0 +1,37 @@
+# Frontend Product Quality Rubric Patterns
+
+Generated from a focused follow-up review after the kit already had content-first design, reference-led critique, visual QA, and anti-generic UI guidance.
+
+## Why This Pass Was Needed
+
+The previous frontend hardening made generic AI-site output harder, but it still relied on qualitative review language. A best-practice setup needs a repeatable product-quality rubric so design agents, coding agents, and human reviewers can reject weak UI for the same reasons.
+
+## Focused Sources Reviewed
+
+- `primer/react` and Primer design guidance: accessible component foundations, product-context patterns, and reviewable design-system decisions.
+- GOV.UK Design System and service/content guidance: user-need-first service design, accessibility, and task-oriented content.
+- Storybook documentation: stateful component review, interaction tests, accessibility checks, and visual testing as review evidence.
+- Shopify Polaris: product-specific admin interface foundations, content guidance, tokens, and component guidance.
+- Radix UI Primitives: accessible, unstyled primitives that separate behavior foundations from product-specific visual direction.
+- Carbon Design System: accessibility status, component guidance, and design-system quality expectations.
+- USWDS: design principles that prioritize real user needs, accessibility, trust, and consistent interaction patterns.
+
+## Repeated Patterns To Adopt
+
+- Treat accessible primitives and components as the foundation, not the product's visual identity.
+- Score UI against real user task, content specificity, information architecture, visual identity, states, accessibility, and safe reference use.
+- Make first-screen specificity a hard gate: users should see the real product object, task, workflow, or content immediately.
+- Require source-safety review whenever references influence layout, imagery, copy, or visual style.
+- Keep desktop/mobile screenshots, state evidence, and visual QA tied to the scorecard verdict.
+- Reject work when polished styling hides missing content, fake data, or generic category tropes.
+
+## Promoted Updates
+
+- Add Frontend Product Quality Rubric skill.
+- Add frontend product-quality checklist and scorecard prompt.
+- Update `DESIGN.md` with a product-quality scorecard and acceptance thresholds.
+- Wire Frontend Design Lead and frontend-change workflow to require the scorecard.
+- Add audit warnings when the scorecard is missing from `DESIGN.md`.
+- Add public-readiness tests for rubric assets and routing.
+
+Do not copy third-party source code, design files, protected visual identity, brand marks, proprietary layouts, or exact copy from reviewed repositories. Adopt generalized practices only.