@appsforgood/next-supabase-kit 0.3.0 → 0.4.1

package/checklists/ui-acceptance-rubric.md

@@ -1,58 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
-# 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 |
-| Accent-border card styling | Cards, callouts, alerts, panels, or status messages rely on thick, high-contrast, one-sided colored borders, glow rails, neon strokes, or gradient borders as the main state cue | Accent borders add decoration where restrained 1px full-border surfaces, subtle background tint, clear labels, icons, and semantic state text would communicate better |
-| Gradient-as-design | Gradient hero, gradient text, abstract blobs, or glow backgrounds substitute for a product-specific first screen | Gradients are present without a tokenized role, brand rationale, or product-specific content support |
-| Card soup | The screen is mostly decorative cards and the primary workflow is unclear | Repeated cards could become a table, list, timeline, form, split pane, or workflow-specific grouped section |
-| 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 |
-| Vague SaaS sayings | Copy could apply to any product and hides what the user can actually do | Phrases like "supercharge your workflow", "unlock insights", "seamless collaboration", or "AI-powered productivity" are not grounded in concrete actions, nouns, constraints, or outcomes |
-| Decorative credibility | Badges, pills, stars, awards, or "trusted by" placeholders imply proof that does not exist | Credibility elements are decorative and should be replaced with real proof, integration names, security posture, support details, or removed |
-| Filler sections | Marketing sections replace the requested app or tool workflow on the first screen | "Features", "benefits", or "how it works" sections are generic and should be replaced with the actual usable workflow or domain-specific hierarchy |
-
-## 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.

package/checklists/upgrade.md

@@ -1,13 +0,0 @@
-# Upgrade Checklist
-
-- [ ] Branch created before upgrade work.
-- [ ] Release notes, changelog, or migration guide reviewed.
-- [ ] `agent-kit diff` reviewed before template updates.
-- [ ] `agent-kit update` run only after preserving local work.
-- [ ] `.agent-kit/conflicts/` reviewed.
-- [ ] `.agent-kit/overrides.json` updated for accepted local deviations.
-- [ ] Next.js codemods or manual upgrade steps reviewed when framework behavior changes.
-- [ ] Supabase migration history, RLS impact, generated types, and rollback risk reviewed when data/auth changes.
-- [ ] Tests, smoke checks, visual QA, or release checks run for affected areas.
-- [ ] `agent-kit audit --min-readiness baseline-setup` passes.
-- [ ] Upgrade evidence, rollback notes, owner, and date recorded in `UPGRADE.md`.

package/checklists/visual-regression.md

@@ -1,11 +0,0 @@
-# Visual Regression Checklist
-
-- Visual QA tier is documented: baseline screenshots, Playwright screenshots, Storybook visual tests, or visual-regression service.
-- Desktop and mobile screenshots exist for primary screens.
-- Reusable components have state stories or screenshot cases for default, loading, empty, error, disabled, success, permission-denied, and mobile states.
-- Dynamic or volatile regions are mocked, masked, frozen, or excluded with rationale.
-- Baseline updates require human review and a short rationale.
-- CI or review notes link to screenshot artifacts, Storybook, Chromatic, Argos, Playwright report, or equivalent evidence.
-- Visual checks cover at least one narrow/mobile viewport and one desktop viewport.
-- Visual checks do not replace accessibility, keyboard, semantic, auth, or data-boundary tests.
-- Known visual QA gaps are recorded in `TESTING.md` before release.

package/design-adapters/claude-design.prompt.md

@@ -1,27 +0,0 @@
-# Claude Design Review Brief
-
-Review or generate UI direction for this product.
-
-Context:
-
-- DESIGN.md: `{{design_md}}`
-- Product: `{{product}}`
-- Users: `{{users}}`
-- Primary task: `{{primary_task}}`
-- Current risk: `{{design_risk}}`
-
-Output:
-
-- Design critique.
-- Brand/content gaps.
-- Creative-direction options or selected-direction critique.
-- Reference-set, anti-reference, and source-safety critique.
-- Frontend product-quality scorecard across user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety.
-- Improved information architecture.
-- Component inventory.
-- Mobile and desktop layout guidance.
-- Accessibility notes.
-- Copy improvements.
-- States for loading, empty, error, disabled, and success.
-
-Reject generic AI-site patterns and prefer product-specific workflow clarity.

package/design-adapters/figma.prompt.md

@@ -1,18 +0,0 @@
-# Figma Design Brief
-
-Create a Figma-ready design direction.
-
-Include:
-
-- DESIGN.md brand/content inputs and creative-direction matrix.
-- Reference set, anti-references, and source-safety notes.
-- Product-quality scorecard requirements and acceptance threshold.
-- Page structure.
-- Component list.
-- Design tokens.
-- Responsive behavior.
-- Form and control states.
-- Accessibility requirements.
-- Notes for handoff to implementation.
-
-Avoid generic AI-site visual defaults and prioritize the real product workflow.

package/design-adapters/google-stitch.prompt.md

@@ -1,36 +0,0 @@
-# Google Stitch Design Brief
-
-Use this brief to generate distinct interface directions from real product content and brand constraints.
-
-DESIGN.md context:
-`{{design_md}}`
-
-Project type:
-`{{project_type}}`
-
-Audience:
-`{{audience}}`
-
-Primary workflow:
-`{{primary_workflow}}`
-
-Design requirements:
-
-- Create three distinct directions unless `DESIGN.md` already selects one.
-- Create mobile and desktop screens.
-- Show real workflow states.
-- Use domain-specific hierarchy.
-- Tie tokens, layout, copy, imagery, density, and interaction tone to the selected content and audience.
-- Use the reference set for learning only and respect all anti-references and source-safety notes.
-- Return a product-quality scorecard covering user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety.
-- Include design tokens.
-- Include empty, loading, error, disabled, and success states.
-- Meet WCAG 2.1 AA.
-
-Avoid:
-
-- Generic purple-blue gradients.
-- Abstract card dashboards.
-- Fake metrics.
-- Vague SaaS copy.
-- Placeholder landing pages.

package/design-adapters/human-designer-brief.prompt.md

@@ -1,36 +0,0 @@
-# Human Designer Brief
-
-## Product
-
-`{{product}}`
-
-## Audience
-
-`{{audience}}`
-
-## Primary Workflow
-
-`{{primary_workflow}}`
-
-## Design Context
-
-`{{design_md}}`
-
-## What We Need
-
-- Domain-specific visual direction.
-- Brand/content gaps and creative-direction recommendation.
-- Reference-set critique, anti-references, and source-safety concerns.
-- Product-quality scorecard with acceptance verdict.
-- Mobile and desktop screens.
-- Design tokens.
-- Component states.
-- Accessibility review.
-- Notes for implementation.
-
-## Avoid
-
-- Generic AI-generated SaaS visuals.
-- Placeholder copy.
-- Fake data.
-- Unclear primary action.

package/design-briefs/admin-dashboard.md

@@ -1,21 +0,0 @@
-# Admin Dashboard Design Brief
-
-Use this brief for internal tools, ops consoles, moderation queues, analytics, and support workflows.
-
-## Product Signals
-
-- First screen should prioritize active work, exceptions, stale items, and operational health.
-- Avoid oversized hero copy, decorative gradients, and promotional layout patterns.
-- Show filters, saved views, bulk actions, and audit trails where relevant.
-
-## Required States
-
-- Loading, empty, filtered-empty, error, partial-data, disabled, success, and permission-denied states.
-- Dense desktop workflow and usable mobile read/review mode.
-- Confirmation and undo patterns for destructive actions.
-
-## Design Direction
-
-- Favor calm information density, sticky table affordances, visible status language, and predictable controls.
-- Use color sparingly for severity, freshness, ownership, and action state.
-- Every chart or metric needs a label, source, timestamp, and empty/error fallback.

package/design-briefs/ai-workflow-product.md

@@ -1,25 +0,0 @@
-# AI Workflow Product Design Brief
-
-Use when designing AI assistants, automation tools, generation workflows, review queues, prompt tools, eval dashboards, agent consoles, or human-in-the-loop products.
-
-## First Screen
-
-Show the real work loop: input, context, model/agent state, output, review, approval, correction, or history. Do not hide the product behind a generic "AI-powered" hero.
-
-## Required Inputs
-
-- User role: operator, reviewer, creator, analyst, developer, admin, or end customer.
-- AI workflow: input sources, context, tools, model calls, outputs, approvals, retries, and audit trail.
-- Trust needs: citations, uncertainty, permissions, rate limits, cost, privacy, and rollback.
-- Human control points: edit, approve, reject, compare, regenerate, escalate, or export.
-
-## Avoid
-
-- Chat box as the only interface when the workflow needs structure.
-- Fake model confidence or fake analytics.
-- Magical language that hides limitations, costs, or review responsibility.
-- Outputs without provenance, status, or recovery path.
-
-## Required States
-
-Queued, streaming, partial output, failed tool call, hallucination report, needs review, approved, rejected, regenerated, rate limited, permission denied, audit trail, mobile review.

package/design-briefs/community-social.md

@@ -1,26 +0,0 @@
-# Community Or Social Design Brief
-
-Use when designing communities, forums, social feeds, member directories, messaging, comments, creator tools, clubs, or collaborative spaces.
-
-## First Screen
-
-Show the community's real activity, topics, people, norms, or contribution path. Avoid generic feed layouts that could belong to any network.
-
-## Required Inputs
-
-- Member types and participation goals.
-- Content types: posts, comments, events, projects, resources, profiles, messages, reactions.
-- Moderation and safety model.
-- Trust, reputation, privacy, consent, and notification rules.
-- Community tone: expert, casual, local, professional, creator-led, support-focused.
-
-## Avoid
-
-- Fake engagement metrics.
-- Infinite feeds without prioritization or safety states.
-- Profile cards with no real identity or contribution signals.
-- Missing empty states for new or quiet communities.
-
-## Required States
-
-New community empty state, muted/blocked/report states, moderation pending, deleted content, private content, notification overload, mobile composer, slow/offline posting.

package/design-briefs/content-app.md

@@ -1,21 +0,0 @@
-# Content App Design Brief
-
-Use this brief for publishing tools, editorial systems, knowledge bases, newsletters, and media products.
-
-## Product Signals
-
-- First screen should show the reading, editing, curation, or review workflow.
-- Avoid generic blog landing pages unless the request is a public marketing surface.
-- Make authorship, freshness, source, status, and editorial workflow visible.
-
-## Required States
-
-- Draft, scheduled, published, archived, review-needed, empty, loading, error, and success states.
-- Reader preferences, search, filtering, and mobile reading layout.
-- Source attribution and unavailable-media fallbacks.
-
-## Design Direction
-
-- Typography and spacing carry the design; do not over-rely on cards.
-- Support scanning with summaries, metadata, sectioning, and predictable hierarchy.
-- Tokens must define body text, display text, captions, links, code, and focus states.

package/design-briefs/ecommerce.md

@@ -1,25 +0,0 @@
-# Ecommerce Design Brief
-
-Use when designing storefronts, product detail pages, carts, checkout flows, merchandising tools, subscriptions, or order-management screens.
-
-## First Screen
-
-Show real product/category inventory, price or availability context, and the next buying or management action. Do not open with generic lifestyle marketing unless the request is explicitly a campaign page.
-
-## Required Inputs
-
-- Product categories, product attributes, variants, inventory, and fulfillment constraints.
-- Buyer goal: browse, compare, buy, reorder, subscribe, gift, or manage orders.
-- Trust signals: returns, shipping, warranty, reviews, security, stock, seller credibility.
-- Asset rules for product photography, thumbnails, swatches, badges, and empty inventory.
-
-## Avoid
-
-- Fake bestseller metrics.
-- Generic ecommerce grid with placeholder products.
-- Decorative hero sections that hide product inspection.
-- Checkout or cart states without error, unavailable, quantity, tax, shipping, and payment edge cases.
-
-## Required States
-
-Loading, empty category, no search results, variant unavailable, out of stock, price changed, cart error, payment error, order success, return/refund state, mobile product inspection.

package/design-briefs/education-course.md

@@ -1,25 +0,0 @@
-# Education Or Course Design Brief
-
-Use when designing learning platforms, course pages, lesson players, cohort dashboards, school tools, tutorials, docs learning paths, or assessment flows.
-
-## First Screen
-
-Show the learner's current path, next lesson, progress, assessment, or decision. Do not default to a generic inspirational landing page.
-
-## Required Inputs
-
-- Learner level, goal, prior knowledge, and constraints.
-- Course structure: modules, lessons, exercises, assessments, resources, cohorts, deadlines.
-- Content types: text, video, code, quiz, project, downloadable material, instructor notes.
-- Success measures: completion, mastery, certification, practice, feedback, community support.
-
-## Avoid
-
-- Progress bars without meaningful next action.
-- Generic course cards with no prerequisites or outcomes.
-- Overly decorative dashboards that obscure learning state.
-- Accessibility gaps in video, code, quizzes, or keyboard navigation.
-
-## Required States
-
-Not started, in progress, blocked, overdue, completed, failed assessment, feedback pending, offline or slow media, mobile lesson view.

package/design-briefs/marketplace.md

@@ -1,21 +0,0 @@
-# Marketplace Design Brief
-
-Use this brief for two-sided marketplaces, listings, booking flows, buyer portals, and seller dashboards.
-
-## Product Signals
-
-- First screen should expose searchable supply, buyer intent, or seller fulfillment work.
-- Avoid fake metrics and placeholder listings.
-- Make trust, availability, pricing, location, eligibility, and next action clear.
-
-## Required States
-
-- No results, filtered results, unavailable item, pending approval, sold/booked, dispute, loading, error, and success states.
-- Buyer and seller role differences.
-- Mobile search, compare, save, and contact flows.
-
-## Design Direction
-
-- Use visual assets that reveal the actual product, place, or listing condition.
-- Prioritize comparison, sorting, saved items, trust signals, and clear transaction steps.
-- Tokens must include status colors for availability, verification, warnings, and completion.

package/design-briefs/portfolio-venue.md

@@ -1,25 +0,0 @@
-# Portfolio Or Venue Design Brief
-
-Use when designing portfolios, personal sites, studios, restaurants, hotels, venues, galleries, agencies, clinics, real-estate showcases, or object/place-focused pages.
-
-## First Screen
-
-The person, place, brand, work, or object must be immediately visible through specific imagery, identity, or proof of work. Do not make the first screen a generic slogan with abstract decoration.
-
-## Required Inputs
-
-- The thing being showcased: person, venue, product, project, place, or service.
-- Real assets: photos, case studies, menus, rooms, locations, artifacts, testimonials, availability, or press.
-- Visitor intent: book, enquire, inspect, compare, visit, hire, buy, or read.
-- Brand tone and sensory details: material, atmosphere, pace, craft, audience, locality.
-
-## Avoid
-
-- Generic agency cards.
-- Dark blurred background photos that hide the actual subject.
-- Fake logos, fake awards, or vague testimonials.
-- Hero sections that do not reveal the real work or place.
-
-## Required States
-
-Image loading, missing asset, enquiry error, booking unavailable, mobile gallery, map/location fallback, long-name wrapping, accessibility for media and carousels.

package/design-briefs/saas.md

@@ -1,21 +0,0 @@
-# SaaS Design Brief
-
-Use this brief for subscription products, team workspaces, account portals, and workflow SaaS.
-
-## Product Signals
-
-- First screen should show the core job: pipeline, inbox, workspace, editor, report, or operational queue.
-- Avoid generic hero-first pages unless the request is explicitly marketing.
-- Make plan, billing, team, permission, and usage states easy to scan.
-
-## Required States
-
-- Trial, active, past due, canceled, and upgrade-required account states.
-- Empty workspace, no data yet, loading, error, disabled, and success states.
-- Mobile layout for the primary repeated workflow, not just the settings screen.
-
-## Design Direction
-
-- Use restrained density, predictable navigation, and domain-specific labels.
-- Prefer tables, split panes, timelines, and command surfaces over decorative cards.
-- Tokens must define semantic status colors, spacing density, radius, and focus states.

package/design-briefs/tool.md

@@ -1,21 +0,0 @@
-# Tool Design Brief
-
-Use this brief for calculators, generators, editors, workflow tools, dashboards, and focused utilities.
-
-## Product Signals
-
-- First screen should be the usable tool, not a landing page explaining the tool.
-- Primary controls, current result, and next action should be visible without scrolling on common viewports.
-- Avoid decorative wrappers around the actual work surface.
-
-## Required States
-
-- Ready, dirty, validating, loading, empty, error, disabled, success, export-ready, and mobile states.
-- Keyboard access for repeated actions.
-- Clear undo, reset, save, copy, download, and share behavior where relevant.
-
-## Design Direction
-
-- Favor stable dimensions, direct manipulation, compact controls, and strong feedback.
-- Use icons for repeated tool actions when a familiar icon exists.
-- Tokens must cover control size, focus rings, surface contrast, and responsive constraints.