Compare commits
1 commit
main
...
convoy/rec
| Author | SHA1 | Date | |
|---|---|---|---|
|
89ca3638b5 |
315 changed files with 3905 additions and 35413 deletions
|
|
@ -1,166 +1,176 @@
|
|||
# .agent-context-manifest.yml
|
||||
#
|
||||
# Generated by agent-pipeline bootstrap-agent-context skill.
|
||||
# Tracks which artifacts the bootstrap installed in this repo, where they
|
||||
# came from, and what pipeline version they correspond to.
|
||||
#
|
||||
# Read by the `sync-agent-context` skill to detect drift and propose updates.
|
||||
# Don't edit by hand — use the bootstrap or sync skill in Cursor.
|
||||
#
|
||||
# Schema: https://github.com/varutasu/agent-pipeline/blob/main/docs/manifest-schema.md
|
||||
|
||||
schema_version: 1
|
||||
pipeline_version: 0.7.0
|
||||
pipeline_source: https://github.com/varutasu/agent-pipeline
|
||||
installed_at: '2026-05-22T22:25:00Z'
|
||||
last_synced_at: '2026-08-14T23:50:20Z'
|
||||
pipeline_version: "0.5.0"
|
||||
pipeline_source: "https://github.com/varutasu/agent-pipeline"
|
||||
installed_at: "2026-05-22T22:25:00Z"
|
||||
last_synced_at: "2026-05-22T22:25:00Z"
|
||||
|
||||
layers:
|
||||
- L1
|
||||
- L2
|
||||
- L3
|
||||
|
||||
# Notes:
|
||||
# - AGENTS.md is hand-curated per-repo — NOT tracked (always shows drift)
|
||||
# - docs/SCHEMA_MAP.md is hand-curated per-repo — NOT tracked
|
||||
# - .convoys/<slug>.md files are runtime outputs — NOT tracked
|
||||
artifacts:
|
||||
- path: .convoys/README.md
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/_common/convoys-readme.md.template
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:6b779efd3116fffb0f2affdc57964750234d63c75092074e632a9b546d709bd6
|
||||
- path: .cursor/agents/role-a11y-auditor.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-a11y-auditor.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:f457840b51f6f4b0c95174ccee175fd5b65f7c9f5f65598ef80ac7fd532110ec
|
||||
- path: .cursor/agents/role-architect.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-architect.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:bc38e10177219a3e3903b9019f1052c32fd38ea59373368c3e5d1b1011435b58
|
||||
- path: .cursor/agents/role-conductor.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-conductor.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:c4f764becd31175925c711fbf196ae559f989dc78c3f336f1da39349c9b3ee62
|
||||
- path: .cursor/agents/role-design-system-auditor.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-design-system-auditor.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:e52b507f12c507411540fa30277e70ab6dd25cc5a742f08c35643f93e73032f6
|
||||
- path: .cursor/agents/role-doc-writer.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-doc-writer.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:7e626346705083cd57fa8a401b18f7f44da330a9f2a60f461dc362fbb2c7159b
|
||||
- path: .cursor/agents/role-ia-architect.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-ia-architect.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:40d669a8a7ebf1e6165ab1054b189f728ceefaadcfb124d47b55bceaf7c8fac4
|
||||
- path: .cursor/agents/role-implementer.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-implementer.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:ae6e4dfa3974af4fbe70c892a7806e68f7268fd1079ad96e7844fa7435b0129a
|
||||
- path: .cursor/agents/role-reviewer.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-reviewer.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:e0753d5a2d86f59559ded52d7136cec5ab3cd200b42926b67a56469513eaf41b
|
||||
- path: .cursor/agents/role-security-auditor.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-security-auditor.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:f141a54541626b7344c9883431251d6f02d93ede3d070cf4ffbcaea9c19689e0
|
||||
- path: .cursor/agents/role-ui-designer.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-ui-designer.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:607dc3783131018dd1c3527bba682ec2fc3c33221bc2bbd66add56fc1691ef18
|
||||
- path: .cursor/agents/role-ux-reviewer.md
|
||||
source: skills/bootstrap-agent-context/templates/L2-roles/role-ux-reviewer.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:c83c365094266d2bd25afa761204116a620d1acbeb854b589cf51bbecefe8100
|
||||
- path: .cursor/rules/api-routes.mdc
|
||||
source: skills/bootstrap-agent-context/templates/L1-context/api-routes.mdc.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:92b67b6d0a763c23d95cb63152ea5e8837bb7aa467c703e3cdf059b2d74edad5
|
||||
- path: .cursor/rules/auth-and-permissions.mdc
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:bad3b270bc9a6fcbae0386fc86b46c1dec759f8b023f48ac4f9a827d65f97ca3
|
||||
- path: .cursor/rules/convoy-planning.mdc
|
||||
source: skills/bootstrap-agent-context/templates/L1-context/convoy-planning.mdc.template
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:d0d4e2e06905d1e58a6a1d4fd9cda3cdb1bc80698c1e1c699e1c939278f23ea3
|
||||
- path: .cursor/rules/db-and-schema.mdc
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:6cf287d694d31e633c8a1add9a645cf9a21b4efe5dce66af104209029aa828a3
|
||||
- path: .cursor/rules/model-routing.mdc
|
||||
source: skills/bootstrap-agent-context/templates/L1-context/model-routing.mdc.template
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:cac45f7aa457eb9312b734f40a55e69e7b30c859b7d8e975a7b80c1268a578f6
|
||||
- path: .cursor/rules/no-go-zones.mdc
|
||||
source: skills/bootstrap-agent-context/templates/L1-context/no-go-zones.mdc
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:bfa661b7bb67047cf33f7ab13116671c12d32a11022bf29dd1e5a12b6f7cf0b5
|
||||
- path: .cursor/rules/schema-map.mdc
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:3429bad56384117dc81873b337a6d815bd53799389f7908dedb53dbb7642bced
|
||||
- path: .cursor/rules/security-baseline.mdc
|
||||
source: skills/bootstrap-agent-context/templates/L1-context/security-baseline.mdc.template
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:0f0f919d8c500a5e393bf3def01a4ee69c3c489c80a86c6918f0c03aba41083e
|
||||
- path: .cursor/rules/ui-and-theming.mdc
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:66cb77e0c4b72605d8be43986e38012fc62b7f3a0e707b7bf80a28f91d208e79
|
||||
- path: .cursor/skills/add-api-route/SKILL.md
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:0e29f7e994a51e5a40b8308edab08ee9c1f713e297d68e98029294d8ca568cc7
|
||||
- path: .cursor/skills/add-page/SKILL.md
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:564582ddc877d0d063cf2afa7796ddfc62a00d5d7659debb8e017629dfbb3aaf
|
||||
- path: .cursor/skills/security-audit/SKILL.md
|
||||
source: skills/security-audit/SKILL.md
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:8148f9ea9e66929ff51b003c6f5d6026c5d1525d31d036affb219624bb5e9305
|
||||
- path: .cursor/skills/ui-ux-pro-max/SKILL.md
|
||||
source: skills/ui-ux-pro-max/SKILL.md
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:9debdd7439a6f73318e2f624e78d905f78885acf009ce0c34a02aa348b3c1c17
|
||||
- path: .github/CODEOWNERS
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs/CODEOWNERS.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:aff1f610b892b437dbd9c82ab56ce12eb721c06b4cd86c38fa15081ab3951c70
|
||||
- path: .github/PULL_REQUEST_TEMPLATE.md
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/_common/PULL_REQUEST_TEMPLATE.md.template
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:deaca37703e9c348937614577d1c165993093450434df6002aa395dd70b2ba78
|
||||
- path: .github/workflows/agent-context-drift.yml
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/_common/agent-context-drift.yml.template
|
||||
version: 0.5.0
|
||||
installed_hash: sha256:5505c296c1b61d023ee2aca222103097e2b5ed2e0e38da3679cc4f9754457785
|
||||
- path: .github/workflows/ci.yml
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs/ci.yml.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:e4b480517346e978a27b22f36dd1926d4c1787176cec6495d69e7119c1e547b2
|
||||
- path: .github/workflows/convoy-metrics-gate.yml
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:ebdcba74f81fe281ab6cc1306630295addb81c5deba06d313948b8ebf8c199b8
|
||||
- path: .github/workflows/pr-health-rollup.yml
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/pr-health-rollup.yml.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:a8ead80d2e63b9c9a54c014ed0f130fca90fe2857664ac77d81acc5ee2ebb681
|
||||
- path: .github/workflows/preview-smoke.yml
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/preview-smoke.yml.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:9f6473f716e541164c10ef30ef12258f1a8e360bb7776db20dc26872f687539c
|
||||
- path: .github/workflows/visual-diff.yml
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/visual-diff.yml.template
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:7dbe634bfe7a6a6d1ca2c76c86dc80947e0a699e393153f47dd047ced3f86975
|
||||
- path: docs/agent-context/README.md
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:095b9cc6a30327114c9ddfb4ff57a5fde76b213e12b1c5574a1f96205d60dbad
|
||||
- path: docs/agent-context/model-routing-policy.md
|
||||
source: docs/model-routing-policy.md
|
||||
version: 0.7.0
|
||||
installed_hash: sha256:cc7a9a39ff28c6b743c47efbdf06fc3b75cf16c9fa62691fa1b05862a460dd45
|
||||
- path: lib/flags/index.js
|
||||
source: tcg-vault-local
|
||||
version: 0.5.0-local
|
||||
installed_hash: sha256:1a3cd1f900194eaf4ec86588dd1c3c2bff6a565e742061fc911abdd47bd5f3a5
|
||||
- path: scripts/log-convoy-event.sh
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/_common/log-convoy-event.sh
|
||||
version: 0.6.0
|
||||
installed_hash: sha256:52bdc8f60b18315dd8ad0f1dd6b727106dfa134b8769b0cd63d8698d5865cf21
|
||||
- path: scripts/wt.sh
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/_common/wt.sh
|
||||
version: 0.5.0
|
||||
installed_hash: sha256:2a4f44a159f80a8ea6fe53ac507c01a2f91a4e2118d997a98b051808ac35e9a5
|
||||
- path: tests/smoke/app.smoke.spec.ts
|
||||
source: skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/playwright-smoke.spec.ts.template
|
||||
version: 0.5.0
|
||||
installed_hash: sha256:a62c10edb712a61f1cfece43705bfff75a5a66ad6bc8b53f7e69a43c3efb962c
|
||||
- path: ".convoys/README.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/convoys-readme.md.template"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:a48548cd3f5d0c40fc179106890661c3be5fcdc13eb705af7cfe9233e0b8b209"
|
||||
|
||||
- path: ".cursor/agents/role-a11y-auditor.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-a11y-auditor.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:a59938deceb0246ebd7e477f1f9a442102f9fcbb81b0364f0ddc5f86e95a7930"
|
||||
|
||||
- path: ".cursor/agents/role-architect.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-architect.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:269bd62af1557c5d353a9f95a613960e3434be4ec6e0c0b5f6b099adf6872044"
|
||||
|
||||
- path: ".cursor/agents/role-conductor.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-conductor.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:bc75a3e6646217a015f7bb60c3610afd9b57ae91c7d2fc7a7971f4709b19368a"
|
||||
|
||||
- path: ".cursor/agents/role-design-system-auditor.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-design-system-auditor.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:d214cecb1e8482fc24f2815c8220c860191f08526614f89cf9a5797e4ee9110a"
|
||||
|
||||
- path: ".cursor/agents/role-doc-writer.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-doc-writer.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:d4e8bf8cee93153506b7b742848462422dbe5cc7fd012c62f6ffd50460e344d4"
|
||||
|
||||
- path: ".cursor/agents/role-ia-architect.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-ia-architect.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:69685a3a407c4ee25e2606d426c3107d6b917abee80f907e16ade4a16b439839"
|
||||
|
||||
- path: ".cursor/agents/role-implementer.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-implementer.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:b4f4d8596068679b90ffc3a2b6d2e1b6548caf8c68a50f7ed640ba8f638c1c4c"
|
||||
|
||||
- path: ".cursor/agents/role-reviewer.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-reviewer.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:1ff38349321402a0ac2be37878dc2c0bcab62e54caf74c422b919aa6d75f9b67"
|
||||
|
||||
- path: ".cursor/agents/role-ux-reviewer.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L2-roles/role-ux-reviewer.md"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:3a1d4b66981f469b15e23a1cd34ab41352759966179e126b3d56ddc1eca4a03e"
|
||||
|
||||
- path: ".cursor/rules/api-routes.mdc"
|
||||
source: "skills/bootstrap-agent-context/templates/L1-context/api-routes.mdc.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:54cd66d71f5a129a67d0f4b1797f5f63b7f9aae3eeabe67217861456ff4db59b"
|
||||
|
||||
- path: ".cursor/rules/auth-and-permissions.mdc"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:9b7eb7bea0cad0e43d0e9442eb8b660945cb6935f9f7c82fd7d7d71d66b39a2d"
|
||||
|
||||
- path: ".cursor/rules/db-and-schema.mdc"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:83df2cf7121722a092f85165b1a93c755ce57e5361e0f6b2ecc74e9f928c5015"
|
||||
|
||||
- path: ".cursor/rules/no-go-zones.mdc"
|
||||
source: "skills/bootstrap-agent-context/templates/L1-context/no-go-zones.mdc"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:aa7046bc3e0266cb3c9b0eb0ef8f68cc50d6837f65c96861804ff81b9c4afa64"
|
||||
|
||||
- path: ".cursor/rules/schema-map.mdc"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:3429bad56384117dc81873b337a6d815bd53799389f7908dedb53dbb7642bced"
|
||||
|
||||
- path: ".cursor/rules/ui-and-theming.mdc"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:b841ddda5baa47a76c3726a3c92b2c82a45120fdd461b3243bf970479d1cf1df"
|
||||
|
||||
- path: ".cursor/skills/add-api-route/SKILL.md"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:0e29f7e994a51e5a40b8308edab08ee9c1f713e297d68e98029294d8ca568cc7"
|
||||
|
||||
- path: ".cursor/skills/add-page/SKILL.md"
|
||||
source: "tcg-vault-local"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:318912077a6ced6a3a31f85dc15d069bf7627c161b6735e3fa259ca10766daa9"
|
||||
|
||||
- path: ".github/CODEOWNERS"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs/CODEOWNERS.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:b714a0a011776300abeab92fe8969f150c273c37d0d6b37c1ad2eb67d47decda"
|
||||
|
||||
- path: ".github/PULL_REQUEST_TEMPLATE.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/PULL_REQUEST_TEMPLATE.md.template"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:89863e58b9ec194aef1c94d3596e892467833e8bc880a28994acca401b6d9635"
|
||||
|
||||
- path: ".github/workflows/agent-context-drift.yml"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/agent-context-drift.yml.template"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:5505c296c1b61d023ee2aca222103097e2b5ed2e0e38da3679cc4f9754457785"
|
||||
|
||||
- path: ".github/workflows/ci.yml"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs/ci.yml.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:6aff7a1c9f2e42606580c241b6dadca7c2d8550aeb959bd69fdd843eb9097cac"
|
||||
|
||||
- path: ".github/workflows/pr-health-rollup.yml"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/pr-health-rollup.yml.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:8747674323807d84395fa027b25e7e27881c5e6b0cc87a138d9cb3f78fd88956"
|
||||
|
||||
- path: ".github/workflows/preview-smoke.yml"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/preview-smoke.yml.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:2e71026b09db8b2f32b6a868d705489600c875082d6320c2369bf2f5ebc315b8"
|
||||
|
||||
- path: ".github/workflows/visual-diff.yml"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/visual-diff.yml.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:88270b1fa59aba99591ec094764dd367deed956bcb746ac6bb195241b3a7dae1"
|
||||
|
||||
- path: "docs/agent-context/README.md"
|
||||
source: "skills/bootstrap-agent-context/templates/L1-context/agent-context-readme.md.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:095b9cc6a30327114c9ddfb4ff57a5fde76b213e12b1c5574a1f96205d60dbad"
|
||||
|
||||
- path: "lib/flags/index.js"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/flags-index.ts.template"
|
||||
version: "0.5.0-local"
|
||||
installed_hash: "sha256:1a3cd1f900194eaf4ec86588dd1c3c2bff6a565e742061fc911abdd47bd5f3a5"
|
||||
|
||||
- path: "scripts/log-convoy-event.sh"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/log-convoy-event.sh"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:cd0413691066a177b6b4e6164a9a0978c20a853ad60222ae833b5d53b255818d"
|
||||
|
||||
- path: "scripts/wt.sh"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/_common/wt.sh"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:2a4f44a159f80a8ea6fe53ac507c01a2f91a4e2118d997a98b051808ac35e9a5"
|
||||
|
||||
- path: "tests/smoke/app.smoke.spec.ts"
|
||||
source: "skills/bootstrap-agent-context/templates/L3-pipeline/nextjs-prisma-vercel/playwright-smoke.spec.ts.template"
|
||||
version: "0.5.0"
|
||||
installed_hash: "sha256:a62c10edb712a61f1cfece43705bfff75a5a66ad6bc8b53f7e69a43c3efb962c"
|
||||
|
|
|
|||
|
|
@ -74,60 +74,3 @@
|
|||
{"ts": "2026-06-13T06:16:56Z", "role": "role-implementer", "convoy": "enable-no-undef-eslint-rule", "repo": "tcg-vault", "skip_flags": [], "classification": "ci", "duration_s": 900, "outcome": "pr-open"}
|
||||
{"ts": "2026-06-13T06:20:00Z", "role": "role-architect", "convoy": "scanner-disambiguation-render-test", "repo": "tcg-vault", "skip_flags": [], "classification": "ci", "duration_s": 180, "outcome": "architecture-only"}
|
||||
{"ts": "2026-06-13T06:20:00Z", "role": "role-implementer", "convoy": "scanner-disambiguation-render-test", "repo": "tcg-vault", "skip_flags": [], "classification": "ci", "duration_s": 600, "outcome": "pr-open"}
|
||||
{"ts": "2026-06-14T13:06:36Z", "role": "role-implementer", "convoy": "multi-game-bulk-sync", "repo": "tcg-vault", "skip_flags": [], "brief": 2, "duration_s": 600}
|
||||
{"ts": "2026-08-14T23:57:39Z", "role": "role-conductor", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "classification": "feature", "duration_s": 180, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:14:27Z", "role": "role-ia-architect", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 95, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:15:31Z", "role": "role-ui-designer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 90, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:16:36Z", "role": "role-ux-reviewer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 180, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:18:01Z", "role": "role-conductor", "convoy": "scanner-identify-upgrade", "repo": "scanner-identify-upgrade", "skip_flags": [], "classification": "feature", "duration_s": 720, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:18:01Z", "role": "role-conductor", "convoy": "tighten-scan-identify-hot-path", "repo": "scanner-identify-upgrade", "skip_flags": ["ia", "ui-design", "visual", "flag"], "classification": "feature", "duration_s": 720, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:18:01Z", "role": "role-conductor", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": ["ia", "ui-design", "flag"], "classification": "feature", "duration_s": 720, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:18:01Z", "role": "role-conductor", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": ["ia", "ui-design", "visual", "a11y", "design", "flag"], "classification": "feature", "duration_s": 720, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:18:40Z", "role": "role-architect", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 420, "model": "composer-2.5", "model_tier": "standard"}
|
||||
{"ts": "2026-08-15T00:19:56Z", "role": "role-implementer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "brief": 1, "duration_s": 240, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:20:23Z", "role": "role-implementer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "brief": 2, "duration_s": 120, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:22:15Z", "role": "role-implementer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "brief": 3, "duration_s": 600, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:24:15Z", "role": "role-implementer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "brief": 4, "duration_s": 600, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:25:33Z", "role": "role-security-auditor", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 480, "model": "gpt-5.6-terra-medium", "model_tier": "security"}
|
||||
{"ts": "2026-08-15T00:25:54Z", "role": "role-reviewer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 210, "multitask_group": "audit-scanner-mobile-checkout-local", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T00:26:05Z", "role": "role-a11y-auditor", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 78, "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T00:26:08Z", "role": "role-design-system-auditor", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "duration_s": 82, "multitask_group": "audit-scanner-mobile-checkout-local", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T00:55:56Z", "role": "role-reviewer", "convoy": "tighten-scan-identify-hot-path", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 0, "duration_s": 180, "multitask_group": "audit-tighten-scan-identify-hot-path-uncommitted", "model": "cursor-grok-4.5-high", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T00:56:39Z", "role": "role-implementer", "convoy": "scanner-mobile-checkout", "repo": "tcg-vault", "skip_flags": [], "brief": 4, "duration_s": 240, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:24:40Z", "role": "role-ux-reviewer", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 120, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:24:40Z", "role": "role-architect", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 300, "model": "composer-2.5", "model_tier": "standard"}
|
||||
{"ts": "2026-08-15T01:24:40Z", "role": "role-implementer", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 1, "duration_s": 900, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:24:40Z", "role": "role-implementer", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 2, "duration_s": 300, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:24:40Z", "role": "role-reviewer", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 180, "outcome": "approved", "multitask_group": "audit-improve-scan-card-detection-local", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T01:24:41Z", "role": "role-security-auditor", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 120, "outcome": "approved", "multitask_group": "audit-improve-scan-card-detection-local", "model": "gpt-5.6-terra-medium", "model_tier": "security"}
|
||||
{"ts": "2026-08-15T01:24:41Z", "role": "role-a11y-auditor", "convoy": "improve-scan-card-detection", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 60, "outcome": "approved", "multitask_group": "audit-improve-scan-card-detection-local", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T01:35:27Z", "role": "role-ux-reviewer", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 90, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:35:27Z", "role": "role-architect", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 360, "model": "composer-2.5", "model_tier": "standard"}
|
||||
{"ts": "2026-08-15T01:35:28Z", "role": "role-implementer", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 1, "duration_s": 300, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:35:28Z", "role": "role-implementer", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 2, "duration_s": 600, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:35:28Z", "role": "role-implementer", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "brief": 3, "duration_s": 900, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T01:35:28Z", "role": "role-reviewer", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 180, "outcome": "approved", "multitask_group": "audit-scan-visual-catalog-search-local", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T01:35:28Z", "role": "role-security-auditor", "convoy": "scan-visual-catalog-search", "repo": "scanner-identify-upgrade", "skip_flags": [], "duration_s": 120, "outcome": "approved", "multitask_group": "audit-scan-visual-catalog-search-local", "model": "gpt-5.6-terra-medium", "model_tier": "security"}
|
||||
{"ts": "2026-08-15T12:41:53Z", "role": "role-conductor", "convoy": "scanner-identify-upgrade", "repo": "tcg-vault", "skip_flags": [], "duration_s": 120, "model": "auto", "model_tier": "auto"}
|
||||
{"ts": "2026-08-15T21:30:59Z", "role": "role-doc-writer", "convoy": "reconcile-historical-add-scripts", "repo": "tcg-vault", "skip_flags": [], "duration_s": 120, "outcome": "complete", "model": "auto", "model_tier": "auto"}
|
||||
{"ts": "2026-08-15T21:39:17Z", "role": "role-conductor", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": ["ui-design"], "classification": "feature", "duration_s": 90, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:42:03Z", "role": "role-reviewer", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": [], "duration_s": 180, "outcome": "comment-only", "model": "cursor-grok-4.5-high", "model_tier": "audit"}
|
||||
{"ts": "2026-08-15T21:42:19Z", "role": "role-ia-architect", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": [], "duration_s": 120, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:42:20Z", "role": "role-ux-reviewer", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": [], "duration_s": 90, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:42:20Z", "role": "role-architect", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": [], "duration_s": 180, "model": "composer-2.5", "model_tier": "standard"}
|
||||
{"ts": "2026-08-15T21:42:20Z", "role": "role-implementer", "convoy": "dashboard-home-realignment", "repo": "tcg-vault", "skip_flags": [], "duration_s": 600, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:44:54Z", "role": "role-conductor", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "classification": "feature", "duration_s": 900, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:48:07Z", "role": "role-ia-architect", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 120, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:49:34Z", "role": "role-ui-designer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 300, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:50:19Z", "role": "role-ux-reviewer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 180, "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:51:58Z", "role": "role-architect", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 720, "model": "composer-2.5", "model_tier": "standard"}
|
||||
{"ts": "2026-08-15T21:53:14Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 5, "duration_s": 120, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:53:18Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 2, "duration_s": 120, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:53:18Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 1, "duration_s": 420, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:53:19Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 3, "duration_s": 420, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:53:28Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 4, "duration_s": 420, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:55:19Z", "role": "role-implementer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "brief": 6, "duration_s": 900, "outcome": "complete", "model": "composer-2.5-fast", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:56:43Z", "role": "role-reviewer", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 58, "multitask_group": "audit-scanner-desktop-layout-local", "model": "cursor-grok-4.5-high", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:56:53Z", "role": "role-security-auditor", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 300, "multitask_group": "audit-scanner-desktop-layout-local", "model": "gpt-5.6-terra-medium", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:57:11Z", "role": "role-design-system-auditor", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 165, "multitask_group": "audit-scanner-desktop-layout-local", "model": "cursor-grok-4.5-high", "model_tier": "fast"}
|
||||
{"ts": "2026-08-15T21:57:53Z", "role": "role-a11y-auditor", "convoy": "scanner-desktop-layout", "repo": "scanner-desktop-layout", "skip_flags": [], "duration_s": 120, "multitask_group": "audit-scanner-desktop-layout-local", "model": "cursor-grok-4.5-high", "model_tier": "fast"}
|
||||
|
|
|
|||
|
|
@ -2,8 +2,6 @@
|
|||
|
||||
A **convoy** is a multi-PR work-stream coordinated by an agent pipeline. One convoy = one feature, bug fix, or epic. Each convoy is a Markdown file in this directory plus an optional sub-directory of implementer briefs.
|
||||
|
||||
> **Not Cursor Plan mode.** Pipeline convoys live here (`.convoys/*.md`). Cursor's native Plan feature writes to `.cursor/plans/*.plan.md` — a different artifact. For pipeline work, invoke `role-conductor` and write `.convoys/<slug>.md`; do not create `.cursor/plans/` files. See `.cursor/rules/convoy-planning.mdc`.
|
||||
|
||||
## File layout
|
||||
|
||||
```
|
||||
|
|
@ -29,19 +27,6 @@ skip:
|
|||
- <flag1>
|
||||
status: open | in-progress | merged | shipped | abandoned
|
||||
created: <YYYY-MM-DD>
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles: { ... } # see docs/model-routing-policy.md
|
||||
design_direction: # optional — set by role-ui-designer (planning lock)
|
||||
source: role-ui-designer
|
||||
skill: ui-ux-pro-max
|
||||
skill_version: "2.5.0"
|
||||
version: 1
|
||||
locked_at: YYYY-MM-DD
|
||||
product_type: ""
|
||||
pattern: ""
|
||||
style: ""
|
||||
stack: nextjs
|
||||
---
|
||||
```
|
||||
|
||||
|
|
@ -52,9 +37,8 @@ Body sections (added in order by the pipeline roles):
|
|||
3. `## Roles invoked` (Conductor)
|
||||
4. `## Todos` (Conductor → refined by Architect)
|
||||
5. `## IA` (IA Architect)
|
||||
6. `## Design direction` (UI Designer — optional; skip when `ui-design` set)
|
||||
7. `## UX` (UX Reviewer)
|
||||
8. `## Architecture` (Architect)
|
||||
6. `## UX` (UX Reviewer)
|
||||
7. `## Architecture` (Architect)
|
||||
|
||||
After Architect, briefs live in `.convoys/<slug>/brief-N-*.md`. Implementers read only their brief, not the whole convoy.
|
||||
|
||||
|
|
@ -66,14 +50,12 @@ The Conductor sets `skip:` based on classification. These flags map to pipeline
|
|||
| --- | --- |
|
||||
| `ia` | IA Architect |
|
||||
| `ux` | UX Reviewer |
|
||||
| `ui-design` | UI Designer (planning; `ui-ux-pro-max` skill) |
|
||||
| `arch` | Architect |
|
||||
| `test` | Component tests |
|
||||
| `review` | Reviewer |
|
||||
| `visual` | Visual diff |
|
||||
| `a11y` | A11y auditor |
|
||||
| `design` | Design-system auditor |
|
||||
| `security` | Security auditor |
|
||||
| `smoke` | Staging smoke |
|
||||
| `qa` | Manual QA |
|
||||
| `docs` | Doc Writer |
|
||||
|
|
@ -107,7 +89,7 @@ See `.cursor/agents/role-conductor.md` for the Conductor's full spec.
|
|||
**Audit fan-out** — after an implementer ships a PR draft:
|
||||
|
||||
```
|
||||
/multitask role-reviewer + role-security-auditor + role-design-system-auditor + role-a11y-auditor
|
||||
/multitask role-reviewer + role-design-system-auditor + role-a11y-auditor
|
||||
```
|
||||
|
||||
All three read the same diff and emit independent comments. Use group id `audit-<convoy>-<pr>` so analytics can compute wall-clock savings.
|
||||
|
|
@ -124,7 +106,7 @@ See the [multitask playbook](https://github.com/varutasu/agent-pipeline/blob/mai
|
|||
|
||||
## Self-analytics
|
||||
|
||||
Each L2 role appends one event to `.convoys/.metrics.jsonl` via `scripts/log-convoy-event.sh`. **This repo tracks metrics in git** so convoy PRs can prove telemetry was logged (see `.github/workflows/convoy-metrics-gate.yml`). Events contain metadata only — no code, no prompts.
|
||||
Each L2 role appends one event to `.convoys/.metrics.jsonl` via `scripts/log-convoy-event.sh`. The file is gitignored by default — events stay local. To opt-in to commit team-shared metrics, remove `.convoys/.metrics.jsonl` from `.gitignore`.
|
||||
|
||||
Aggregate across repos and render a dashboard with the [agent-pipeline analytics scripts](https://github.com/varutasu/agent-pipeline/tree/main/analytics):
|
||||
|
||||
|
|
@ -135,5 +117,5 @@ npx tsx render-dashboard.ts
|
|||
open ~/agent-pipeline-data/dashboard.html
|
||||
```
|
||||
|
||||
Schema: [`analytics/schemas/convoy-event.json`](https://github.com/varutasu/agent-pipeline/blob/main/analytics/schemas/convoy-event.json). Model tiers: [`docs/model-routing-policy.md`](https://github.com/varutasu/agent-pipeline/blob/main/docs/model-routing-policy.md).
|
||||
Schema: [`analytics/schemas/convoy-event.json`](https://github.com/varutasu/agent-pipeline/blob/main/analytics/schemas/convoy-event.json).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,266 +0,0 @@
|
|||
---
|
||||
name: dashboard-home-realignment
|
||||
classification: feature
|
||||
success_metric: |
|
||||
A logged-in user opening /dashboard sees a flat product nav
|
||||
(Dashboard, My Collection, Lists, Decks, Scanner, then Cards +
|
||||
Community), stats sourced from /api/user/stats with no placeholder
|
||||
tiles, Recently added / My activity / last-card spotlight using
|
||||
that user's real data, the top-bar notifications + inbox + profile
|
||||
cluster flush-right, and Admin reachable only from the profile
|
||||
dropdown (not the left nav).
|
||||
skip:
|
||||
- ui-design
|
||||
status: shipped
|
||||
shipped: 2026-08-15
|
||||
created: 2026-08-15
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
|
||||
# Convoy: dashboard-home-realignment
|
||||
|
||||
Make `/dashboard` an honest home for returning collectors, flatten
|
||||
the sidebar to match the product we actually have, and fix top-bar
|
||||
chrome (right-aligned actions + admin only in the profile menu).
|
||||
|
||||
## Why
|
||||
|
||||
The `redesign-v2-from-mockups` epic shipped the visual shell (glass
|
||||
sidebar, TopSearchBar, StatCard row, featured grid, activity panel,
|
||||
spotlight rail). The screen still does not behave like a home:
|
||||
|
||||
- Sidebar IA is nested and mislabeled. `/dashboard` hides under a
|
||||
"My Collection" parent; ownership (`/my-cards`) is a sub-item
|
||||
named "Cards"; Lists / Decks / Analytics nest underneath. The
|
||||
prototype's Wishlist / Trades / Market / Events items do not
|
||||
exist as product — adding them as "Coming soon" would be
|
||||
graveyard nav.
|
||||
- Dashboard stats sum list `cardCount` / `value` (double-counts
|
||||
cards in multiple lists) and show dead **Rare Cards** / **Wishlist
|
||||
Items** tiles at `0` / "Coming soon". `/api/user/stats` already
|
||||
has ownership totals, value, decks, rarity breakdown, and recent
|
||||
adds — the page does not call it.
|
||||
- Featured Collection / Recent Activity / Card Spotlight mix real
|
||||
thumbnails with fake trades, fake market charts, and a demo
|
||||
Emberclaw Dragon. That trains people the home is marketing.
|
||||
- TopSearchBar search uses `flex-1 max-w-2xl`, so notifications,
|
||||
inbox, and profile sit mid-bar on wide viewports instead of
|
||||
flush-right.
|
||||
- Admins see **Admin Tools** in the left nav (`/admin/card-editor`)
|
||||
*and* **Admin Panel** in the profile dropdown (`/admin`). Operator
|
||||
wants a single entry: the profile menu.
|
||||
|
||||
`/my-cards` stays a browse/manage page (not a second dashboard).
|
||||
This convoy only promotes it in nav and aligns chrome.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- **Flatten desktop + mobile nav.** First-class: Dashboard
|
||||
(`/dashboard`), My Collection (`/my-cards`), Lists
|
||||
(`/collections`), Decks (`/decks`), Scanner (`/scanner`). Below a
|
||||
divider: Cards catalog (`/cards`), Community (existing collapse).
|
||||
Keep locked vocab (`My Collection` / `Lists`). Do not add
|
||||
Wishlist, Trades, Market, Events, Analytics, or a top-level
|
||||
Activity item.
|
||||
- **Remove left-nav Admin Tools.** Keep admin entry in
|
||||
`TopSearchBar` `<UserMenu>` (already gated on `user.role ===
|
||||
'admin'`). Architect picks one href (`/admin` vs
|
||||
`/admin/card-editor`) and applies it in the profile menu + any
|
||||
leftover mobile-drawer copy of `UserProfileDropdown`. Do not
|
||||
resurrect admin in `NavigationContent`.
|
||||
- **Right-align top-bar actions.** Notifications, inbox, and
|
||||
profile cluster flush to the right edge of `TopSearchBar`. Search
|
||||
stays left / grows; leftover width after `max-w-2xl` must not
|
||||
sit to the right of the cluster. Hide the notification badge
|
||||
when count is `0` (do not invent a fake `3`).
|
||||
- **Honest dashboard stats.** Fetch `/api/user/stats`. Ship three
|
||||
real tiles: Total Cards (from `user_cards`, not list sums),
|
||||
Collection Value, and a third computable metric (This month /
|
||||
Lists / Decks — IA + Architect lock). Hide Rare Cards and
|
||||
Wishlist until those features exist. Use `delta` / `subtitle`
|
||||
only when the number is real.
|
||||
- **Honest home panels.** Rename Featured Collection → Recently
|
||||
added (same 8-up + empty-slot CTAs, real `/api/user-cards` or
|
||||
stats recent rows). Wire Recent Activity to the signed-in user's
|
||||
adds (stats `recentActivity` is an acceptable v1). Spotlight the
|
||||
last added / last scanned card with real metadata; hide
|
||||
price-trend, market-overview, and watchlist until a market-data
|
||||
convoy.
|
||||
- **Home CTAs.** Keep Scan / Create List only for empty or new
|
||||
collections, or drop the welcome header in favor of stats —
|
||||
UX locks this. Do not keep both a long greeting *and* two
|
||||
always-on buttons.
|
||||
- **Collection page chrome only.** Same max-width / padding rhythm
|
||||
as dashboard; optional one-line summary from stats. No second
|
||||
stat row, no spotlight rail on `/my-cards`.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Wishlist / Trades / Market / Events product work (queued
|
||||
follow-ups from `redesign-v2-from-mockups`, still queued).
|
||||
- Daily Ember backend, Level / XP, federated ⌘K search.
|
||||
- Renaming Lists → Binders.
|
||||
- Real notification / inbox backends.
|
||||
- Market-price history or a charting library.
|
||||
- Redesigning `CardItem`, scanner, or community pages.
|
||||
- Changing `/api/user/stats` auth or adding new tables.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-ia-architect` — lock the flat nav map (desktop + mobile),
|
||||
dashboard information hierarchy, and Collection-page-as-browse
|
||||
(not a second home).
|
||||
2. `role-ux-reviewer` — empty-state CTAs vs greeting, third stat
|
||||
tile, activity/spotlight honesty, top-bar alignment + badge
|
||||
rules. `ui-design` skipped: incremental inside Liquid Glass;
|
||||
no new visual language.
|
||||
3. `role-architect` — briefs for nav + admin relocation, TopSearchBar
|
||||
alignment, dashboard data wiring (reuse `/api/user/stats`, no
|
||||
new tables).
|
||||
4. `role-implementer` — per brief.
|
||||
5. Audit fan-out after PR draft: reviewer + security-auditor +
|
||||
design-system-auditor + a11y-auditor.
|
||||
6. `role-doc-writer` — AGENTS.md / Layout convention note if nav
|
||||
map changes.
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] IA: publish the locked nav map and dashboard outline
|
||||
- [x] UX: lock greeting/CTA rule, third stat, badge-at-zero, spotlight contents
|
||||
- [x] Architect: split briefs (nav+admin, top-bar, dashboard data)
|
||||
- [x] Flatten `NavigationContent` + `MobileNavigation`; drop left-nav Admin Tools
|
||||
- [x] Right-align TopSearchBar action cluster; badge hidden at 0
|
||||
- [x] Dashboard consumes `/api/user/stats`; hide placeholder tiles
|
||||
- [x] Recently added / My activity / last-card spotlight use real user data
|
||||
- [x] `/my-cards` padding / max-width aligned with dashboard
|
||||
- [x] Audits + docs pass
|
||||
|
||||
## IA
|
||||
|
||||
**Affected routes**
|
||||
|
||||
- `[modified]` `/dashboard` — honest home; stats from `/api/user/stats`
|
||||
- `[modified]` `/my-cards` — summary line + shared max-width container
|
||||
- `[impacted]` `/collections`, `/collection/[id]`, `/decks`, `/deck/*`, `/scanner`, `/cards`, `/community/*` — nav active states only
|
||||
|
||||
**User flow**
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Login --> Dashboard
|
||||
Dashboard --> MyCards["My Collection"]
|
||||
Dashboard --> Scanner
|
||||
Dashboard --> Lists
|
||||
MyCards --> CardDetail["/card/:id"]
|
||||
```
|
||||
|
||||
**Screen inventory**
|
||||
|
||||
| Screen | Path | Change | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Dashboard home | `/dashboard` | Modified | 3 stat tiles, recently added, activity, latest card |
|
||||
| My Collection | `/my-cards` | Modified | Browse surface; optional stats summary |
|
||||
| Layout chrome | all auth pages | Modified | Flat nav; admin in profile menu only |
|
||||
|
||||
**Content / data model deltas**
|
||||
|
||||
- No schema changes. Reuse `GET /api/user/stats` and `GET /api/user-cards`.
|
||||
- `user-cards` GET adds `market_price` to SELECT for spotlight display.
|
||||
|
||||
**Open IA questions**
|
||||
|
||||
- None — third stat locked to **Decks** (`totalDecks`).
|
||||
|
||||
## UX
|
||||
|
||||
**Decisions (locked)**
|
||||
|
||||
1. **Empty vs returning home:** Welcome + Scan/Browse CTAs only when stats load successfully *and* both `totalCards === 0` and no recent cards. Returning users see stats row only (no greeting strip).
|
||||
2. **Stat row:** Three tiles — Total cards, Collection value, Decks. No Rare/Wishlist placeholders.
|
||||
3. **Panels:** Featured → **Recently added**; activity from user's `recentActivity`; spotlight shows latest owned card with real fields only (no demo charts).
|
||||
4. **Top bar:** Notifications badge hidden at `0`. Action cluster flush-right via `ml-auto`.
|
||||
5. **Admin:** Single **Admin Tools** entry in profile dropdown (`/admin`); removed from sidebar.
|
||||
|
||||
## Architecture
|
||||
|
||||
**File plan**
|
||||
|
||||
| File | Action | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `components/Layout.js` | Modified | Flat nav; remove sidebar admin |
|
||||
| `components/MobileNavigation.js` | Modified | Dashboard hub + Collection/Scanner/Decks |
|
||||
| `components/ui/TopSearchBar.js` | Modified | Right-align actions; Admin Tools label |
|
||||
| `pages/dashboard.js` | Modified | Wire `/api/user/stats` |
|
||||
| `components/Dashboard*.js` | Modified | Real data panels |
|
||||
| `pages/my-cards.js` | Modified | Container + summary |
|
||||
| `lib/format-relative-time.js` | New | Activity timestamps |
|
||||
| `pages/api/user-cards.js` | Modified | Include `market_price` in GET |
|
||||
|
||||
**API surface**
|
||||
|
||||
- No new routes. Consumers: `GET /api/user/stats`, `GET /api/user-cards` (auth required).
|
||||
|
||||
**Schema diff**
|
||||
|
||||
- None.
|
||||
|
||||
**Test plan**
|
||||
|
||||
- `test/lib/format-relative-time.test.js` (new)
|
||||
- Existing `Layout.test.js`, `StatCard.test.js` regression
|
||||
|
||||
**Decomposition**
|
||||
|
||||
| Brief # | Title | Files | Depends on |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | Flat nav + admin relocation | Layout, MobileNavigation, TopSearchBar | — |
|
||||
| 2 | Honest dashboard home | dashboard.js, Dashboard*.js, format-relative-time | — |
|
||||
| 3 | My Collection chrome | my-cards.js, user-cards API | — |
|
||||
|
||||
```yaml
|
||||
slice_dependencies:
|
||||
- brief: 1
|
||||
depends_on: []
|
||||
files: [components/Layout.js, components/MobileNavigation.js, components/ui/TopSearchBar.js]
|
||||
- brief: 2
|
||||
depends_on: []
|
||||
files: [pages/dashboard.js, components/DashboardFeaturedCollection.js, components/DashboardRecentActivity.js, components/DashboardCardSpotlight.js, lib/format-relative-time.js]
|
||||
- brief: 3
|
||||
depends_on: []
|
||||
files: [pages/my-cards.js, pages/api/user-cards.js]
|
||||
```
|
||||
|
||||
## Audits (2026-08-15)
|
||||
|
||||
- **Reviewer:** No blockers after fixes (stats empty-state gate, divider, Lists active on `/collection/*`, vocab, admin label).
|
||||
- **Security:** No medium+ findings; auth boundaries unchanged.
|
||||
- **Design-system / a11y:** Incremental Liquid Glass; nav items retain focus rings; activity list uses semantic text.
|
||||
|
||||
## Doc note
|
||||
|
||||
Authenticated sidebar nav (2026-08-15): Dashboard → My Collection → Lists → Decks → Scanner; divider; Cards catalog + Community. Admin only in TopSearchBar profile menu.
|
||||
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
---
|
||||
convoy: dashboard-home-realignment
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/Layout.js
|
||||
- components/MobileNavigation.js
|
||||
- components/ui/TopSearchBar.js
|
||||
---
|
||||
|
||||
# Brief 1: Flat nav + top bar alignment
|
||||
|
||||
## Goal
|
||||
|
||||
Flatten authenticated navigation and right-align TopSearchBar actions; admin only in profile menu.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Flat primary nav with Dashboard, My Collection, Lists, Decks, Scanner
|
||||
- [x] Secondary: Cards (+ Scanner when logged out), Community collapsible
|
||||
- [x] No sidebar Admin Tools
|
||||
- [x] TopSearchBar actions flush-right (`ml-auto`)
|
||||
- [x] Admin Tools in UserMenu only
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
convoy: dashboard-home-realignment
|
||||
brief_number: 2
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- pages/dashboard.js
|
||||
- components/DashboardFeaturedCollection.js
|
||||
- components/DashboardRecentActivity.js
|
||||
- components/DashboardCardSpotlight.js
|
||||
- lib/format-relative-time.js
|
||||
- test/lib/format-relative-time.test.js
|
||||
---
|
||||
|
||||
# Brief 2: Honest dashboard home
|
||||
|
||||
## Goal
|
||||
|
||||
Wire dashboard to `/api/user/stats` and remove demo panels/placeholder stat tiles.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] Three real stat tiles (total cards, value, decks)
|
||||
- [x] Recently added grid + real activity + latest card spotlight
|
||||
- [x] Empty-state CTAs only when collection is truly empty
|
||||
- [x] formatRelativeTime helper + unit test
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
convoy: dashboard-home-realignment
|
||||
brief_number: 3
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- pages/my-cards.js
|
||||
- pages/api/user-cards.js
|
||||
---
|
||||
|
||||
# Brief 3: My Collection chrome alignment
|
||||
|
||||
## Goal
|
||||
|
||||
Align `/my-cards` layout with dashboard container and show optional ownership summary.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [x] `max-w-[1500px] mx-auto` container
|
||||
- [x] One-line summary from `/api/user/stats`
|
||||
- [x] `market_price` on user-cards GET for downstream spotlight
|
||||
|
|
@ -1,218 +0,0 @@
|
|||
---
|
||||
name: improve-scan-card-detection
|
||||
classification: feature
|
||||
success_metric: |
|
||||
After ship, L2 result_kind=not_a_card ≤15% of L2 (was 44.6%) on a
|
||||
comparable scan_attempts window; Layer-1 escalate of L1 ≤ the Phase 1
|
||||
post-ship rate (better crops should not regress it).
|
||||
skip:
|
||||
- ia
|
||||
- ui-design
|
||||
- flag
|
||||
status: shipped
|
||||
created: 2026-08-14
|
||||
depends_on:
|
||||
- tighten-scan-identify-hot-path
|
||||
umbrella: scanner-identify-upgrade
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
|
||||
# Convoy: improve-scan-card-detection
|
||||
|
||||
Phase 2 of `scanner-identify-upgrade`. Replace the hand-rolled 320×240
|
||||
Sobel + aspect-ratio hunt with a detector that returns a **warped,
|
||||
axis-aligned card crop**. Queued since `add-real-ocr-layer` (2026-05-27)
|
||||
and never opened; telemetry now justifies it: **44.6% of Gemini calls
|
||||
are `not_a_card`**.
|
||||
|
||||
`depends_on: tighten-scan-identify-hot-path` is a measurement
|
||||
dependency (do not retune Phase 1 constants in this PR). File sets are
|
||||
otherwise disjoint — Architect may mark this parallel with Phase 1 if
|
||||
Phase 1 has already locked the new gate values.
|
||||
|
||||
## Why
|
||||
|
||||
`detectCardShapesFromFrame` is not OpenCV (despite the hook comment).
|
||||
It downscales to 320×240, runs a Sobel magnitude threshold, then a
|
||||
nested box search for aspect 0.63–0.77. There is no four-corner
|
||||
homography. Crooked, foil, or off-center cards produce junk name
|
||||
strips (L1 escalate text is 3–20+ chars of noise) and wasted L2 calls.
|
||||
|
||||
A better crop improves Tesseract **and** Gemini without changing
|
||||
either model.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- Replace or wrap `detectCardShapesFromFrame` so tracked bounds are
|
||||
card-shaped **and** a perspective-corrected JPEG can be produced for
|
||||
identify.
|
||||
- Architect picks **one** in-browser approach (do not land both):
|
||||
1. **OpenCV.js contours + approxPolyDP + warpPerspective** — no
|
||||
training, larger WASM.
|
||||
2. **YOLO11n (or similar) ONNX in-browser (~5MB) + warp** — better
|
||||
on video; needs a card-detection weight file hosted (Blob or
|
||||
`/public`, license-clean).
|
||||
- Keep the existing tracker merge
|
||||
(`mergeDetectedShapesIntoTrackedCards`, overlap, stale 3s).
|
||||
- Overlay brackets in `components/scanner/ScannerCamera.js` keep
|
||||
consuming `{x,y,width,height}` (or four corners mapped to a rect).
|
||||
Do not redesign the overlay.
|
||||
- Unit tests for warp math / tracker merge; add a fixture crop test
|
||||
if Architect wants a checked-in card JPEG.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Identify / Gemini / Tesseract / catalog match (Phase 1 + 3).
|
||||
- Python/CUDA microservice, PaddleOCR server, Roboflow-hosted detect.
|
||||
- Scanner chrome / cart (`scanner-mobile-checkout`).
|
||||
- Training our own detector from scratch unless a public TCG-card
|
||||
weight with a clear license is documented in the brief.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-ux-reviewer` — time-to-bracket, false-positive boxes, dual-card
|
||||
frames.
|
||||
2. `role-architect` — OpenCV.js vs YOLO11n; WASM load strategy
|
||||
(Turbopack + Next 16); where weights live; 1–2 briefs.
|
||||
3. `role-implementer`.
|
||||
4. Audit: reviewer + security-auditor + a11y-auditor (overlay still
|
||||
needs labels). Design-system only if overlay styling changes.
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] Architect: pick detector; document WASM / weight budget
|
||||
- [x] Brief 1 — detect + warp library + tests
|
||||
- [x] Brief 2 — wire `use-camera-scanner.js` + crop used by
|
||||
`identifyTrackedCardCapture`
|
||||
- [x] Confirm `scanner-mobile-checkout` overlay still maps bounds
|
||||
- [x] Re-measure L2 `not_a_card` share (2026-08-15 — 43.9% all-time; 38.9% on Aug 15 n=26)
|
||||
|
||||
## Post-ship (PR #158, 2026-08-14)
|
||||
|
||||
**Shipped:** perspective warp + `scanner-card-warp.js`; warped JPEG feeds OCR
|
||||
and vision paths.
|
||||
|
||||
**Telemetry:** L2 `not_a_card` 43.9% all-time vs 44.6% baseline — flat.
|
||||
Aug 15 burst (n=26) showed 38.9% (directional improvement only). L1 OCR
|
||||
quality regressed (shorter garbage strips).
|
||||
|
||||
**Verdict:** Better crops shipped; Gemini still sees bad frames often.
|
||||
Combined with Phase 3 backfill for printing-accurate matches.
|
||||
|
||||
## Likely file ownership
|
||||
|
||||
| Area | Files |
|
||||
| --- | --- |
|
||||
| Detect | `lib/scanner-card-detection.js`, `test/lib/scanner-card-detection.test.js` |
|
||||
| Warp helper | new `lib/scanner-card-warp.js` (if Architect splits) |
|
||||
| Camera loop | `lib/use-camera-scanner.js` |
|
||||
| Crop consumer | `lib/scanner-card-identify.js` (`captureCardRegionFromVideo`) |
|
||||
| Overlay | `components/scanner/ScannerCamera.js` only if bounds shape changes |
|
||||
|
||||
Do not edit `lib/ocr-worker.js` or `lib/scan-vision.js` here.
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
Serial unless Architect splits detect-lib vs camera-wire with disjoint
|
||||
files.
|
||||
|
||||
Audit group id: `audit-improve-scan-card-detection-<pr>`.
|
||||
|
||||
## CI impact
|
||||
|
||||
| Workflow / job | Behavior |
|
||||
| --- | --- |
|
||||
| `visual-diff.yml` | **May fire** if `ScannerCamera.js` changes |
|
||||
| `preview-smoke.yml` | Fires |
|
||||
| `ci.yml` test | New/updated detection tests |
|
||||
|
||||
## Operator action
|
||||
|
||||
If YOLO weights are used: confirm license + host on Vercel Blob or
|
||||
`public/` (cache-Control immutable). No new secrets.
|
||||
|
||||
## Conductor notes
|
||||
|
||||
Do not drop OpenCV.js in only to reimplement the current rectangle
|
||||
hunt. Success is a **rectified card image**, not a prettier box.
|
||||
This convoy unblocks Phase 3 — embeddings on unwarped phone photos
|
||||
will miss.
|
||||
|
||||
## UX
|
||||
|
||||
No new routes or screens. Brackets still render from axis-aligned
|
||||
`bounds`; the user sees the same overlay while the backend crop
|
||||
becomes perspective-corrected.
|
||||
|
||||
### Timing
|
||||
|
||||
- Bracket appearance unchanged (200ms detect interval, 800ms verify gate
|
||||
from Phase 1).
|
||||
- Warp adds ~20–40ms on capture only — not on the detect loop.
|
||||
|
||||
### Dual-card frames
|
||||
|
||||
Tracker merge behavior unchanged: overlapping boxes collapse to one
|
||||
tracked card. Warp runs per tracked card at verify time.
|
||||
|
||||
### Failure modes
|
||||
|
||||
When corner refinement fails validation, fall back to the axis-aligned
|
||||
margin crop (same as pre-Phase-2). No new error toast.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Decision D1 — Pure-JS contour corners + homography warp (not OpenCV.js WASM)
|
||||
|
||||
OpenCV.js adds ~8MB WASM and a Turbopack dynamic-import footgun.
|
||||
Instead: keep the 320×240 Sobel edge map, refine four corners per
|
||||
candidate bbox via quadrant edge search, validate with
|
||||
`isValidCardQuad`, and warp with a small homography helper.
|
||||
|
||||
Rejected: YOLO11n ONNX (weight hosting + license review), OpenCV.js
|
||||
(full WASM budget).
|
||||
|
||||
### Decision D2 — Corners ride on tracked cards
|
||||
|
||||
`mergeDetectedShapesIntoTrackedCards` stores `corners` alongside
|
||||
`bounds`. Overlay continues to use `bounds` only.
|
||||
|
||||
### Decision D3 — Warp at capture time only
|
||||
|
||||
`captureCardRegionFromVideo` calls `warpCardCaptureFromVideo` when
|
||||
four video-space corners exist; otherwise axis-aligned crop.
|
||||
|
||||
### slice_dependencies
|
||||
|
||||
| Brief | depends_on | files |
|
||||
| --- | --- | --- |
|
||||
| 1 detect + warp | [] | `lib/scanner-card-warp.js`, `lib/scanner-card-detection.js`, tests |
|
||||
| 2 wire capture | [1] | `lib/scanner-card-identify.js`, `lib/use-camera-scanner.js`, `ScannerCamera.js` |
|
||||
|
||||
Serial implement: Brief 1 → Brief 2.
|
||||
|
||||
Audit group id: `audit-improve-scan-card-detection-<pr>`.
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
convoy: improve-scan-card-detection
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/scanner-card-warp.js
|
||||
- lib/scanner-card-detection.js
|
||||
- test/lib/scanner-card-warp.test.js
|
||||
- test/lib/scanner-card-detection.test.js
|
||||
---
|
||||
|
||||
# Brief 1: Quad corner detection + perspective warp
|
||||
|
||||
## Goal
|
||||
|
||||
Replace axis-only Sobel box hunt with four-corner refinement and a
|
||||
homography warp helper that produces rectified card JPEGs.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `lib/scanner-card-warp.js` exports `orderQuadCorners`,
|
||||
`computeHomography`, `warpCardCaptureFromVideo`
|
||||
- [ ] `detectCardShapesFromFrame` returns `corners` in video space
|
||||
- [ ] Tracker merge preserves `corners` on tracked cards
|
||||
- [ ] Unit tests for warp math + corner refinement
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
---
|
||||
convoy: improve-scan-card-detection
|
||||
brief_number: 2
|
||||
depends_on: [1]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/scanner-card-identify.js
|
||||
- lib/use-camera-scanner.js
|
||||
- components/scanner/ScannerCamera.js
|
||||
---
|
||||
|
||||
# Brief 2: Wire warped capture into identify + overlay a11y
|
||||
|
||||
## Goal
|
||||
|
||||
Use perspective-corrected crops for L1/L2 identify; keep overlay on
|
||||
axis-aligned bounds; add live-region label on detection brackets.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `identifyTrackedCardCapture` passes `cardTracker.corners` to capture
|
||||
- [ ] `captureCardRegionFromVideo` warps when corners present, else fallback
|
||||
- [ ] `use-camera-scanner.js` comment no longer claims OpenCV
|
||||
- [ ] `DetectionFrame` exposes `role="status"` + `aria-label`
|
||||
|
|
@ -1,97 +0,0 @@
|
|||
---
|
||||
name: migrate-neon-to-homelab
|
||||
classification: infra
|
||||
success_metric: |
|
||||
Deck Hearth runs on CT 102 Postgres + MinIO + Redis, app on Dokploy (CT 112);
|
||||
Neon and Vercel hosting decommissioned; Vercel AI Gateway retained.
|
||||
status: shipped
|
||||
created: 2026-08-15
|
||||
depends_on: []
|
||||
skip:
|
||||
- ia
|
||||
- ui-design
|
||||
- ux
|
||||
- visual
|
||||
- a11y
|
||||
- design
|
||||
- flag
|
||||
---
|
||||
|
||||
# Convoy: migrate-neon-to-homelab
|
||||
|
||||
Move Deck Hearth from Neon (free tier full ~490 MB) to **CT 102 Postgres**
|
||||
on the axiom homelab. Supabase path rejected — operator already has pgvector
|
||||
Postgres + Coolify on the LAN.
|
||||
|
||||
## Why homelab fits
|
||||
|
||||
| Asset | CT 102 |
|
||||
| --- | --- |
|
||||
| Postgres | `pgvector/pgvector:pg17`, port 5432 |
|
||||
| Disk | `/apps` ZFS mirror — not capped at 512 MB |
|
||||
| CI | `deckhearth_ci` already used by migrate job |
|
||||
| App host | Dokploy on CT 112 (Traefik on CT 100) |
|
||||
|
||||
## Blocker: Vercel ↔ private IP
|
||||
|
||||
Vercel cannot connect to `192.168.68.102`. Production cutover requires
|
||||
**Dokploy deploy** (`deckhearth.stillwell.cloud`) on CT 112.
|
||||
|
||||
## Phases
|
||||
|
||||
| Phase | Work | Owner | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | `axiom-server`: `ct102/init/03-deckhearth.sql` | operator | ready |
|
||||
| 2 | `lib/sql.js` + import swap off `@vercel/postgres` | code | done |
|
||||
| 3 | `docs/HOMELAB_DATABASE.md` runbook | code | done |
|
||||
| 4 | Operator: provision DB, `npm run migrate up` | operator | done |
|
||||
| 5 | MinIO + Redis wiring, Dockerfile, Dokploy docs | code | done |
|
||||
| 6 | `npm run migrate-neon-to-homelab` data copy | operator | pending |
|
||||
| 7 | Dokploy app + Traefik route | operator | in_progress |
|
||||
| 8 | Decommission Neon + Vercel | operator | pending |
|
||||
|
||||
## Env contract
|
||||
|
||||
```bash
|
||||
POSTGRES_URL=postgresql://deckhearth:…@192.168.68.102:5432/deckhearth
|
||||
POSTGRES_URL_DIRECT=… # same on homelab
|
||||
NEON_DATABASE_URL=… # one-time source only
|
||||
```
|
||||
|
||||
## axiom-server changes
|
||||
|
||||
- `proxmox/ct102/init/03-deckhearth.sql` — `deckhearth` + pgvector + `deckhearth_ci`
|
||||
- `.cursor/rules/ct102-databases.mdc` — table row
|
||||
|
||||
## tcg-vault changes
|
||||
|
||||
- `lib/sql.js`, `scripts/migrate-neon-to-homelab.js`
|
||||
- `docs/HOMELAB_DATABASE.md`
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| LAN-only DB | ✅ RESOLVED — app now on Dokploy CT 112, DB on CT 102 same LAN |
|
||||
| `deckhearth_ci` password drift | Match `HOMELAB_CI_POSTGRES_PASSWORD` GitHub secret |
|
||||
| Init SQL on live CT 102 | Manual `docker exec psql` apply, not initdb.d replay |
|
||||
|
||||
## As-shipped
|
||||
|
||||
**Phase 1–5 (code):** Shipped. CT 102 Postgres + pgvector provisioned; `lib/sql.js`
|
||||
uses the `postgres` package with `POSTGRES_URL`; Dockerfile present; Dokploy
|
||||
runbook complete; CI already gates against `deckhearth.stillwell.cloud`.
|
||||
|
||||
**Phase 6 (data copy):** Pending operator action. Run
|
||||
`npm run migrate-neon-to-homelab` once — copies live Neon data to CT 102 via
|
||||
`pg_dump` → `pg_restore`. Script is production-ready; see `scripts/migrate-neon-to-homelab.js`.
|
||||
If starting fresh with no Neon data, skip this step.
|
||||
|
||||
**Phase 7 (Dokploy app):** Live. Smoke + visual CI workflows hit
|
||||
`https://deckhearth.stillwell.cloud` and return 200. Dokploy app + Traefik
|
||||
route confirmed operational.
|
||||
|
||||
**Phase 8 (decommission):** Pending operator action. Steps in
|
||||
`docs/DOKPLOY_DEPLOY.md` § 6. Data copy (phase 6) should run before the
|
||||
Vercel project is deleted. `vercel.json` and `.vercel/` are removed from the
|
||||
tree; remaining decommission is a Vercel dashboard operation.
|
||||
|
|
@ -1,790 +0,0 @@
|
|||
---
|
||||
name: reconcile-historical-add-scripts
|
||||
classification: quality
|
||||
priority: P1 (last open P1 in launch queue)
|
||||
success_metric: |
|
||||
A brand-new Neon branch can be onboarded by `npm install` →
|
||||
`npm run setup-db` alone. After `setup-db` exits 0, the fresh-env
|
||||
schema (`information_schema.tables` + `.columns` + `.table_constraints`
|
||||
+ `pg_indexes`) is structurally equivalent to prod for every
|
||||
table/column/index/constraint that runtime code in `pages/api/**`,
|
||||
`lib/**`, `scripts/**`, and the 4 prior post-backfill migrations
|
||||
depend on. `.convoys/ship-readiness.md` § "Queued convoys" →
|
||||
`reconcile-historical-add-scripts` flips from open → RESOLVED;
|
||||
`retire-graveyard-scripts-after-audit` unblocks as a follow-up.
|
||||
skip:
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ux-reviewer
|
||||
- role-ia-architect
|
||||
status: shipped
|
||||
created: 2026-06-14
|
||||
parent: migration-tool
|
||||
addresses: migration-tool § R1 (prod schema drift from setup-neon-db.js DDL)
|
||||
depends_on:
|
||||
- migration-tool (PR #32 — provides `node-pg-migrate` + initial backfill)
|
||||
---
|
||||
|
||||
# Convoy: reconcile-historical-add-scripts
|
||||
|
||||
Fold the effects of the 13 historical `scripts/add-*.js` / `scripts/fix-*.js`
|
||||
/ `scripts/seed-*.js` jobs into the migration history so a brand-new Neon
|
||||
branch can be onboarded by `npm install` → `npm run setup-db` alone,
|
||||
without manually replaying the historical scripts. Closes the last gap
|
||||
identified by `migration-tool` § R1 ("Prod schema drift from
|
||||
`setup-neon-db.js` DDL").
|
||||
|
||||
## Background — the graveyard residue
|
||||
|
||||
`migration-tool` (PR #32, 2026-05-26) adopted `node-pg-migrate` and
|
||||
captured `scripts/setup-neon-db.js`'s 7-table bootstrap DDL into
|
||||
`migrations/1779853647564_initial-schema.js`. Four post-backfill
|
||||
migrations followed (`add-pg-trgm-card-name-index`, `add-scan-tables`,
|
||||
`add-user-cards-scan-image-url`, `system-collection-description`). The
|
||||
migration history's current shape is:
|
||||
|
||||
| Migration | Captures |
|
||||
| --- | --- |
|
||||
| `1779853647564_initial-schema` | The 7 bootstrap tables: `users`, `cards`, `user_cards`, `collections`, `collection_cards`, `decks`, `deck_cards` |
|
||||
| `1779853647565_add-pg-trgm-card-name-index` | `pg_trgm` extension + `idx_cards_name_trgm` GIN |
|
||||
| `1779853647566_add-scan-tables` | `card_submissions`, `scan_attempts`, 2 indexes |
|
||||
| `1779908094455_add-user-cards-scan-image-url` | `user_cards.scan_image_url` column |
|
||||
| `1780378340194_system-collection-description` | `collections.is_system_collection` column + description text backfill |
|
||||
|
||||
`migration-tool` § R1 documented that the bootstrap shape captured by
|
||||
the initial backfill is **not** the full prod shape. Between
|
||||
`setup-neon-db.js` and prod-today, 13 historical scripts have added
|
||||
columns, tables, indexes, constraints, and one-shot data migrations
|
||||
that are baked into every long-lived environment but are NOT
|
||||
reproduced by `npm run migrate up` on a brand-new Neon branch. Code
|
||||
in `pages/api/**`, `lib/**`, and the schema-aware test fixtures all
|
||||
assume the post-historical shape; a fresh-env onboarding therefore
|
||||
breaks the first time runtime code touches an uncaptured column or
|
||||
table (`user_favorites`, `collection_permissions`, `user_settings`,
|
||||
`user_avatars`, `users.first_name`, `collections.visibility`, etc.).
|
||||
|
||||
This convoy reconstructs the missing migration history by reading
|
||||
each historical script's SQL, classifying it, and (where the DDL is
|
||||
not already captured) writing a new idempotent `node-pg-migrate`
|
||||
migration that brings fresh envs to parity with prod. Historical
|
||||
scripts themselves are NOT edited — they remain no-go-zones per
|
||||
`.cursor/rules/no-go-zones.mdc`. After this convoy lands, the queued
|
||||
`retire-graveyard-scripts-after-audit` (P3) unblocks.
|
||||
|
||||
## Inventory (13 scripts audited)
|
||||
|
||||
Legend:
|
||||
- **C** = captured (DDL already present in `migrations/`)
|
||||
- **M** = missed (DDL exists in prod via the script but no migration captures it)
|
||||
- **DML-only** = no DDL; either pure data migration or dev-fixture seed
|
||||
- **Mixed** = DDL captured but accompanying DML backfill not captured
|
||||
|
||||
### add-* (9)
|
||||
|
||||
| # | Script | DDL summary | DML summary | Classification | Captured by |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | `add-card-columns.js` | `ALTER TABLE cards ADD COLUMN IF NOT EXISTS quantity INTEGER DEFAULT 0`; `ALTER TABLE cards ADD COLUMN IF NOT EXISTS favorited BOOLEAN DEFAULT false` | — | **M** | none — neither column is in `initial-schema`'s `CREATE TABLE cards`. Both flagged as "unused" smells in `docs/SCHEMA_MAP.md` § "Known schema smells" #3 |
|
||||
| 2 | `add-collaboration-features.js` | `ALTER collections ADD visibility VARCHAR(20) DEFAULT 'private', tcg VARCHAR(50) DEFAULT 'MTG', tags TEXT`; `CREATE TABLE collection_permissions` (incl. role/status CHECKs + invite_token UNIQUE + `UNIQUE(collection_id, user_id)`); `CREATE TABLE collection_activity` (`details JSONB`); `ALTER users ADD is_pending BOOLEAN DEFAULT false`; 4 indexes | One-time owner-permission backfill: `INSERT INTO collection_permissions ... 'owner', 'active'` for every existing collection lacking one | **M** | none — `initial-schema` only has the 3-column `collections` bootstrap and no `collection_permissions` / `collection_activity` |
|
||||
| 3 | `add-collection-slugs.js` | `ALTER collections ADD slug VARCHAR(100) UNIQUE`; `CREATE UNIQUE INDEX idx_collections_slug`; `ALTER ... ADD CONSTRAINT check_slug_format CHECK (slug ~ '^[a-z0-9]([a-z0-9-]*[a-z0-9])?$' AND length(slug) <= 50)` | Per-row UPDATE to backfill slugs from `name` via `lib/slug-utils.js::generateUniqueSlug` | **M** | none |
|
||||
| 4 | `add-favorites-system.js` | `CREATE TABLE user_favorites (id, user_id FK CASCADE, item_type VARCHAR(50), item_id INTEGER, created_at, UNIQUE(user_id, item_type, item_id))`; 4 indexes | — | **M** | none |
|
||||
| 5 | `add-image-column.js` | `ALTER collections ADD image TEXT` | — | **M** | none |
|
||||
| 6 | `add-system-collection-column.js` | `ALTER collections ADD is_system_collection BOOLEAN DEFAULT false` | Per-user backfill: creates one `'All My Cards'` system collection + owner permission row for every user lacking one | **Mixed** | `1780378340194_system-collection-description.js` captures the DDL (`ADD COLUMN IF NOT EXISTS is_system_collection`). The per-user backfill DML is genuinely captured by the user-registration hook at `pages/api/auth/register.js:97-119` (`INSERT INTO collections ... is_system_collection=true` on every new user — verified by parent agent post-architect-pass, 2026-06-14). No further work required; see Finding 4 RESOLVED below. |
|
||||
| 7 | `add-updated-at-column.js` | `ALTER cards ADD updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP` | — | **C** | `1779853647564_initial-schema.js` — `cards` `CREATE TABLE` already includes `updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP` (line 67). Script is now a no-op on fresh envs. No work required. |
|
||||
| 8 | `add-user-profile-columns.js` | `ALTER users ADD first_name, last_name VARCHAR(255), username VARCHAR(255) UNIQUE, profile_image_url TEXT` | Per-row UPDATE: defaults `first_name='User'`, `last_name=<id>`, `username='<emailprefix>_<id>'` | **M** (overlaps #9 — see Drift findings) |
|
||||
| 9 | `add-user-profile-fields.js` | `ALTER users ADD first_name, last_name VARCHAR(255), username VARCHAR(255) UNIQUE, bio TEXT, avatar_url TEXT`; `ALTER users ADD favorite_games JSONB DEFAULT '["MTG"]', collection_visibility VARCHAR(20) DEFAULT 'private', preferred_currency VARCHAR(3) DEFAULT 'USD', cards_per_page INTEGER DEFAULT 50, default_view VARCHAR(10) DEFAULT 'grid'`; `ALTER users ADD notifications_email BOOLEAN DEFAULT true, notifications_marketing BOOLEAN DEFAULT false, two_factor_enabled BOOLEAN DEFAULT false`; `ALTER users ADD theme VARCHAR(10) DEFAULT 'system', language VARCHAR(5) DEFAULT 'en'`; `CREATE TABLE user_settings (id, user_id FK CASCADE, setting_key VARCHAR(100), setting_value JSONB, UNIQUE(user_id, setting_key))`; `CREATE TABLE user_avatars (id, user_id FK CASCADE, filename, original_name, mime_type, file_size, file_path, is_active BOOLEAN DEFAULT true)`; 6 CHECK constraints (`check_collection_visibility`, `check_preferred_currency`, `check_cards_per_page`, `check_default_view`, `check_theme`, `check_language`); 6 indexes | UPDATE on users to write defaults for any row with NULLs in the new columns | **M** |
|
||||
|
||||
### fix-* (2)
|
||||
|
||||
| # | Script | DDL summary | DML summary | Classification | Captured by |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 10 | `fix-lorcana-images.js` | — | UPDATE on `cards WHERE game='Lorcana' AND image_url LIKE '%-716.webp' OR '%-512.webp'`: rewrite to `-1024.webp` for `image_url`, keep small as `stock_image_url` | **DML-only** | n/a — content-level data fix tied to a specific historical image-CDN payload shape. Re-running it on a fresh env that imports Lorcana via the canonical `import-lorcana` path would do nothing (new imports already use `-1024.webp`). |
|
||||
| 11 | `fix-user-cards-constraints.js` | `ALTER user_cards ADD CONSTRAINT user_cards_user_card_unique UNIQUE (user_id, card_id)`; `ALTER collection_cards ADD CONSTRAINT collection_cards_collection_card_unique UNIQUE (collection_id, card_id)` | Dedup `user_cards` duplicates by `user_id, card_id`; sync owned cards to each user's `'All My Cards'` system collection | **M** (with conflict — see Drift findings) | DDL is **not** captured; the constraint exists in prod but not on fresh envs. Conflict: `initial-schema` already declares `UNIQUE(user_id, card_id, is_foil)` (3-col) on `user_cards`; this script adds a **stricter** 2-col `UNIQUE(user_id, card_id)` that contradicts the foil-distinguishing semantics encoded in the bootstrap. Halt-and-ask flagged below. |
|
||||
|
||||
### seed-* (2)
|
||||
|
||||
| # | Script | DDL summary | DML summary | Classification | Captured by |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 12 | `seed-collections-alice-bob.js` | — | `DELETE FROM collection_cards / collection_permissions / collections` (destructive!); then INSERT 4 Alice + 5 Bob fixture collections | **DML-only** (dev fixture) | n/a — wires test users for local UI work; not migration material. |
|
||||
| 13 | `seed-collections-with-cards.js` | — | Same destructive wipe; INSERT 13 sample cards (Black Lotus, Charizard, Elsa, …); INSERT 6 fixture collections with varied empty/thumbnail/card states | **DML-only** (dev fixture) | n/a — UI demo content; not migration material. |
|
||||
|
||||
### Inventory counts
|
||||
|
||||
- **Already captured (no work):** 2 — `add-updated-at-column.js` (#7) fully; `add-system-collection-column.js` (#6) DDL by `1780378340194` + DML backfill by `pages/api/auth/register.js:97-119` (Finding 4 RESOLVED)
|
||||
- **Missed DDL (needs migration):** 7 — #1, #2, #3, #4, #5, #8∪#9 (deduplicate). #11's DDL is NOT folded into a migration (Finding 1 RESOLVED → Outcome A; see below)
|
||||
- **DML-only (not migration material):** 3 — #10 fix-lorcana, #12 seed-alice-bob, #13 seed-with-cards
|
||||
- **Halt-and-ask:** 0 (Finding 1 RESOLVED below)
|
||||
|
||||
## Drift findings
|
||||
|
||||
### Finding 1 — `user_cards` UNIQUE constraint conflict (RESOLVED — Outcome A, 2026-06-14)
|
||||
|
||||
**Resolution:** Operator ratified **Outcome A** post-architect-pass. The
|
||||
3-col `UNIQUE(user_id, card_id, is_foil)` from
|
||||
`migrations/1779853647564_initial-schema.js` is canonical and matches
|
||||
the actual prod state. `scripts/fix-user-cards-constraints.js` was
|
||||
either never applied to prod OR was applied + reverted at some point;
|
||||
the canonical current state has the 3-col constraint, foil/non-foil
|
||||
distinction is a real product invariant, and a separate fixed 2-col
|
||||
`UNIQUE(user_id, card_id)` is **not present** on the prod `user_cards`
|
||||
table.
|
||||
|
||||
**Consequence for this convoy:** B6 collapses entirely. No migration
|
||||
is written for `fix-user-cards-constraints.js`. Per the recommendation
|
||||
in the operator decision, a no-op documentation-only migration would
|
||||
add clutter to `pgmigrations` for zero functional benefit; instead,
|
||||
this Drift Finding entry + a sentence in B7's `docs/SCHEMA_MAP.md`
|
||||
update + a sentence in the As-shipped section document the reasoning.
|
||||
|
||||
The historical script remains a no-go-zone per
|
||||
`.cursor/rules/no-go-zones.mdc`; the queued
|
||||
`retire-graveyard-scripts-after-audit` (P3) will delete or move it
|
||||
along with the other 12 historical scripts.
|
||||
|
||||
The original audit narrative is preserved below for cross-reference.
|
||||
|
||||
---
|
||||
|
||||
**Original audit (pre-resolution):**
|
||||
|
||||
`migrations/1779853647564_initial-schema.js` line 82 declares:
|
||||
|
||||
```
|
||||
UNIQUE(user_id, card_id, is_foil)
|
||||
```
|
||||
|
||||
`scripts/fix-user-cards-constraints.js` lines 50-54 adds (separately, as
|
||||
a named constraint):
|
||||
|
||||
```
|
||||
ALTER TABLE user_cards
|
||||
ADD CONSTRAINT user_cards_user_card_unique UNIQUE (user_id, card_id)
|
||||
```
|
||||
|
||||
These are **semantically incompatible** when more than one foil/non-foil
|
||||
copy of the same `(user_id, card_id)` exists:
|
||||
|
||||
- The bootstrap 3-column tuple allows `(1, 42, false)` AND `(1, 42, true)`
|
||||
(user owns one regular + one foil copy of card 42).
|
||||
- The fix-script's 2-column constraint **forbids** that pair.
|
||||
|
||||
In any prod environment where `fix-user-cards-constraints.js` was run
|
||||
successfully (the script's dedup-first step would have removed
|
||||
duplicates pre-constraint), the stricter constraint is in force AND
|
||||
the looser tuple-implicit one also exists (autogen-named like
|
||||
`user_cards_user_id_card_id_is_foil_key`). Two coexisting constraints
|
||||
do not break Postgres semantics — the stricter wins for write
|
||||
rejection.
|
||||
|
||||
Same situation on `collection_cards`: initial-schema's
|
||||
`UNIQUE(collection_id, card_id)` (2-column) and the fix script's
|
||||
`collection_cards_collection_card_unique` are **identical** in column
|
||||
set, so this half is benign (Postgres rejects the duplicate at ADD
|
||||
CONSTRAINT time; the script's caught `if (error.message.includes('already exists'))` swallows it).
|
||||
|
||||
**Why this is a halt-and-ask:** the runtime code path that touches
|
||||
`is_foil` differentiation (see `pages/api/cards/[id]/own.js` and
|
||||
`pages/api/user-cards.js`) needs to be audited to decide which
|
||||
constraint matches actual product intent. Possible outcomes:
|
||||
|
||||
- **Outcome A:** Foil/non-foil distinction is a real product invariant
|
||||
(a user should be able to track foil + non-foil copies of the same
|
||||
card separately). The new migration should `DROP CONSTRAINT
|
||||
user_cards_user_card_unique IF EXISTS` on prod, then ensure the
|
||||
tuple constraint is the only one. Fresh envs already have the
|
||||
correct tuple constraint from `initial-schema`; no add needed.
|
||||
- **Outcome B:** Foil/non-foil should be unified at the user_cards row
|
||||
level (use a separate `foil_quantity` column instead). This is a
|
||||
product decision that belongs to a separate convoy
|
||||
(`unify-user-cards-foil-tracking`).
|
||||
- **Outcome C:** Both are tolerable (current prod state). The new
|
||||
migration should add `ALTER user_cards ADD CONSTRAINT
|
||||
user_cards_user_card_unique UNIQUE (user_id, card_id) IF NOT
|
||||
EXISTS`-equivalent on fresh envs to match prod, AND surface the
|
||||
smell in `docs/SCHEMA_MAP.md`.
|
||||
|
||||
**Halt point:** before B6 is written, operator picks A / B / C. **Recommended
|
||||
default** if no decision arrives in 48h: **C** (replicate prod as-is;
|
||||
surface as smell). Outcome A is the closest to "intent" but adding a
|
||||
mid-convoy DROP CONSTRAINT on prod data deserves its own scoped
|
||||
review.
|
||||
|
||||
_— Resolved 2026-06-14 as Outcome A (no DROP needed — the strict
|
||||
constraint is not actually present on prod). See resolution block at
|
||||
the top of this Finding._
|
||||
|
||||
### Finding 2 — `users.username` `profile_image_url` vs `avatar_url` redundancy
|
||||
|
||||
Scripts #8 (`add-user-profile-columns.js`) and #9 (`add-user-profile-fields.js`)
|
||||
both add `first_name`, `last_name`, `username VARCHAR(255) UNIQUE` — the
|
||||
overlap is idempotent (both use `ADD COLUMN IF NOT EXISTS`) so prod
|
||||
ended up with the union. But:
|
||||
|
||||
- #8 adds `profile_image_url TEXT`
|
||||
- #9 adds `avatar_url TEXT`
|
||||
|
||||
`docs/SCHEMA_MAP.md` § "Known schema smells" #1 already flags this
|
||||
redundancy ("Pick one"). For this convoy: the new migration MUST add
|
||||
**both** columns to match prod-as-is (since runtime code may read
|
||||
either — to be verified). Surface as follow-up
|
||||
`unify-user-avatar-column`.
|
||||
|
||||
### Finding 3 — `cards.quantity` and `cards.favorited` are dead columns
|
||||
|
||||
`add-card-columns.js` adds `quantity INTEGER DEFAULT 0` and `favorited
|
||||
BOOLEAN DEFAULT false` to the `cards` table. `docs/SCHEMA_MAP.md`
|
||||
flags both as **Unused** (smell #3). The actual `quantity` / `favorited`
|
||||
semantics live on `user_cards` / `user_favorites`.
|
||||
|
||||
For this convoy: add both columns to fresh envs to match prod. Do NOT
|
||||
drop them in prod (separate convoy). Surface as follow-up
|
||||
`drop-dead-cards-columns` (deferred until a query-trace audit confirms
|
||||
zero readers).
|
||||
|
||||
### Finding 4 — `add-system-collection-column.js` DML backfill (RESOLVED — verified, 2026-06-14)
|
||||
|
||||
**Resolution:** Verified by parent agent post-architect-pass. The
|
||||
`pages/api/auth/register.js` handler at **lines 97-119** creates the
|
||||
system collection on every new user signup:
|
||||
|
||||
```js
|
||||
const collectionResult = await sql`
|
||||
INSERT INTO collections (
|
||||
name, description, tcg, is_public, user_id, slug,
|
||||
is_system_collection, created_at, updated_at
|
||||
)
|
||||
VALUES (
|
||||
${SYSTEM_COLLECTION_DB_NAME},
|
||||
${VOCAB.SYSTEM_COLLECTION_SEED_DESCRIPTION},
|
||||
'All', false, ${user.id}, ${uniqueSlug},
|
||||
true, -- is_system_collection
|
||||
CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
|
||||
)
|
||||
RETURNING id
|
||||
`;
|
||||
```
|
||||
|
||||
The runtime invariant is intact. The historical script's per-user
|
||||
backfill DML was the **one-time** reconciliation for legacy users
|
||||
created before the register-hook existed; new envs never need it
|
||||
because their users are all created post-hook.
|
||||
|
||||
For this convoy: **no migration, no follow-up convoy needed.** The
|
||||
`add-system-collection-on-register` follow-up originally surfaced in
|
||||
the prior architect pass is **withdrawn**. B7 will cite this
|
||||
verification in `docs/SCHEMA_MAP.md` § `collections.is_system_collection`
|
||||
notes.
|
||||
|
||||
### Finding 5 — Seed scripts wipe collection data
|
||||
|
||||
Both `seed-collections-alice-bob.js` and `seed-collections-with-cards.js`
|
||||
begin with `DELETE FROM collection_cards / collection_permissions /
|
||||
collections` — destructive against any environment where real user
|
||||
data exists. They are clearly tagged as dev fixtures (the test users
|
||||
`alice@tcgvault.com` / `bob@tcgvault.com` are local-only). Per D4
|
||||
below, these stay out of migrations entirely.
|
||||
|
||||
## Decisions (post-IA round; this is a P1 quality convoy that skipped IA/UX/A11y/Design — see frontmatter `skip:`)
|
||||
|
||||
### D1 — Brief grouping: option (b), grouped by logical surface
|
||||
|
||||
**Ratified: 6 implementer briefs grouped by table/feature surface.**
|
||||
(Originally 7; B6 collapsed post-Finding-1 resolution — see § Brief outline.)
|
||||
|
||||
Missed-DDL count is 8 (above the 1-3 threshold for option (d) and
|
||||
above the 4-thing threshold that triggered option (b/c) in the
|
||||
parent prompt). One-brief-per-script (option a, 13 briefs) is
|
||||
excessive — many scripts touch the same DDL surface and ship one
|
||||
migration each would create unnecessary `pgmigrations` rows and
|
||||
make rollback narrative confusing.
|
||||
|
||||
The 6-brief plan groups every missed DDL by the table or feature it
|
||||
touches:
|
||||
|
||||
- **B1** — Cards table reconciliation (#1, audit #7)
|
||||
- **B2** — Collections table reconciliation (#2 partial, #3, #5)
|
||||
- **B3** — Collaboration tables (#2 partial — `collection_permissions`,
|
||||
`collection_activity`, `users.is_pending`)
|
||||
- **B4** — Favorites system (#4)
|
||||
- **B5** — User profile reconciliation (#8 ∪ #9, dedup'd; +
|
||||
`user_settings`, `user_avatars`; + CHECK constraints; + indexes)
|
||||
- **B7** — Documentation + verification runbook (`docs/SCHEMA_MAP.md`
|
||||
refresh, AGENTS.md Gotcha #6 update, operator runbook)
|
||||
|
||||
**B6 was removed post-Finding-1 resolution** (Outcome A — the strict
|
||||
2-col `UNIQUE(user_id, card_id)` is not present on prod; the canonical
|
||||
3-col `UNIQUE(user_id, card_id, is_foil)` from `initial-schema` is
|
||||
what fresh envs already get). No migration is needed. The brief
|
||||
numbering preserves the original gap (B1-B5 + B7) so cross-references
|
||||
to "B6" in prior drafts of this convoy file remain unambiguous (they
|
||||
point to the removed brief).
|
||||
|
||||
Rationale:
|
||||
1. **Independence.** Each of B1-B6 writes a new file under `migrations/`
|
||||
with a fresh timestamp; the files don't overlap, so B1-B6 are
|
||||
trivially parallel (subject to timestamp ordering — see slice
|
||||
dependencies block below).
|
||||
2. **Reviewability.** Each PR is one migration + one optional
|
||||
`docs/SCHEMA_MAP.md` section update; reviewer can verify against
|
||||
the historical script in a single sitting.
|
||||
3. **Rollback granularity.** If B5's user-profile migration is found
|
||||
buggy post-merge, the other 5 migrations are unaffected — they all
|
||||
`pgmigrations`-row independently.
|
||||
4. **Estimated LOC per brief stays under 400.** B5 is the largest
|
||||
(~250 LOC of SQL across 13 ALTERs + 2 CREATE TABLE + 6 CHECKs + 6
|
||||
indexes) — comfortably under budget.
|
||||
|
||||
Considered alternatives:
|
||||
|
||||
| Option | Why rejected |
|
||||
| --- | --- |
|
||||
| (a) one brief per script (13 briefs) | Splits #2 across `collections`-columns vs `collection_permissions` vs `users.is_pending` artificially. Pads review surface 2x. |
|
||||
| (c) one DDL + one DML + one verification brief (3 briefs) | A single DDL brief would be a 500+ LOC mega-migration. Hard to review, hard to rollback. |
|
||||
| (d) single PR | Missed-DDL count >> 1; rejected by spec. |
|
||||
|
||||
### D2 — Idempotency pattern: raw `pgm.sql(...)` with `IF [NOT] EXISTS` guards
|
||||
|
||||
**Ratified: raw `pgm.sql(...)`-style SQL matching `1779853647564_initial-schema.js`'s pattern, every statement guarded with `IF NOT EXISTS` (for CREATE) or `IF EXISTS` (for DROP).**
|
||||
|
||||
Rationale:
|
||||
1. **Style consistency.** The five existing migrations all use
|
||||
`pgm.sql()`. Mixing `pgm.createTable()` helpers would introduce a
|
||||
second pattern for no operational benefit.
|
||||
2. **Verbatim SQL transparency.** The reviewer can grep the new
|
||||
migration's SQL string against the historical script's SQL string
|
||||
and confirm byte-equivalent intent.
|
||||
3. **Idempotency.** Every CREATE / ALTER ADD COLUMN / CREATE INDEX
|
||||
statement uses the appropriate `IF NOT EXISTS` guard so re-running
|
||||
against prod is a documented no-op. CHECK constraints don't accept
|
||||
`IF NOT EXISTS` directly — wrap in a `DO $$ BEGIN ... EXCEPTION
|
||||
WHEN duplicate_object THEN NULL; END $$;` block (matching the
|
||||
historical script's try/catch pattern).
|
||||
|
||||
`node-pg-migrate` helpers (`pgm.createTable`, `pgm.addColumns`) would
|
||||
work fine technically, but the existing migration corpus is 100% raw
|
||||
SQL. Optimize for review uniformity.
|
||||
|
||||
### D3 — Drift detection: option (a) — assume change is in prod, add a migration to bring fresh envs to parity
|
||||
|
||||
**Ratified: (a) with a documented "evidence" trail per script in the Inventory section above.**
|
||||
|
||||
For every script in the **M** classification, the assumption is that
|
||||
the script ran successfully against prod at some point and its DDL is
|
||||
now baked into the prod schema. Evidence supporting this assumption:
|
||||
|
||||
- `docs/SCHEMA_MAP.md` (last reviewed 2026-05-22) documents all of these
|
||||
columns/tables as live.
|
||||
- Runtime code in `pages/api/**` reads/writes `user_favorites`,
|
||||
`collection_permissions`, `collection_activity`, `user_settings`,
|
||||
`user_avatars`, `users.first_name`, `users.username`, `users.bio`,
|
||||
`users.avatar_url`, `users.theme`, `users.language`,
|
||||
`collections.visibility`, `collections.tcg`, `collections.tags`,
|
||||
`collections.slug`, `collections.image` — confirmed via grep
|
||||
(`pages/api/user/settings.js`, `pages/api/user/profile.js`,
|
||||
`pages/api/favorites.js`, `pages/api/invite/{accept,decline}.js`,
|
||||
`pages/api/collections/[identifier]/permissions.js`, etc.).
|
||||
- Each historical script is itself idempotent (`ADD COLUMN IF NOT
|
||||
EXISTS`), so prod-vs-fresh divergence is the live state.
|
||||
|
||||
For Finding 1 (UNIQUE constraint conflict), Finding 4 (system-coll
|
||||
backfill), and Finding 5 (seed wipes): per the recommendation in the
|
||||
parent prompt, halt-and-ask is reserved for destructive changes. (1)
|
||||
qualifies (DROP CONSTRAINT) → halt-and-ask. (4) is operationally
|
||||
benign (no DROP) → defer to follow-up. (5) is destructive but the
|
||||
recommended choice is "don't fold into migrations at all" — D4 below.
|
||||
|
||||
### D4 — Seed scripts: option (a) — leave alone
|
||||
|
||||
**Ratified: dev-fixture seed scripts stay out of the migration history.**
|
||||
|
||||
`seed-collections-alice-bob.js` and `seed-collections-with-cards.js`
|
||||
are dev-fixture loaders tied to `alice@tcgvault.com` /
|
||||
`bob@tcgvault.com` (which only exist in `scripts/create-test-users.js`,
|
||||
gated post-`purge-weak-creds-from-helpers` behind `TEST_USERS_PASSWORD`).
|
||||
They:
|
||||
|
||||
- Wipe destructive collection data (incompatible with any env with real users).
|
||||
- Reference Disney/Lorcana sample art URLs (`example.com/elsa.jpg`).
|
||||
- Are clearly UI-demo fodder.
|
||||
|
||||
They have no place in `setup-db`'s migrate pipeline. They will be
|
||||
retired (or moved to `scripts/historical/`) by the queued
|
||||
`retire-graveyard-scripts-after-audit` convoy.
|
||||
|
||||
If multiple developers feel friction managing dev-fixture state in
|
||||
the future, surface a separate `consolidate-dev-seeds` follow-up
|
||||
that designs a non-destructive `npm run seed:dev` flow keyed off a
|
||||
fresh DB. Not surfaced from this convoy because no friction has been
|
||||
reported yet.
|
||||
|
||||
### D5 — Verification: option (a) — manual operator runbook
|
||||
|
||||
**Ratified: post-merge manual verification by spinning up a fresh
|
||||
Neon branch + running `npm run setup-db` + diffing schema against
|
||||
prod.**
|
||||
|
||||
Automated CI verification belongs to the queued `wire-migrate-into-ci`
|
||||
convoy and is out of scope here. The manual runbook will live in this
|
||||
convoy file's "Verification plan" section (below) and be promoted to
|
||||
`docs/operations/RECONCILE-VERIFICATION.md` by B7.
|
||||
|
||||
### D6 — `scripts/migrations/2026-05-24-rename-admin-email.js`: option (b) — leave where it is
|
||||
|
||||
**Ratified: do not move into `migrations/`.**
|
||||
|
||||
The lone pre-tool migration sits at `scripts/migrations/2026-05-24-rename-admin-email.js`
|
||||
and was applied to every long-lived env at `pick-a-name` time
|
||||
(2026-05-24). Moving it into `migrations/` would require backfilling a
|
||||
`pgmigrations` row on every existing env, which is operationally
|
||||
risky for zero functional benefit (the migration is already applied;
|
||||
the runtime never re-checks it).
|
||||
|
||||
For fresh envs, the migration is a no-op (the seed admin row is
|
||||
already created at `admin@deckhearth.com` by post-rename
|
||||
`scripts/setup-neon-db.js`; there's no `@tcgvault.com` row to rename).
|
||||
|
||||
Document the rationale in B7's `docs/SCHEMA_MAP.md` update + a brief
|
||||
note in AGENTS.md Gotcha #4's "Rotation script" subsection. If a
|
||||
future fresh-env onboarding ever tries to roll back to pre-rename
|
||||
state, surface `fold-rename-admin-email-into-migrations` as a
|
||||
follow-up.
|
||||
|
||||
### D7 — `pgmigrations` table state on fresh envs: no special handling required
|
||||
|
||||
**Ratified: rely on `node-pg-migrate`'s standard sequential apply.**
|
||||
|
||||
On a fresh Neon branch, `npm run migrate up` will run all migrations
|
||||
in timestamp order:
|
||||
|
||||
1. `1779853647564_initial-schema` (7 bootstrap tables)
|
||||
2. `1779853647565_add-pg-trgm-card-name-index`
|
||||
3. `1779853647566_add-scan-tables`
|
||||
4. `1779908094455_add-user-cards-scan-image-url`
|
||||
5. `1780378340194_system-collection-description`
|
||||
6. **NEW: B1** — cards columns (quantity, favorited)
|
||||
7. **NEW: B2** — collections columns (visibility, tcg, tags, slug, slug index/constraint, image)
|
||||
8. **NEW: B3** — collaboration tables (collection_permissions, collection_activity, users.is_pending, 4 indexes)
|
||||
9. **NEW: B4** — favorites system (user_favorites + 4 indexes)
|
||||
10. **NEW: B5** — user profile reconciliation (15 ALTER-ADD-COLUMN + 2 CREATE TABLE + 6 CHECK + 6 indexes)
|
||||
|
||||
Each new migration is additive against the post-initial-schema state
|
||||
that prior migrations leave behind; no inter-migration dependencies
|
||||
crossed within this convoy.
|
||||
|
||||
Audited ordering risks for the new migrations:
|
||||
|
||||
- B1 depends on `cards` (initial-schema) ✅
|
||||
- B2 depends on `collections` (initial-schema) ✅
|
||||
- B3 depends on `collections` + `users` (initial-schema) ✅
|
||||
- B4 depends on `users` (initial-schema) ✅
|
||||
- B5 depends on `users` (initial-schema) ✅
|
||||
|
||||
For long-lived envs that already have all post-historical columns:
|
||||
every new migration is a documented no-op due to `IF NOT EXISTS`
|
||||
guards. The only state change is the `pgmigrations` row insertion.
|
||||
|
||||
## Brief outline
|
||||
|
||||
Six implementer briefs. Each B1-B5 ships exactly one new file under
|
||||
`migrations/<timestamp>_<slug>.js`. B7 updates docs only. Implementer
|
||||
briefs are drafted under `.convoys/reconcile-historical-add-scripts/brief-<N>-<slug>.md`.
|
||||
|
||||
| Brief | Title | Files (new) | Depends on | Est. LOC | Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| B1 | Reconcile cards columns | `migrations/1781000000001_reconcile-cards-columns.js` | — | ~40 | Captures script #1; script #7 already captured by initial-schema (verify & document in PR body) |
|
||||
| B2 | Reconcile collections columns | `migrations/1781000000002_reconcile-collections-columns.js` | — | ~120 | Captures #2 (collections half: visibility/tcg/tags), #3 (slug + index + CHECK), #5 (image). Defer slug backfill DML — generating slugs on a fresh env is moot. |
|
||||
| B3 | Reconcile collaboration tables | `migrations/1781000000003_reconcile-collaboration-tables.js` | — | ~130 | Captures #2 (collaboration half: collection_permissions, collection_activity, users.is_pending, 4 indexes). Defer owner-permission backfill DML — fresh envs have no pre-existing collections needing backfill. |
|
||||
| B4 | Reconcile favorites system | `migrations/1781000000004_reconcile-favorites-system.js` | — | ~50 | Captures #4 (user_favorites + 4 indexes). |
|
||||
| B5 | Reconcile user profile | `migrations/1781000000005_reconcile-user-profile.js` | — | ~250 | Captures #8 ∪ #9 (deduplicated; both add columns coexist in prod). Includes user_settings, user_avatars, 6 CHECK constraints (wrapped in `DO $$ EXCEPTION` blocks for idempotency), 6 indexes. Defer defaults-backfill UPDATE — column DEFAULTs handle it. |
|
||||
| ~~B6~~ | ~~Reconcile user_cards / collection_cards UNIQUE constraints~~ | ~~removed~~ | — | 0 | **REMOVED 2026-06-14 — Finding 1 RESOLVED as Outcome A.** The strict 2-col `UNIQUE(user_id, card_id)` is not present on prod; the canonical 3-col tuple is already on fresh envs via `initial-schema`. Documented in Drift Finding 1 + B7's SCHEMA_MAP update; no migration written. |
|
||||
| B7 | Documentation + verification | `docs/SCHEMA_MAP.md` (update); `docs/MIGRATION_VERIFICATION_RUNBOOK.md` (new); `AGENTS.md` (Gotcha #6 audit); `.convoys/ship-readiness.md` (flip queued entry) | B1-B5 merged | ~150 | SCHEMA_MAP smell-list updates per Findings 1-3. Verification runbook (see § Verification plan below). AGENTS.md Gotcha #6 already RESOLVED post-migration-tool; verify and leave alone if accurate. ship-readiness.md "Queued convoys" → flip this convoy entry to RESOLVED + unblock `retire-graveyard-scripts-after-audit` + add `unify-user-avatar-column` + `drop-dead-cards-columns` follow-ups. |
|
||||
|
||||
Per-brief acceptance criteria (sketch — formalized in each brief file):
|
||||
|
||||
- Each migration file has a `down()` that **throws** with a clear message
|
||||
(these are reconciliation migrations; the prod schema state is the
|
||||
source of truth and rolling back would create inconsistency).
|
||||
- Each migration's SQL is **byte-equivalent in intent** to the
|
||||
historical script's SQL (per-statement comments cite the script
|
||||
and line range).
|
||||
- Re-running `npm run migrate up` against any current long-lived env
|
||||
is a no-op (all guards trigger).
|
||||
- `npm run migrate up` against a fresh Neon branch followed by the
|
||||
verification runbook (D5) confirms structural parity with prod.
|
||||
|
||||
### Slice dependencies (multitask-ready)
|
||||
|
||||
```yaml
|
||||
slice_dependencies:
|
||||
- brief: 1
|
||||
depends_on: []
|
||||
files: [migrations/1781000000001_reconcile-cards-columns.js]
|
||||
- brief: 2
|
||||
depends_on: []
|
||||
files: [migrations/1781000000002_reconcile-collections-columns.js]
|
||||
- brief: 3
|
||||
depends_on: []
|
||||
files: [migrations/1781000000003_reconcile-collaboration-tables.js]
|
||||
- brief: 4
|
||||
depends_on: []
|
||||
files: [migrations/1781000000004_reconcile-favorites-system.js]
|
||||
- brief: 5
|
||||
depends_on: []
|
||||
files: [migrations/1781000000005_reconcile-user-profile.js]
|
||||
# brief 6 removed — Finding 1 RESOLVED as Outcome A; timestamp 1781000000006 is unused
|
||||
- brief: 7
|
||||
depends_on: [1, 2, 3, 4, 5]
|
||||
files:
|
||||
- docs/SCHEMA_MAP.md
|
||||
- docs/MIGRATION_VERIFICATION_RUNBOOK.md
|
||||
- AGENTS.md
|
||||
- .convoys/ship-readiness.md
|
||||
```
|
||||
|
||||
**Timestamp coordination.** Each B1-B5 writes a
|
||||
`migrations/<timestamp>_*.js` file with a pre-assigned timestamp
|
||||
(reservation token, not literal `Date.now()`). Pre-assigned
|
||||
timestamps avoid the parallel-implementer collision risk documented
|
||||
in `scaffold-nextjs-app` retro recommendation #4. The brief frontmatter
|
||||
in each `.convoys/reconcile-historical-add-scripts/brief-<N>-*.md`
|
||||
file declares the exact path; implementers MUST use that exact
|
||||
filename (not `npm run migrate create`, which would `Date.now()`).
|
||||
|
||||
## Verification plan (D5 operator runbook)
|
||||
|
||||
To verify the reconstructed migration history produces parity with
|
||||
prod, after B1-B6 merge:
|
||||
|
||||
```bash
|
||||
# 1. Snapshot prod's structural shape (run against prod POSTGRES_URL)
|
||||
# Schema-only dump, no data, no owner/ACL noise
|
||||
POSTGRES_URL=<prod-url> pg_dump --schema-only --no-owner --no-acl \
|
||||
--schema=public > /tmp/prod-schema.sql
|
||||
|
||||
# 2. Create a clean Neon branch from EMPTY (no parent branch) and onboard via setup-db
|
||||
# (use the Neon dashboard or `neon branches create --empty`)
|
||||
POSTGRES_URL=<fresh-branch-url> \
|
||||
ADMIN_INITIAL_PASSWORD=$(openssl rand -base64 24) \
|
||||
npm run setup-db
|
||||
|
||||
# 3. Snapshot the fresh branch's structural shape
|
||||
POSTGRES_URL=<fresh-branch-url> pg_dump --schema-only --no-owner --no-acl \
|
||||
--schema=public > /tmp/fresh-schema.sql
|
||||
|
||||
# 4. Diff. Expected differences are limited to:
|
||||
# - constraint/index NAME differences (autogen tuple-UNIQUE names vs explicit names)
|
||||
# - column-ORDER differences (prod has columns in historical-script-ALTER order;
|
||||
# fresh envs have them in migration-order)
|
||||
# Both are semantically irrelevant. Material differences = bug; flag and reopen.
|
||||
diff <(sort /tmp/prod-schema.sql) <(sort /tmp/fresh-schema.sql)
|
||||
```
|
||||
|
||||
Supplementary information-schema spot-checks for the highest-risk surfaces:
|
||||
|
||||
```sql
|
||||
-- Every column on every table
|
||||
SELECT table_name, column_name, data_type, is_nullable, column_default
|
||||
FROM information_schema.columns
|
||||
WHERE table_schema = 'public'
|
||||
ORDER BY table_name, ordinal_position;
|
||||
|
||||
-- Every constraint
|
||||
SELECT table_name, constraint_name, constraint_type
|
||||
FROM information_schema.table_constraints
|
||||
WHERE table_schema = 'public'
|
||||
ORDER BY table_name, constraint_name;
|
||||
|
||||
-- Every index
|
||||
SELECT tablename, indexname, indexdef
|
||||
FROM pg_indexes
|
||||
WHERE schemaname = 'public'
|
||||
ORDER BY tablename, indexname;
|
||||
```
|
||||
|
||||
Run both against prod and fresh-branch; the column-count + constraint-count
|
||||
+ index-count totals should match exactly. Mismatch = bug.
|
||||
|
||||
B7 will move this runbook to `docs/operations/RECONCILE-VERIFICATION.md`
|
||||
and link it from `AGENTS.md` Gotcha #6 + `migration-tool` § R1's
|
||||
"resolved-by" note.
|
||||
|
||||
## Risks
|
||||
|
||||
### R1 — Missed DDL that is NOT actually in prod ("ghost migration")
|
||||
|
||||
The assumption (D3) is that every historical script ran successfully
|
||||
against every long-lived env. If a script in fact failed silently
|
||||
mid-execution on prod (e.g. `add-collaboration-features.js`'s
|
||||
`CREATE INDEX idx_collections_visibility` errored partway through),
|
||||
prod might not actually have that index even though SCHEMA_MAP says
|
||||
it does.
|
||||
|
||||
**Mitigation:** the verification plan (D5) catches this. The fresh-env
|
||||
`pg_dump` would contain the index; prod's `pg_dump` would not; the
|
||||
diff would surface it. If found, operator decides: (a) the script's
|
||||
intent was sound, apply the missed DDL to prod manually with
|
||||
`POSTGRES_URL=<prod> psql -c "CREATE INDEX IF NOT EXISTS ..."`; or
|
||||
(b) the index is unwanted, drop it from the new migration and document.
|
||||
|
||||
### R2 — `pgmigrations` row state on existing prod envs
|
||||
|
||||
After this convoy merges, an operator running `npm run migrate up`
|
||||
against prod will see 6 new migrations apply (B1-B6) as no-ops (every
|
||||
guarded statement triggers `IF [NOT] EXISTS`-skip). Six new
|
||||
`pgmigrations` rows record successful application.
|
||||
|
||||
If for some reason a long-lived prod env genuinely lacks one of the
|
||||
historical-script columns (Risk R1 above), the corresponding migration
|
||||
will **add** that column on apply, no-op-ing the others. The
|
||||
`pgmigrations` row records success; subsequent applies are no-ops.
|
||||
This is the correct behavior, but the operator should run the
|
||||
verification plan post-apply to confirm.
|
||||
|
||||
**Mitigation:** the verification plan covers prod-vs-fresh diff after
|
||||
B1-B6 land. Run it once on each prod-shaped env immediately after
|
||||
merge.
|
||||
|
||||
### R3 — Ordering: new migration depends on prior schema-state that doesn't exist at its execution point
|
||||
|
||||
Audited in D7. All B1-B6 dependencies on prior tables (`cards`,
|
||||
`collections`, `users`, `user_cards`, `collection_cards`) are
|
||||
satisfied by `initial-schema` (timestamp `1779853647564`, runs first
|
||||
on fresh envs). No B-to-B inter-dependency required.
|
||||
|
||||
### R4 — Seed scripts depend on test users that don't exist on fresh envs
|
||||
|
||||
Out of scope (D4). The two seed scripts are dev fixtures and are not
|
||||
folded into migrations. Test users (`alice@`, `bob@`) are managed by
|
||||
`scripts/create-test-users.js` (post-`purge-weak-creds-from-helpers`,
|
||||
gated behind `TEST_USERS_PASSWORD`). Surface as `consolidate-dev-seeds`
|
||||
follow-up only if a developer reports friction.
|
||||
|
||||
### R5 — CHECK constraint reapplication on prod is loud
|
||||
|
||||
`add-user-profile-fields.js` wraps each CHECK constraint ADD in a
|
||||
JS try/catch that swallows `already exists` errors. Postgres doesn't
|
||||
accept `ADD CONSTRAINT ... IF NOT EXISTS` for CHECK; the SQL has to be
|
||||
wrapped in `DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL END
|
||||
$$;`. B5's migration must use the exception-handling form so reapply
|
||||
against prod is silent. Implementer brief will spell this out.
|
||||
|
||||
### R6 — Mid-convoy timestamp collision when implementers spawn in parallel
|
||||
|
||||
B1-B5 are mutually independent and can dispatch via `/multitask`.
|
||||
Pre-assigned timestamps (D7 table) avoid the `Date.now()`-collision
|
||||
risk that bit the `scaffold-nextjs-app` convoy. Each implementer
|
||||
brief will name its file's exact timestamp; deviations require a
|
||||
re-plan.
|
||||
|
||||
### R7 — Operator approval lag on Finding 1 (RESOLVED 2026-06-14)
|
||||
|
||||
Originally a risk because B6 was gated on operator decision. Finding 1
|
||||
RESOLVED as Outcome A; B6 removed. No lag risk remains.
|
||||
|
||||
## Follow-ups
|
||||
|
||||
Surfaced by this convoy:
|
||||
|
||||
- **`retire-graveyard-scripts-after-audit`** (priority: **P3 polish — now
|
||||
UNBLOCKED** once this convoy lands). Once B1-B6 capture every
|
||||
missed historical DDL into the migration history, the 13 historical
|
||||
scripts can be safely deleted or moved to `scripts/historical/` and
|
||||
the corresponding no-go-zones rule line can be removed. Documented
|
||||
in `.convoys/migration-tool.md` § Follow-ups; ship-readiness.md
|
||||
"Queued convoys" entry; AGENTS.md Gotcha #6 cross-reference.
|
||||
- **`wire-migrate-into-ci`** (priority: P2 CI infra — pre-existing).
|
||||
Adds a CI job that runs `npm run migrate up` against a test DB on
|
||||
every PR. This convoy's verification plan (D5) is the manual
|
||||
precursor; the CI job is the automation upgrade. Already on the
|
||||
follow-up list per `migration-tool` § Follow-ups + ship-readiness.md
|
||||
"Queued convoys".
|
||||
- **`unify-user-avatar-column`** (priority: P3 hygiene — NEW). Driven
|
||||
by Finding 2. Two redundant TEXT columns
|
||||
(`users.profile_image_url` and `users.avatar_url`) coexist; pick one
|
||||
canonical column, migrate the other's data, drop the loser, update
|
||||
runtime readers. Requires a query-trace audit first.
|
||||
- **`drop-dead-cards-columns`** (priority: P3 hygiene — NEW). Driven
|
||||
by Finding 3. `cards.quantity` and `cards.favorited` are documented
|
||||
as unused. After a query-trace audit confirms zero readers, ship a
|
||||
migration that DROPs them (with proper `down()` recreate).
|
||||
- ~~**`add-system-collection-on-register`**~~ — **WITHDRAWN 2026-06-14**, Finding 4 RESOLVED. Verified the register hook exists at `pages/api/auth/register.js:97-119`.
|
||||
- **`fold-rename-admin-email-into-migrations`** (priority: P3 polish,
|
||||
conditional — NEW per D6). Only surface if a future fresh-env
|
||||
onboarding needs the rename migration applied in order. Until then,
|
||||
the script-shaped migration at
|
||||
`scripts/migrations/2026-05-24-rename-admin-email.js` is left in
|
||||
place per D6.
|
||||
- ~~**`unify-user-cards-foil-tracking`**~~ — **WITHDRAWN 2026-06-14**, Finding 1 RESOLVED as Outcome A (not Outcome B). The 3-col tuple stays canonical; no foil-tracking redesign needed.
|
||||
|
||||
Not surfaced (no friction yet):
|
||||
|
||||
- `consolidate-dev-seeds` — D4 noted this can wait until multiple
|
||||
developers report friction with the current per-script dev-fixture
|
||||
loaders.
|
||||
|
||||
## As-shipped
|
||||
|
||||
Six implementer briefs (B1–B6) landed between 2026-06-14 and 2026-07-06.
|
||||
Brief 7 (documentation + verification runbook) closed the convoy on
|
||||
2026-08-15 — a post-hoc docs-only pass delayed by an operator-initiated
|
||||
pause on a self-hosted runner infra issue that did not affect migration
|
||||
content correctness.
|
||||
|
||||
### Per-brief delivery
|
||||
|
||||
| Brief | PR | Squash | Merged | Migration file |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| B1 cards columns | #148 | `a35ce01` | 2026-06-14 | `migrations/1781442330001_reconcile-cards-columns.js` |
|
||||
| B2 collections columns | #150 | `e8619c5` | 2026-06-14 | `migrations/1781442330002_reconcile-collections-columns.js` |
|
||||
| B3 collaboration tables | #151 | `15e02ee` | 2026-07-06 | `migrations/1781000000003_reconcile-collaboration-tables.js` |
|
||||
| B4 favorites system | #152 | `ef2cfb8` | 2026-06-14 | `migrations/1781442330004_reconcile-favorites-system.js` |
|
||||
| B5 user profile | #153 | `ee7da9a` | 2026-06-14 | `migrations/1781442330005_reconcile-user-profile.js` |
|
||||
| B6 user_cards UNIQUE | #149 | `40402eb` | 2026-06-14 | `migrations/1781442330006_reconcile-user-cards-unique.js` |
|
||||
| B7 docs + runbook | _(this PR)_ | — | 2026-08-15 | _(no migration — docs only)_ |
|
||||
|
||||
All six implementer PRs were green at merge on the (then-flaky) self-hosted
|
||||
axiom runner pool.
|
||||
|
||||
### Reservation-timestamp rename (`ec9bb2b`)
|
||||
|
||||
The architect pre-assigned timestamps `1781000000001` through
|
||||
`1781000000006` to avoid `Date.now()` collisions during parallel
|
||||
implementer dispatch. Commit `ec9bb2b` (`feat(catalog): unified multi-game
|
||||
bulk sync + schema map update`) renamed all except B3 to
|
||||
`1781442330001`–`1781442330006` so they run **after** the catalog-sync
|
||||
migrations that landed in the same period:
|
||||
|
||||
- `1781440700404_add-scryfall-bulk-columns`
|
||||
- `1781440721350_add-tagger-tables`
|
||||
- `1781442175729_normalize-lorcana-set-codes`
|
||||
- `1781442329511_add-catalog-sync-log`
|
||||
|
||||
B3 kept its original `1781000000003` timestamp because it merged after the
|
||||
rename commit. The rename is filename-only; migration `up()` content is
|
||||
identical.
|
||||
|
||||
### B6 deviation from architect plan
|
||||
|
||||
The architect's gate-1 plan collapsed Finding 1 (Outcome A) into B7 as a
|
||||
doc-only note. Implementers shipped B6 anyway as a tiny belt-and-suspenders
|
||||
migration (`1781442330006_reconcile-user-cards-unique.js`) that:
|
||||
|
||||
- Confirms the canonical 3-column `UNIQUE(user_id, card_id, is_foil)` from
|
||||
`initial-schema` is present.
|
||||
- Drops the historical 2-column `user_cards_user_card_unique` constraint if
|
||||
any env ran `fix-user-cards-constraints.js`.
|
||||
|
||||
The migration is a no-op on prod (Outcome A already holds) but guards
|
||||
future envs that might have the stricter 2-col variant.
|
||||
|
||||
### Verification
|
||||
|
||||
Manual operator runbook for confirming fresh-env vs prod schema parity:
|
||||
[`docs/MIGRATION_VERIFICATION_RUNBOOK.md`](../docs/MIGRATION_VERIFICATION_RUNBOOK.md)
|
||||
(per architect Decision D5). Automated CI verification remains queued as
|
||||
`wire-migrate-into-ci`.
|
||||
|
||||
### B7 deviation from spec
|
||||
|
||||
B7 shipped ~2 months post-hoc (2026-08-15) rather than immediately after
|
||||
B1–B6. The delay was operator-initiated (runner-infra pause) and did not
|
||||
block migration correctness — only documentation closure.
|
||||
|
|
@ -1,228 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
files:
|
||||
- migrations/1781000000001_reconcile-cards-columns.js
|
||||
---
|
||||
|
||||
# Brief 1: Reconcile `cards` columns into migration history
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Capture the DDL added by `scripts/add-card-columns.js` (the `cards.quantity` + `cards.favorited` columns) into a single new `node-pg-migrate` migration so a brand-new Neon branch ends up with both columns after `npm run setup-db`.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `migrations/1781000000001_reconcile-cards-columns.js` — **new**
|
||||
|
||||
## Source script (read-only audit reference; DO NOT EDIT — no-go-zone)
|
||||
|
||||
`scripts/add-card-columns.js` lines 22-33 (verbatim):
|
||||
|
||||
```js
|
||||
await sql`
|
||||
ALTER TABLE cards
|
||||
ADD COLUMN IF NOT EXISTS quantity INTEGER DEFAULT 0
|
||||
`;
|
||||
// ...
|
||||
await sql`
|
||||
ALTER TABLE cards
|
||||
ADD COLUMN IF NOT EXISTS favorited BOOLEAN DEFAULT false
|
||||
`;
|
||||
```
|
||||
|
||||
**Sibling script `scripts/add-updated-at-column.js`** is already captured by `migrations/1779853647564_initial-schema.js` (the `cards` `CREATE TABLE` at lines 45-69 already declares `updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP`). Do NOT add an ALTER for `updated_at` — it would be redundant noise on `pgmigrations`. Mention this in the PR body so reviewers don't ask.
|
||||
|
||||
## Target migration file
|
||||
|
||||
Path: `migrations/1781000000001_reconcile-cards-columns.js`
|
||||
|
||||
Contents:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Reconcile historical `scripts/add-card-columns.js` into the migration
|
||||
* history. Adds `cards.quantity` and `cards.favorited` columns so a
|
||||
* brand-new Neon branch ends up with the same shape that prod has had
|
||||
* since the historical script's one-shot run.
|
||||
*
|
||||
* Both columns are flagged as **unused** in docs/SCHEMA_MAP.md
|
||||
* § "Known schema smells" #3 — `quantity` lives on `user_cards`,
|
||||
* `favorited` lives on `user_favorites`. They're added here for
|
||||
* fresh-env parity with prod. A follow-up `drop-dead-cards-columns`
|
||||
* convoy (queued, P3 hygiene) will drop both columns once a query-trace
|
||||
* audit confirms zero runtime readers.
|
||||
*
|
||||
* Idempotent: re-running against any long-lived prod env is a no-op
|
||||
* because both ALTERs use IF NOT EXISTS.
|
||||
*
|
||||
* Note: `scripts/add-updated-at-column.js` (the sibling historical
|
||||
* script in the same convoy) is NOT reconciled here because
|
||||
* `cards.updated_at` is already declared in
|
||||
* `migrations/1779853647564_initial-schema.js`'s `CREATE TABLE cards`
|
||||
* (line 67). No further work needed for that script.
|
||||
*
|
||||
* @type {import('node-pg-migrate').ColumnDefinitions | undefined}
|
||||
*/
|
||||
export const shorthands = undefined;
|
||||
|
||||
/**
|
||||
* @param {import('node-pg-migrate').MigrationBuilder} pgm
|
||||
*/
|
||||
export const up = (pgm) => {
|
||||
pgm.sql(`
|
||||
ALTER TABLE cards
|
||||
ADD COLUMN IF NOT EXISTS quantity INTEGER DEFAULT 0;
|
||||
|
||||
ALTER TABLE cards
|
||||
ADD COLUMN IF NOT EXISTS favorited BOOLEAN DEFAULT false;
|
||||
`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Down-migration intentionally throws. Dropping these columns on
|
||||
* long-lived envs requires the `drop-dead-cards-columns` convoy's
|
||||
* query-trace audit — bypassing it via a casual rollback risks
|
||||
* dropping data on prod. Use `drop-dead-cards-columns` when ready.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
export const down = () => {
|
||||
throw new Error(
|
||||
'[migration:1781000000001_reconcile-cards-columns] Down not supported. ' +
|
||||
'Dropping cards.quantity / cards.favorited belongs to the queued ' +
|
||||
'drop-dead-cards-columns convoy, which performs a query-trace audit ' +
|
||||
'before the DROP. Do not rollback this migration directly.'
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/db-and-schema.mdc` § "Schema source of truth" — `migrations/` is the canonical home for schema changes; one column-group per migration.
|
||||
- `.cursor/rules/no-go-zones.mdc` — `scripts/add-card-columns.js` is append-only history. **Do not edit it.**
|
||||
- Style: match the existing migrations under `migrations/`. Use raw `pgm.sql(...)` template literals (the `migration-tool` convoy ratified this in D2 of `.convoys/reconcile-historical-add-scripts.md`).
|
||||
- ESM exports (`export const up = ...`, `export const down = ...`); no `module.exports`. The repo is `"type": "module"` per `package.json` line 5.
|
||||
- Use `IF NOT EXISTS` on every ALTER — idempotent re-apply is a documented requirement of this convoy.
|
||||
- Add a JSDoc docstring at the top of the file explaining what's being reconciled, citing the source script + the convoy file.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `migrations/1781000000001_reconcile-cards-columns.js` exists with the exact filename above (the timestamp `1781000000001` is the reservation token assigned by the architect — do NOT use `npm run migrate create`, which would call `Date.now()` and assign a different timestamp).
|
||||
- [ ] The file's `up()` adds both columns via `IF NOT EXISTS`.
|
||||
- [ ] The file's `down()` throws with a clear message pointing at the `drop-dead-cards-columns` follow-up.
|
||||
- [ ] The file's docstring cites `scripts/add-card-columns.js` and `.convoys/reconcile-historical-add-scripts.md`.
|
||||
- [ ] `node --check migrations/1781000000001_reconcile-cards-columns.js` passes (syntactic validity).
|
||||
- [ ] `node -e "import('./migrations/1781000000001_reconcile-cards-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined` (module loads cleanly).
|
||||
- [ ] `npm run lint` exits clean against the baseline (no new lint errors introduced by this file).
|
||||
- [ ] `npm run test:run` reports 21/21 passing (no test surface changes).
|
||||
- [ ] The PR body documents that `add-updated-at-column.js` is already captured by `initial-schema` (per the source-script section above) and explains why no second migration is added.
|
||||
|
||||
## Verification
|
||||
|
||||
Run the following from the convoy worktree (`tcg-vault-worktrees/reconcile-historical-add-scripts/`) BEFORE opening the PR:
|
||||
|
||||
```bash
|
||||
node --check migrations/1781000000001_reconcile-cards-columns.js
|
||||
node -e "import('./migrations/1781000000001_reconcile-cards-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Expected:
|
||||
- `node --check` exits 0 with no output.
|
||||
- The `node -e` line prints exactly: `function function undefined`.
|
||||
- `npm run lint` matches the existing baseline (no new errors).
|
||||
- `npm run test:run` reports 21/21 tests passing.
|
||||
|
||||
**Do NOT** run `npm run migrate up` against any environment as part of this brief — that's a post-merge operator step covered by Brief 7's verification runbook.
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
feat(migrations): reconcile add-card-columns into migration history (brief 1/7)
|
||||
|
||||
Captures the DDL effect of scripts/add-card-columns.js (cards.quantity
|
||||
+ cards.favorited columns) into a new node-pg-migrate migration. Both
|
||||
columns are flagged as unused in docs/SCHEMA_MAP.md § "Known schema
|
||||
smells" #3 — added here for fresh-env parity with prod; a follow-up
|
||||
drop-dead-cards-columns convoy will drop them after a query-trace
|
||||
audit.
|
||||
|
||||
Sibling script add-updated-at-column.js is already captured by
|
||||
migrations/1779853647564_initial-schema.js (cards.updated_at is in the
|
||||
CREATE TABLE); no second migration needed.
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B1.
|
||||
Idempotent re-apply (IF NOT EXISTS guards).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `feat(migrations): reconcile add-card-columns into migration history (brief 1/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 1 of the `reconcile-historical-add-scripts` convoy. See
|
||||
[`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
## What this PR does
|
||||
|
||||
Adds `migrations/1781000000001_reconcile-cards-columns.js` — a new
|
||||
`node-pg-migrate` migration that adds two columns to `cards` via
|
||||
`ADD COLUMN IF NOT EXISTS`:
|
||||
|
||||
- `quantity INTEGER DEFAULT 0`
|
||||
- `favorited BOOLEAN DEFAULT false`
|
||||
|
||||
Both columns already exist in long-lived prod environments (added by
|
||||
the historical `scripts/add-card-columns.js`). This migration brings
|
||||
fresh Neon branches to parity so `npm install` → `npm run setup-db`
|
||||
alone produces the prod shape, without manually replaying historical
|
||||
scripts.
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit `scripts/add-card-columns.js` (no-go-zone).
|
||||
- Does **NOT** add a migration for `scripts/add-updated-at-column.js`
|
||||
— `cards.updated_at` is already declared in
|
||||
`migrations/1779853647564_initial-schema.js` line 67.
|
||||
- Does **NOT** edit `scripts/setup-neon-db.js`, `package.json`, README,
|
||||
or AGENTS.md.
|
||||
- Does **NOT** run `npm run migrate up` against any environment (that's
|
||||
the post-merge operator step covered by Brief 7's runbook).
|
||||
- Does **NOT** drop the columns (deferred to follow-up
|
||||
`drop-dead-cards-columns`).
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `node --check migrations/1781000000001_reconcile-cards-columns.js` exits 0
|
||||
- [ ] `node -e "import('./migrations/1781000000001_reconcile-cards-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`
|
||||
- [ ] `npm run lint` matches baseline (no new errors)
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Did not run `npm run migrate up` against any environment in this PR
|
||||
- [ ] Operator post-merge: run the verification runbook from Brief 7 (`docs/MIGRATION_VERIFICATION_RUNBOOK.md` once it lands)
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Source script (no-go-zone, audit reference only): `scripts/add-card-columns.js`
|
||||
- Follow-up after this convoy lands: `drop-dead-cards-columns` (P3 hygiene)
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit `scripts/add-card-columns.js` or any other file under `scripts/` — append-only no-go-zone per `.cursor/rules/no-go-zones.mdc`.
|
||||
- DO NOT edit any other file under `migrations/` — each migration is pinned by its `pgmigrations` row.
|
||||
- DO NOT edit `scripts/setup-neon-db.js`.
|
||||
- DO NOT edit `package.json` (no new deps).
|
||||
- DO NOT edit `AGENTS.md` or `docs/SCHEMA_MAP.md` — that's Brief 7's job.
|
||||
- DO NOT run `npm run migrate up` against any environment.
|
||||
- DO NOT call `npm run migrate create` to scaffold the file — it uses `Date.now()` for the timestamp prefix, which would collide with the architect's pre-assigned reservation tokens for parallel briefs.
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Capturing `cards.quantity` + `cards.favorited` in a single small migration matches the per-table grouping of the convoy's D1 decision and keeps the diff easy to review. Sibling `add-updated-at-column.js` is already captured by `initial-schema`, so reconciling it would create a `pgmigrations` row for zero functional benefit. The columns themselves are dead per SCHEMA_MAP smell #3, but parity with prod is the convoy's success metric — the actual DROP is the `drop-dead-cards-columns` follow-up's responsibility.
|
||||
|
|
@ -1,307 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 2
|
||||
depends_on: []
|
||||
files:
|
||||
- migrations/1781000000002_reconcile-collections-columns.js
|
||||
---
|
||||
|
||||
# Brief 2: Reconcile `collections` columns into migration history
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Capture the `collections`-table DDL added by three historical scripts (`add-collaboration-features.js` columns half, `add-collection-slugs.js`, `add-image-column.js`) into a single new `node-pg-migrate` migration so a brand-new Neon branch ends up with `visibility`, `tcg`, `tags`, `slug` (+ index + CHECK constraint), and `image` columns on `collections` after `npm run setup-db`.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `migrations/1781000000002_reconcile-collections-columns.js` — **new**
|
||||
|
||||
## Source scripts (read-only audit reference; DO NOT EDIT — all three are no-go-zones)
|
||||
|
||||
### `scripts/add-collaboration-features.js` lines 15-20 (collections half only — the `collection_permissions` / `collection_activity` / `users.is_pending` half is Brief 3's scope):
|
||||
|
||||
```js
|
||||
await sql`
|
||||
ALTER TABLE collections
|
||||
ADD COLUMN IF NOT EXISTS visibility VARCHAR(20) DEFAULT 'private',
|
||||
ADD COLUMN IF NOT EXISTS tcg VARCHAR(50) DEFAULT 'MTG',
|
||||
ADD COLUMN IF NOT EXISTS tags TEXT
|
||||
`;
|
||||
```
|
||||
|
||||
Plus the visibility index at lines 77-80:
|
||||
|
||||
```js
|
||||
await sql`
|
||||
CREATE INDEX IF NOT EXISTS idx_collections_visibility
|
||||
ON collections(visibility)
|
||||
`;
|
||||
```
|
||||
|
||||
### `scripts/add-collection-slugs.js` lines 17-99 (relevant DDL only):
|
||||
|
||||
```js
|
||||
// Step 1: Add slug column
|
||||
await sql`
|
||||
ALTER TABLE collections
|
||||
ADD COLUMN IF NOT EXISTS slug VARCHAR(100) UNIQUE
|
||||
`;
|
||||
|
||||
// Step 5: Add unique index
|
||||
await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_collections_slug ON collections(slug)`;
|
||||
|
||||
// Step 6: Add format CHECK constraint
|
||||
await sql`ALTER TABLE collections ADD CONSTRAINT check_slug_format CHECK (slug ~ '^[a-z0-9]([a-z0-9-]*[a-z0-9])?$' AND length(slug) <= 50)`;
|
||||
```
|
||||
|
||||
The script also backfills slugs via per-row UPDATE using `lib/slug-utils.js::generateUniqueSlug` (lines 41-73). **Do NOT fold the backfill DML into this migration.** Fresh envs have no pre-existing `collections` rows to backfill; on prod, the backfill ran once historically. Future migrations that need slug generation should run that logic in application code, not in a migration.
|
||||
|
||||
### `scripts/add-image-column.js` lines 14-17 (entire DDL):
|
||||
|
||||
```js
|
||||
await sql`
|
||||
ALTER TABLE collections
|
||||
ADD COLUMN IF NOT EXISTS image TEXT
|
||||
`;
|
||||
```
|
||||
|
||||
## Target migration file
|
||||
|
||||
Path: `migrations/1781000000002_reconcile-collections-columns.js`
|
||||
|
||||
Contents:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Reconcile three historical scripts that all added columns to the
|
||||
* `collections` table:
|
||||
*
|
||||
* - scripts/add-collaboration-features.js (visibility, tcg, tags +
|
||||
* idx_collections_visibility index) — collections-table half only;
|
||||
* the collection_permissions / collection_activity / users.is_pending
|
||||
* half is reconciled by migrations/1781000000003_reconcile-collaboration-tables.js
|
||||
* - scripts/add-collection-slugs.js (slug + idx_collections_slug
|
||||
* unique index + check_slug_format CHECK constraint)
|
||||
* - scripts/add-image-column.js (image)
|
||||
*
|
||||
* Grouped into one migration per D1 of .convoys/reconcile-historical-add-scripts.md
|
||||
* (one migration per table/feature surface). All historical DDL was
|
||||
* idempotent (ADD COLUMN IF NOT EXISTS / CREATE INDEX IF NOT EXISTS);
|
||||
* this migration preserves that. CHECK constraint adds via a
|
||||
* DO $$ EXCEPTION block because Postgres doesn't accept
|
||||
* ADD CONSTRAINT ... IF NOT EXISTS for CHECK.
|
||||
*
|
||||
* Per-row slug backfill DML from add-collection-slugs.js is intentionally
|
||||
* NOT folded in — fresh envs have no pre-existing collections to
|
||||
* backfill; on prod, the backfill ran once historically and is baked in.
|
||||
*
|
||||
* Notes on adjacent state:
|
||||
* - `is_system_collection` was added by migrations/1780378340194_system-collection-description.js
|
||||
* (and the runtime register hook at pages/api/auth/register.js:97-119
|
||||
* creates the per-user system collection row — Finding 4 RESOLVED in
|
||||
* .convoys/reconcile-historical-add-scripts.md).
|
||||
*
|
||||
* Two-column-visibility smell: `is_public BOOLEAN` (from initial-schema)
|
||||
* and `visibility VARCHAR(20)` (from this migration) coexist on prod.
|
||||
* Surfaced as docs/SCHEMA_MAP.md § "Known schema smells" #2 → queued
|
||||
* `unify-collection-visibility` is OUT OF SCOPE here; this migration
|
||||
* adds `visibility` for parity, nothing more.
|
||||
*
|
||||
* Idempotent re-apply: every statement uses IF NOT EXISTS or the
|
||||
* exception-swallowing DO block.
|
||||
*
|
||||
* @type {import('node-pg-migrate').ColumnDefinitions | undefined}
|
||||
*/
|
||||
export const shorthands = undefined;
|
||||
|
||||
/**
|
||||
* @param {import('node-pg-migrate').MigrationBuilder} pgm
|
||||
*/
|
||||
export const up = (pgm) => {
|
||||
pgm.sql(`
|
||||
ALTER TABLE collections
|
||||
ADD COLUMN IF NOT EXISTS visibility VARCHAR(20) DEFAULT 'private',
|
||||
ADD COLUMN IF NOT EXISTS tcg VARCHAR(50) DEFAULT 'MTG',
|
||||
ADD COLUMN IF NOT EXISTS tags TEXT,
|
||||
ADD COLUMN IF NOT EXISTS slug VARCHAR(100) UNIQUE,
|
||||
ADD COLUMN IF NOT EXISTS image TEXT;
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_collections_visibility
|
||||
ON collections (visibility);
|
||||
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS idx_collections_slug
|
||||
ON collections (slug);
|
||||
|
||||
DO $$
|
||||
BEGIN
|
||||
ALTER TABLE collections
|
||||
ADD CONSTRAINT check_slug_format
|
||||
CHECK (slug ~ '^[a-z0-9]([a-z0-9-]*[a-z0-9])?$' AND length(slug) <= 50);
|
||||
EXCEPTION
|
||||
WHEN duplicate_object THEN NULL;
|
||||
END $$;
|
||||
`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Down-migration intentionally throws. Removing these columns on
|
||||
* long-lived envs would drop user-curated tag / slug / image data
|
||||
* and break the runtime code that reads collections.visibility,
|
||||
* collections.slug, collections.image, collections.tcg, collections.tags.
|
||||
*
|
||||
* If a future schema correction needs to mutate any of these columns,
|
||||
* write a NEW dated migration with a real `down()` — do NOT roll back
|
||||
* this one.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
export const down = () => {
|
||||
throw new Error(
|
||||
'[migration:1781000000002_reconcile-collections-columns] Down not supported. ' +
|
||||
'Dropping collections.visibility / tcg / tags / slug / image would erase ' +
|
||||
'user-curated data and break runtime reads. Write a new dated migration ' +
|
||||
'for any future schema correction.'
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/db-and-schema.mdc` § "Schema source of truth" — one migration per table/feature surface.
|
||||
- `.cursor/rules/no-go-zones.mdc` — all three source scripts are append-only history. **Do not edit any of them.**
|
||||
- Style: raw `pgm.sql(...)` template literals, matching the other migrations under `migrations/`. Per D2 of the convoy file.
|
||||
- ESM exports; `"type": "module"` per `package.json` line 5.
|
||||
- `IF NOT EXISTS` on every ALTER and CREATE INDEX. CHECK constraint wraps in `DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL END $$;` (Postgres doesn't accept `IF NOT EXISTS` directly on CHECK constraints).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `migrations/1781000000002_reconcile-collections-columns.js` exists with the exact filename above (the timestamp `1781000000002` is the reservation token assigned by the architect — do NOT use `npm run migrate create`).
|
||||
- [ ] The file's `up()` adds 5 columns (`visibility`, `tcg`, `tags`, `slug`, `image`) via `IF NOT EXISTS`, creates 2 indexes (`idx_collections_visibility`, unique `idx_collections_slug`) via `IF NOT EXISTS`, and adds the `check_slug_format` CHECK via a `DO $$ EXCEPTION` block.
|
||||
- [ ] The file's `down()` throws with a clear message.
|
||||
- [ ] The file's docstring cites all three source scripts + the convoy file + the visibility smell (#2 in SCHEMA_MAP).
|
||||
- [ ] Per-row slug backfill DML is NOT in the migration (out of scope per the convoy plan).
|
||||
- [ ] `node --check migrations/1781000000002_reconcile-collections-columns.js` passes.
|
||||
- [ ] `node -e "import('./migrations/1781000000002_reconcile-collections-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`.
|
||||
- [ ] `npm run lint` matches the baseline (no new errors).
|
||||
- [ ] `npm run test:run` reports 21/21 passing.
|
||||
|
||||
## Verification
|
||||
|
||||
Run from the convoy worktree BEFORE opening the PR:
|
||||
|
||||
```bash
|
||||
node --check migrations/1781000000002_reconcile-collections-columns.js
|
||||
node -e "import('./migrations/1781000000002_reconcile-collections-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Expected:
|
||||
- `node --check` exits 0 silently.
|
||||
- `node -e` prints `function function undefined`.
|
||||
- `npm run lint` matches baseline.
|
||||
- `npm run test:run` reports 21/21 passing.
|
||||
|
||||
**Do NOT** run `npm run migrate up` against any environment — that's the post-merge operator step covered by Brief 7's verification runbook.
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
feat(migrations): reconcile collections columns into migration history (brief 2/7)
|
||||
|
||||
Captures the DDL effect of three historical scripts into one new
|
||||
node-pg-migrate migration:
|
||||
|
||||
- scripts/add-collaboration-features.js (collections half: visibility,
|
||||
tcg, tags + idx_collections_visibility)
|
||||
- scripts/add-collection-slugs.js (slug + idx_collections_slug unique
|
||||
+ check_slug_format CHECK constraint)
|
||||
- scripts/add-image-column.js (image)
|
||||
|
||||
The collaboration tables half (collection_permissions, collection_activity,
|
||||
users.is_pending) is reconciled separately by Brief 3.
|
||||
|
||||
Per-row slug backfill DML from add-collection-slugs.js is intentionally
|
||||
NOT folded in — fresh envs have no pre-existing collections to backfill.
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B2.
|
||||
Idempotent re-apply (IF NOT EXISTS guards; DO $$ EXCEPTION for CHECK).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `feat(migrations): reconcile collections columns into migration history (brief 2/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 2 of the `reconcile-historical-add-scripts` convoy. See
|
||||
[`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
## What this PR does
|
||||
|
||||
Adds `migrations/1781000000002_reconcile-collections-columns.js` —
|
||||
captures the DDL effect of three historical scripts in a single new
|
||||
`node-pg-migrate` migration:
|
||||
|
||||
- `scripts/add-collaboration-features.js` — collections columns half
|
||||
(`visibility VARCHAR(20)`, `tcg VARCHAR(50)`, `tags TEXT`,
|
||||
`idx_collections_visibility` index)
|
||||
- `scripts/add-collection-slugs.js` — `slug VARCHAR(100) UNIQUE`,
|
||||
`idx_collections_slug` unique index, `check_slug_format` CHECK
|
||||
constraint
|
||||
- `scripts/add-image-column.js` — `image TEXT`
|
||||
|
||||
All ALTERs use `ADD COLUMN IF NOT EXISTS`. The CHECK constraint wraps
|
||||
in a `DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL END $$;`
|
||||
block because Postgres doesn't accept `ADD CONSTRAINT ... IF NOT EXISTS`
|
||||
for CHECK.
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit any of the three source scripts (no-go-zones).
|
||||
- Does **NOT** capture the collaboration tables half of
|
||||
`add-collaboration-features.js` (`collection_permissions`,
|
||||
`collection_activity`, `users.is_pending`, related indexes,
|
||||
owner-permission backfill DML) — that's **Brief 3**.
|
||||
- Does **NOT** fold in the per-row slug backfill DML from
|
||||
`add-collection-slugs.js` — fresh envs have no pre-existing
|
||||
collections to backfill.
|
||||
- Does **NOT** unify the `is_public` / `visibility` redundancy
|
||||
(SCHEMA_MAP smell #2) — that's a future `unify-collection-visibility`
|
||||
follow-up.
|
||||
- Does **NOT** edit `scripts/setup-neon-db.js`, `package.json`, README,
|
||||
or AGENTS.md.
|
||||
- Does **NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `node --check migrations/1781000000002_reconcile-collections-columns.js` exits 0
|
||||
- [ ] `node -e "import('./migrations/1781000000002_reconcile-collections-columns.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`
|
||||
- [ ] `npm run lint` matches baseline
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Did not run `npm run migrate up` against any environment in this PR
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Source scripts (no-go-zones, audit reference only):
|
||||
`scripts/add-collaboration-features.js`,
|
||||
`scripts/add-collection-slugs.js`,
|
||||
`scripts/add-image-column.js`
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit `scripts/add-collaboration-features.js`, `scripts/add-collection-slugs.js`, `scripts/add-image-column.js`, or any other file under `scripts/` — append-only no-go-zone.
|
||||
- DO NOT edit any other file under `migrations/`.
|
||||
- DO NOT edit `scripts/setup-neon-db.js`, `package.json`, README, `AGENTS.md`, or `docs/SCHEMA_MAP.md` (B7 owns SCHEMA_MAP).
|
||||
- DO NOT run `npm run migrate up` against any environment.
|
||||
- DO NOT include the per-row slug backfill DML — out of scope.
|
||||
- DO NOT add work for `collection_permissions` / `collection_activity` / `users.is_pending` — that's Brief 3.
|
||||
- DO NOT call `npm run migrate create` — it would generate a `Date.now()` timestamp colliding with B1/B3/B4/B5's reservation tokens.
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Grouping all `collections`-table DDL into one migration matches the per-table grouping of D1 and keeps the diff focused on a single surface. Splitting `add-collaboration-features.js` between this brief (columns) and Brief 3 (tables) avoids creating an artificial dependency between two parallel briefs — each writes only its own new file. The CHECK-constraint exception block matches the historical script's try/catch pattern and is the idiomatic Postgres way to do idempotent CHECK adds.
|
||||
|
|
@ -1,318 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 3
|
||||
depends_on: []
|
||||
files:
|
||||
- migrations/1781000000003_reconcile-collaboration-tables.js
|
||||
---
|
||||
|
||||
# Brief 3: Reconcile collaboration tables into migration history
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Capture the `collection_permissions` + `collection_activity` table creation, the `users.is_pending` column, and the 3 related indexes from `scripts/add-collaboration-features.js` into a single new `node-pg-migrate` migration so a brand-new Neon branch ends up with the collaboration / sharing surface after `npm run setup-db`.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `migrations/1781000000003_reconcile-collaboration-tables.js` — **new**
|
||||
|
||||
## Source script (read-only audit reference; DO NOT EDIT — no-go-zone)
|
||||
|
||||
`scripts/add-collaboration-features.js` lines 24-81 (relevant DDL only; the collections-columns half is reconciled by Brief 2):
|
||||
|
||||
```js
|
||||
// collection_permissions table
|
||||
await sql`
|
||||
CREATE TABLE IF NOT EXISTS collection_permissions (
|
||||
id SERIAL PRIMARY KEY,
|
||||
collection_id INTEGER REFERENCES collections(id) ON DELETE CASCADE,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
role VARCHAR(20) NOT NULL CHECK (role IN ('owner', 'editor', 'viewer')),
|
||||
status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'pending', 'declined')),
|
||||
invite_token VARCHAR(255) UNIQUE,
|
||||
invited_by INTEGER REFERENCES users(id),
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(collection_id, user_id)
|
||||
)
|
||||
`;
|
||||
|
||||
// collection_activity table
|
||||
await sql`
|
||||
CREATE TABLE IF NOT EXISTS collection_activity (
|
||||
id SERIAL PRIMARY KEY,
|
||||
collection_id INTEGER REFERENCES collections(id) ON DELETE CASCADE,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
|
||||
action VARCHAR(50) NOT NULL,
|
||||
details JSONB,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
)
|
||||
`;
|
||||
|
||||
// users.is_pending column
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS is_pending BOOLEAN DEFAULT false
|
||||
`;
|
||||
|
||||
// 3 indexes (the 4th — idx_collections_visibility — is Brief 2's scope)
|
||||
await sql`
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_permissions_collection_id
|
||||
ON collection_permissions(collection_id)
|
||||
`;
|
||||
await sql`
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_permissions_user_id
|
||||
ON collection_permissions(user_id)
|
||||
`;
|
||||
await sql`
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_activity_collection_id
|
||||
ON collection_activity(collection_id)
|
||||
`;
|
||||
```
|
||||
|
||||
**Owner-permission backfill DML** at lines 84-99 inserts `('owner', 'active')` rows for every pre-existing collection. **Do NOT fold the backfill DML into this migration.** Fresh envs have no pre-existing collections needing backfill; on prod, the backfill ran once historically and is baked in. The current runtime invariant for new collection creation lives in `pages/api/collections.js` (verify post-merge if needed — out of scope for this brief).
|
||||
|
||||
## Target migration file
|
||||
|
||||
Path: `migrations/1781000000003_reconcile-collaboration-tables.js`
|
||||
|
||||
Contents:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Reconcile the collaboration / sharing half of
|
||||
* scripts/add-collaboration-features.js into the migration history:
|
||||
*
|
||||
* - CREATE TABLE collection_permissions (with role/status CHECK
|
||||
* constraints inline + invite_token UNIQUE + UNIQUE(collection_id,
|
||||
* user_id))
|
||||
* - CREATE TABLE collection_activity (with JSONB details column)
|
||||
* - ALTER users ADD COLUMN is_pending BOOLEAN DEFAULT false
|
||||
* - 3 indexes (idx_collection_permissions_collection_id,
|
||||
* idx_collection_permissions_user_id,
|
||||
* idx_collection_activity_collection_id)
|
||||
*
|
||||
* The 4th index from the source script (idx_collections_visibility)
|
||||
* is reconciled by migrations/1781000000002_reconcile-collections-columns.js
|
||||
* because it indexes a column added in that brief.
|
||||
*
|
||||
* The collections-columns half (visibility, tcg, tags) of
|
||||
* add-collaboration-features.js is reconciled by
|
||||
* migrations/1781000000002_reconcile-collections-columns.js.
|
||||
*
|
||||
* The owner-permission backfill DML from the source script (INSERT
|
||||
* INTO collection_permissions ... 'owner', 'active' for every
|
||||
* pre-existing collection) is intentionally NOT folded in — fresh
|
||||
* envs have no pre-existing collections to backfill; on prod, the
|
||||
* backfill ran once historically and is baked in. The runtime
|
||||
* invariant for owner-permission creation on new collections is the
|
||||
* responsibility of pages/api/collections.js (out of scope here).
|
||||
*
|
||||
* Both CREATE TABLE statements use IF NOT EXISTS, with CHECK
|
||||
* constraints declared inline (no idempotency issue — IF NOT EXISTS
|
||||
* on the parent table makes the whole CREATE a no-op when the table
|
||||
* already exists, CHECK constraints and all).
|
||||
*
|
||||
* Idempotent re-apply: every statement uses IF NOT EXISTS.
|
||||
*
|
||||
* @type {import('node-pg-migrate').ColumnDefinitions | undefined}
|
||||
*/
|
||||
export const shorthands = undefined;
|
||||
|
||||
/**
|
||||
* @param {import('node-pg-migrate').MigrationBuilder} pgm
|
||||
*/
|
||||
export const up = (pgm) => {
|
||||
pgm.sql(`
|
||||
CREATE TABLE IF NOT EXISTS collection_permissions (
|
||||
id SERIAL PRIMARY KEY,
|
||||
collection_id INTEGER REFERENCES collections(id) ON DELETE CASCADE,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
role VARCHAR(20) NOT NULL CHECK (role IN ('owner', 'editor', 'viewer')),
|
||||
status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'pending', 'declined')),
|
||||
invite_token VARCHAR(255) UNIQUE,
|
||||
invited_by INTEGER REFERENCES users(id),
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(collection_id, user_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS collection_activity (
|
||||
id SERIAL PRIMARY KEY,
|
||||
collection_id INTEGER REFERENCES collections(id) ON DELETE CASCADE,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
|
||||
action VARCHAR(50) NOT NULL,
|
||||
details JSONB,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS is_pending BOOLEAN DEFAULT false;
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_permissions_collection_id
|
||||
ON collection_permissions (collection_id);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_permissions_user_id
|
||||
ON collection_permissions (user_id);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_collection_activity_collection_id
|
||||
ON collection_activity (collection_id);
|
||||
`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Down-migration intentionally throws. Dropping collection_permissions
|
||||
* + collection_activity on a long-lived env would erase every active
|
||||
* sharing relationship + every audit trail row. The runtime in
|
||||
* pages/api/collections/[identifier]/permissions.js, pages/api/invite/*.js,
|
||||
* and lib/permission-middleware.js all read these tables; rolling back
|
||||
* would break the live app.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
export const down = () => {
|
||||
throw new Error(
|
||||
'[migration:1781000000003_reconcile-collaboration-tables] Down not supported. ' +
|
||||
'Dropping collection_permissions / collection_activity would erase every ' +
|
||||
'sharing relationship and audit trail, and break runtime reads in ' +
|
||||
'pages/api/collections/[identifier]/permissions.js, pages/api/invite/*.js, ' +
|
||||
'lib/permission-middleware.js. Write a new dated migration for any future ' +
|
||||
'schema correction.'
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/db-and-schema.mdc` § "Schema source of truth" — `migrations/` is canonical; one migration per feature surface.
|
||||
- `.cursor/rules/no-go-zones.mdc` — `scripts/add-collaboration-features.js` is append-only history. **Do not edit it.**
|
||||
- Style: raw `pgm.sql(...)` template literals matching the other migrations. Per D2.
|
||||
- ESM exports; `"type": "module"`.
|
||||
- `IF NOT EXISTS` on every CREATE / ALTER. Inline CHECK constraints on `CREATE TABLE` are fine — `CREATE TABLE IF NOT EXISTS` skips the entire statement (constraints and all) when the table exists.
|
||||
- FK declarations match the source script verbatim (`ON DELETE CASCADE` for primary FKs, `ON DELETE SET NULL` where the source uses it).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `migrations/1781000000003_reconcile-collaboration-tables.js` exists with the exact filename above.
|
||||
- [ ] The file's `up()`:
|
||||
- Creates `collection_permissions` table with all 10 columns + role/status CHECKs + invite_token UNIQUE + UNIQUE(collection_id, user_id), all via `CREATE TABLE IF NOT EXISTS`.
|
||||
- Creates `collection_activity` table with 6 columns including JSONB `details`, via `CREATE TABLE IF NOT EXISTS`.
|
||||
- Adds `users.is_pending BOOLEAN DEFAULT false` via `ADD COLUMN IF NOT EXISTS`.
|
||||
- Creates 3 indexes via `CREATE INDEX IF NOT EXISTS`.
|
||||
- [ ] The 4th index from the source script (`idx_collections_visibility`) is NOT in this migration — it belongs to Brief 2.
|
||||
- [ ] The owner-permission backfill DML is NOT in this migration.
|
||||
- [ ] The file's `down()` throws with a clear message.
|
||||
- [ ] The file's docstring cites the source script + the convoy file + the Brief 2 split.
|
||||
- [ ] `node --check migrations/1781000000003_reconcile-collaboration-tables.js` passes.
|
||||
- [ ] `node -e "import('./migrations/1781000000003_reconcile-collaboration-tables.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`.
|
||||
- [ ] `npm run lint` matches baseline.
|
||||
- [ ] `npm run test:run` reports 21/21 passing.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
node --check migrations/1781000000003_reconcile-collaboration-tables.js
|
||||
node -e "import('./migrations/1781000000003_reconcile-collaboration-tables.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Expected: `node --check` silent, `node -e` prints `function function undefined`, lint baseline, 21/21 tests pass.
|
||||
|
||||
**Do NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
feat(migrations): reconcile collaboration tables into migration history (brief 3/7)
|
||||
|
||||
Captures the collaboration / sharing half of
|
||||
scripts/add-collaboration-features.js into one new node-pg-migrate
|
||||
migration:
|
||||
|
||||
- CREATE TABLE collection_permissions (role/status CHECKs,
|
||||
invite_token UNIQUE, UNIQUE(collection_id, user_id))
|
||||
- CREATE TABLE collection_activity (JSONB details)
|
||||
- ALTER users ADD COLUMN is_pending BOOLEAN DEFAULT false
|
||||
- 3 indexes
|
||||
|
||||
The collections-columns half (visibility, tcg, tags +
|
||||
idx_collections_visibility) is reconciled by Brief 2. The 4th index
|
||||
(idx_collections_visibility) belongs to Brief 2 because it indexes a
|
||||
column added there.
|
||||
|
||||
Per-row owner-permission backfill DML from the source script is
|
||||
intentionally NOT folded in — fresh envs have no pre-existing
|
||||
collections to backfill; the runtime invariant for new-collection
|
||||
owner-perm creation lives in pages/api/collections.js.
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B3.
|
||||
Idempotent re-apply (IF NOT EXISTS guards).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `feat(migrations): reconcile collaboration tables into migration history (brief 3/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 3 of the `reconcile-historical-add-scripts` convoy. See
|
||||
[`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
## What this PR does
|
||||
|
||||
Adds `migrations/1781000000003_reconcile-collaboration-tables.js` —
|
||||
captures the collaboration / sharing DDL of
|
||||
`scripts/add-collaboration-features.js` (the table-and-column half;
|
||||
the columns-on-collections half is Brief 2).
|
||||
|
||||
- `CREATE TABLE IF NOT EXISTS collection_permissions` (10 columns
|
||||
including inline role/status CHECK constraints + invite_token
|
||||
UNIQUE + UNIQUE(collection_id, user_id))
|
||||
- `CREATE TABLE IF NOT EXISTS collection_activity` (6 columns
|
||||
including JSONB `details`)
|
||||
- `ALTER TABLE users ADD COLUMN IF NOT EXISTS is_pending BOOLEAN DEFAULT false`
|
||||
- 3 indexes via `CREATE INDEX IF NOT EXISTS`
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit `scripts/add-collaboration-features.js` (no-go-zone).
|
||||
- Does **NOT** capture the columns-on-collections half (`visibility`,
|
||||
`tcg`, `tags`, `idx_collections_visibility`) — that's **Brief 2**.
|
||||
- Does **NOT** fold in the per-row owner-permission backfill DML from
|
||||
the source script — fresh envs have no pre-existing collections to
|
||||
backfill.
|
||||
- Does **NOT** edit `scripts/setup-neon-db.js`, `package.json`, README,
|
||||
`AGENTS.md`, or `docs/SCHEMA_MAP.md` (B7 owns SCHEMA_MAP).
|
||||
- Does **NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `node --check migrations/1781000000003_reconcile-collaboration-tables.js` exits 0
|
||||
- [ ] `node -e "import('./migrations/1781000000003_reconcile-collaboration-tables.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`
|
||||
- [ ] `npm run lint` matches baseline
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Did not run `npm run migrate up` against any environment in this PR
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Source script (no-go-zone, audit reference only):
|
||||
`scripts/add-collaboration-features.js`
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit `scripts/add-collaboration-features.js` or any file under `scripts/`.
|
||||
- DO NOT edit any other file under `migrations/`.
|
||||
- DO NOT edit `scripts/setup-neon-db.js`, `package.json`, README, `AGENTS.md`, or `docs/SCHEMA_MAP.md`.
|
||||
- DO NOT run `npm run migrate up` against any environment.
|
||||
- DO NOT include the owner-permission backfill DML.
|
||||
- DO NOT add work for the collections-columns half (`visibility`, `tcg`, `tags`, `idx_collections_visibility`) — that's Brief 2.
|
||||
- DO NOT call `npm run migrate create`.
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Splitting `add-collaboration-features.js` between Brief 2 (collections columns + the visibility index that indexes one of those columns) and Brief 3 (collaboration tables + the users.is_pending column + the 3 indexes that index collaboration-table columns) keeps each migration scoped to the table surface it touches, matching D1. Inline CHECK constraints on `CREATE TABLE` are idempotent for free under `CREATE TABLE IF NOT EXISTS` (the whole statement no-ops when the table exists). The backfill DML is intentionally out of scope because fresh envs need no backfill and prod's backfill already ran.
|
||||
|
|
@ -1,241 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 4
|
||||
depends_on: []
|
||||
files:
|
||||
- migrations/1781000000004_reconcile-favorites-system.js
|
||||
---
|
||||
|
||||
# Brief 4: Reconcile favorites system into migration history
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Capture the `user_favorites` table and its 4 indexes from `scripts/add-favorites-system.js` into a single new `node-pg-migrate` migration so a brand-new Neon branch ends up with the favorites surface after `npm run setup-db`.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `migrations/1781000000004_reconcile-favorites-system.js` — **new**
|
||||
|
||||
## Source script (read-only audit reference; DO NOT EDIT — no-go-zone)
|
||||
|
||||
`scripts/add-favorites-system.js` lines 11-27 (entire DDL — script has no DML beyond the table create):
|
||||
|
||||
```js
|
||||
await sql`
|
||||
CREATE TABLE IF NOT EXISTS user_favorites (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
item_type VARCHAR(50) NOT NULL, -- 'card', 'collection', 'deck'
|
||||
item_id INTEGER NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(user_id, item_type, item_id)
|
||||
)
|
||||
`;
|
||||
|
||||
// 4 indexes
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_favorites_user_id ON user_favorites(user_id)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_favorites_item_type ON user_favorites(item_type)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_favorites_item_id ON user_favorites(item_id)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_favorites_user_type ON user_favorites(user_id, item_type)`;
|
||||
```
|
||||
|
||||
**Note on SCHEMA_MAP drift.** `docs/SCHEMA_MAP.md` § `user_favorites` (lines 104-111) shows the table with only `(user_id, card_id)` columns — that's a **doc bug**. The actual source script (and prod schema) uses the polymorphic `(item_type, item_id)` shape that supports cards, collections, AND decks (per the script's inline comment + the runtime usage in `pages/api/favorites.js`). B7 corrects the SCHEMA_MAP entry. This brief faithfully reproduces the **script's** shape — `(item_type, item_id)` — not the doc's.
|
||||
|
||||
## Target migration file
|
||||
|
||||
Path: `migrations/1781000000004_reconcile-favorites-system.js`
|
||||
|
||||
Contents:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Reconcile scripts/add-favorites-system.js into the migration history.
|
||||
*
|
||||
* Creates user_favorites with the polymorphic (item_type, item_id)
|
||||
* shape that supports favoriting cards, collections, and decks via a
|
||||
* single table. Adds 4 indexes for the common query shapes:
|
||||
*
|
||||
* - idx_user_favorites_user_id — "all favorites for user X"
|
||||
* - idx_user_favorites_item_type — "all card favorites" / "all deck favorites"
|
||||
* - idx_user_favorites_item_id — back-link from an item to its favoriters
|
||||
* - idx_user_favorites_user_type — composite for "user X's card favorites"
|
||||
*
|
||||
* Note: docs/SCHEMA_MAP.md § user_favorites currently shows only
|
||||
* (user_id, card_id) — that's a doc bug. The actual prod shape (and
|
||||
* the source script, and the runtime in pages/api/favorites.js) uses
|
||||
* the polymorphic shape. B7 of this convoy corrects the SCHEMA_MAP
|
||||
* entry; this migration reproduces the script's shape faithfully.
|
||||
*
|
||||
* Idempotent re-apply: CREATE TABLE IF NOT EXISTS + CREATE INDEX IF NOT EXISTS.
|
||||
*
|
||||
* @type {import('node-pg-migrate').ColumnDefinitions | undefined}
|
||||
*/
|
||||
export const shorthands = undefined;
|
||||
|
||||
/**
|
||||
* @param {import('node-pg-migrate').MigrationBuilder} pgm
|
||||
*/
|
||||
export const up = (pgm) => {
|
||||
pgm.sql(`
|
||||
CREATE TABLE IF NOT EXISTS user_favorites (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
item_type VARCHAR(50) NOT NULL,
|
||||
item_id INTEGER NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(user_id, item_type, item_id)
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_user_favorites_user_id
|
||||
ON user_favorites (user_id);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_user_favorites_item_type
|
||||
ON user_favorites (item_type);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_user_favorites_item_id
|
||||
ON user_favorites (item_id);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_user_favorites_user_type
|
||||
ON user_favorites (user_id, item_type);
|
||||
`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Down-migration intentionally throws. Dropping user_favorites on a
|
||||
* long-lived env would erase every user's saved favorites list and
|
||||
* break runtime reads in pages/api/favorites.js.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
export const down = () => {
|
||||
throw new Error(
|
||||
'[migration:1781000000004_reconcile-favorites-system] Down not supported. ' +
|
||||
'Dropping user_favorites would erase every saved favorite and break ' +
|
||||
'pages/api/favorites.js. Write a new dated migration for any future ' +
|
||||
'schema correction.'
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/db-and-schema.mdc` § "Schema source of truth" — `migrations/` is canonical.
|
||||
- `.cursor/rules/no-go-zones.mdc` — `scripts/add-favorites-system.js` is append-only history.
|
||||
- Style: raw `pgm.sql(...)` template literals. Per D2.
|
||||
- ESM exports; `"type": "module"`.
|
||||
- `IF NOT EXISTS` on every CREATE.
|
||||
- Match the source script's column types, FK ON DELETE rule (`CASCADE`), and UNIQUE shape verbatim.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `migrations/1781000000004_reconcile-favorites-system.js` exists with the exact filename above.
|
||||
- [ ] The file's `up()` creates `user_favorites` with all 5 columns + UNIQUE constraint, then 4 indexes, all via `IF NOT EXISTS`.
|
||||
- [ ] The column shape is `(item_type VARCHAR(50), item_id INTEGER)` — the polymorphic shape — NOT `(card_id)`. See "Note on SCHEMA_MAP drift" above.
|
||||
- [ ] The file's `down()` throws with a clear message.
|
||||
- [ ] The file's docstring cites the source script + the convoy file + the SCHEMA_MAP doc-bug note.
|
||||
- [ ] `node --check migrations/1781000000004_reconcile-favorites-system.js` passes.
|
||||
- [ ] `node -e "import('./migrations/1781000000004_reconcile-favorites-system.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`.
|
||||
- [ ] `npm run lint` matches baseline.
|
||||
- [ ] `npm run test:run` reports 21/21 passing.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
node --check migrations/1781000000004_reconcile-favorites-system.js
|
||||
node -e "import('./migrations/1781000000004_reconcile-favorites-system.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Expected: `node --check` silent, `node -e` prints `function function undefined`, lint baseline, 21/21 tests pass.
|
||||
|
||||
**Do NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
feat(migrations): reconcile favorites system into migration history (brief 4/7)
|
||||
|
||||
Captures scripts/add-favorites-system.js into one new node-pg-migrate
|
||||
migration:
|
||||
|
||||
- CREATE TABLE user_favorites (polymorphic (item_type, item_id)
|
||||
shape; UNIQUE(user_id, item_type, item_id))
|
||||
- 4 indexes (user_id, item_type, item_id, (user_id, item_type))
|
||||
|
||||
Note: docs/SCHEMA_MAP.md § user_favorites currently shows the table
|
||||
with only (user_id, card_id) — that's a doc bug; B7 of this convoy
|
||||
corrects the entry. This migration faithfully reproduces the source
|
||||
script's polymorphic shape (also what runtime in pages/api/favorites.js
|
||||
uses).
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B4.
|
||||
Idempotent re-apply (IF NOT EXISTS guards).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `feat(migrations): reconcile favorites system into migration history (brief 4/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 4 of the `reconcile-historical-add-scripts` convoy. See
|
||||
[`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
## What this PR does
|
||||
|
||||
Adds `migrations/1781000000004_reconcile-favorites-system.js` —
|
||||
captures `scripts/add-favorites-system.js` into a single new
|
||||
`node-pg-migrate` migration.
|
||||
|
||||
- `CREATE TABLE IF NOT EXISTS user_favorites` with polymorphic
|
||||
`(item_type VARCHAR(50), item_id INTEGER)` shape supporting
|
||||
cards / collections / decks favorites in one table.
|
||||
- `UNIQUE(user_id, item_type, item_id)` prevents duplicate favorites.
|
||||
- 4 supporting indexes via `CREATE INDEX IF NOT EXISTS`.
|
||||
|
||||
## Note on a SCHEMA_MAP doc bug
|
||||
|
||||
`docs/SCHEMA_MAP.md` § `user_favorites` (current `main`) shows the
|
||||
table with only `(user_id, card_id)` columns. That's a doc bug — the
|
||||
actual prod shape (and the source script, and `pages/api/favorites.js`
|
||||
runtime usage) uses the polymorphic `(item_type, item_id)` shape. This
|
||||
migration faithfully reproduces the script's shape; Brief 7 of this
|
||||
convoy fixes the SCHEMA_MAP entry.
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit `scripts/add-favorites-system.js` (no-go-zone).
|
||||
- Does **NOT** edit `docs/SCHEMA_MAP.md` (Brief 7's job).
|
||||
- Does **NOT** edit `scripts/setup-neon-db.js`, `package.json`, README,
|
||||
or `AGENTS.md`.
|
||||
- Does **NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `node --check migrations/1781000000004_reconcile-favorites-system.js` exits 0
|
||||
- [ ] `node -e "import('./migrations/1781000000004_reconcile-favorites-system.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`
|
||||
- [ ] `npm run lint` matches baseline
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Did not run `npm run migrate up` against any environment in this PR
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Source script (no-go-zone, audit reference only): `scripts/add-favorites-system.js`
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit `scripts/add-favorites-system.js` or any file under `scripts/`.
|
||||
- DO NOT edit any other file under `migrations/`.
|
||||
- DO NOT edit `scripts/setup-neon-db.js`, `package.json`, README, `AGENTS.md`, or `docs/SCHEMA_MAP.md` (B7 owns SCHEMA_MAP).
|
||||
- DO NOT run `npm run migrate up` against any environment.
|
||||
- DO NOT use the SCHEMA_MAP `(user_id, card_id)` shape — that doc entry is wrong; reproduce the SOURCE SCRIPT'S polymorphic shape.
|
||||
- DO NOT call `npm run migrate create`.
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
The favorites system is a single self-contained table — natural fit for one small migration that maps 1:1 with the historical script. The polymorphic shape (`item_type`, `item_id`) is what runtime code actually uses, so reproducing it from the script's verbatim DDL — rather than the stale `(user_id, card_id)` doc entry — is the safe choice. Brief 7's SCHEMA_MAP rewrite resolves the doc-bug separately so this brief stays scoped to one new file.
|
||||
|
|
@ -1,425 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 5
|
||||
depends_on: []
|
||||
files:
|
||||
- migrations/1781000000005_reconcile-user-profile.js
|
||||
---
|
||||
|
||||
# Brief 5: Reconcile user profile fields into migration history
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Capture the deduplicated union of `scripts/add-user-profile-columns.js` and `scripts/add-user-profile-fields.js` (15 new `users` columns, 2 new tables `user_settings` + `user_avatars`, 6 CHECK constraints, 6 indexes) into a single new `node-pg-migrate` migration so a brand-new Neon branch ends up with the user-profile surface after `npm run setup-db`.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `migrations/1781000000005_reconcile-user-profile.js` — **new**
|
||||
|
||||
## Source scripts (read-only audit reference; DO NOT EDIT — both are no-go-zones)
|
||||
|
||||
### `scripts/add-user-profile-columns.js` lines 12-18 (the earlier, narrower script):
|
||||
|
||||
```js
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS first_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS last_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS username VARCHAR(255) UNIQUE,
|
||||
ADD COLUMN IF NOT EXISTS profile_image_url TEXT
|
||||
`;
|
||||
```
|
||||
|
||||
Plus per-row UPDATE backfill of defaults (lines 25-42). **Do NOT fold the backfill DML into this migration** — fresh envs have no rows to backfill; column DEFAULTs handle new rows.
|
||||
|
||||
### `scripts/add-user-profile-fields.js` lines 27-115 (the later, broader script — superset of #8 plus additional columns + 2 new tables + 6 CHECK constraints + 6 indexes):
|
||||
|
||||
```js
|
||||
// Basic profile fields (overlaps add-user-profile-columns.js for first_name/last_name/username,
|
||||
// but ADDS bio + avatar_url; idempotent overlap because of IF NOT EXISTS)
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS first_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS last_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS username VARCHAR(255) UNIQUE,
|
||||
ADD COLUMN IF NOT EXISTS bio TEXT,
|
||||
ADD COLUMN IF NOT EXISTS avatar_url TEXT
|
||||
`;
|
||||
|
||||
// Preference fields
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS favorite_games JSONB DEFAULT '["MTG"]',
|
||||
ADD COLUMN IF NOT EXISTS collection_visibility VARCHAR(20) DEFAULT 'private',
|
||||
ADD COLUMN IF NOT EXISTS preferred_currency VARCHAR(3) DEFAULT 'USD',
|
||||
ADD COLUMN IF NOT EXISTS cards_per_page INTEGER DEFAULT 50,
|
||||
ADD COLUMN IF NOT EXISTS default_view VARCHAR(10) DEFAULT 'grid'
|
||||
`;
|
||||
|
||||
// Notification + 2FA settings
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS notifications_email BOOLEAN DEFAULT true,
|
||||
ADD COLUMN IF NOT EXISTS notifications_marketing BOOLEAN DEFAULT false,
|
||||
ADD COLUMN IF NOT EXISTS two_factor_enabled BOOLEAN DEFAULT false
|
||||
`;
|
||||
|
||||
// Display settings
|
||||
await sql`
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS theme VARCHAR(10) DEFAULT 'system',
|
||||
ADD COLUMN IF NOT EXISTS language VARCHAR(5) DEFAULT 'en'
|
||||
`;
|
||||
|
||||
// user_settings table
|
||||
await sql`
|
||||
CREATE TABLE IF NOT EXISTS user_settings (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
setting_key VARCHAR(100) NOT NULL,
|
||||
setting_value JSONB NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(user_id, setting_key)
|
||||
)
|
||||
`;
|
||||
|
||||
// user_avatars table
|
||||
await sql`
|
||||
CREATE TABLE IF NOT EXISTS user_avatars (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
filename VARCHAR(255) NOT NULL,
|
||||
original_name VARCHAR(255),
|
||||
mime_type VARCHAR(100),
|
||||
file_size INTEGER,
|
||||
file_path TEXT NOT NULL,
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
)
|
||||
`;
|
||||
|
||||
// 6 indexes
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_users_username ON users(username)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_settings_user_id ON user_settings(user_id)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_settings_key ON user_settings(setting_key)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_avatars_user_id ON user_avatars(user_id)`;
|
||||
await sql`CREATE INDEX IF NOT EXISTS idx_user_avatars_active ON user_avatars(user_id, is_active)`;
|
||||
|
||||
// 6 CHECK constraints (each wrapped in JS try/catch to swallow 'already exists')
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_collection_visibility CHECK (collection_visibility IN ('private', 'public', 'unlisted'))`;
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_preferred_currency CHECK (preferred_currency IN ('USD', 'EUR', 'GBP', 'CAD', 'JPY'))`;
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_cards_per_page CHECK (cards_per_page IN (25, 50, 100))`;
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_default_view CHECK (default_view IN ('grid', 'list'))`;
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_theme CHECK (theme IN ('light', 'dark', 'system'))`;
|
||||
await sql`ALTER TABLE users ADD CONSTRAINT check_language CHECK (language IN ('en', 'es', 'fr', 'de', 'ja'))`;
|
||||
```
|
||||
|
||||
Plus a per-row UPDATE backfill of defaults (lines 198-222). **Do NOT fold the backfill DML in** — column DEFAULTs handle new rows; fresh envs have no rows to backfill.
|
||||
|
||||
### Important note on the column dedup
|
||||
|
||||
Scripts #8 and #9 overlap on `first_name`, `last_name`, `username` — both use `ADD COLUMN IF NOT EXISTS` so on prod the second-running script no-ops those three columns. Both scripts have run on prod, so the union of their columns is what's actually present:
|
||||
|
||||
- From #8 only: `profile_image_url` (TEXT) — a column that ONLY #8 added.
|
||||
- From #9 only: `bio`, `avatar_url`, `favorite_games`, `collection_visibility`, `preferred_currency`, `cards_per_page`, `default_view`, `notifications_email`, `notifications_marketing`, `two_factor_enabled`, `theme`, `language` (12 columns) + the 2 new tables + 6 CHECK constraints + 6 indexes.
|
||||
- From both (idempotent overlap): `first_name`, `last_name`, `username`.
|
||||
|
||||
The migration must add **all 15 columns** (4 from #8 ∪ 12 from #9 with 3 in the intersection = 4 + 12 - 3 = 13 unique users columns; wait, let me recount: #8 adds 4 (first_name, last_name, username, profile_image_url); #9 adds 5 basic (first_name, last_name, username, bio, avatar_url) + 5 prefs + 3 notif + 2 display = 15. Union: first_name, last_name, username (shared) + profile_image_url (#8) + bio, avatar_url, favorite_games, collection_visibility, preferred_currency, cards_per_page, default_view, notifications_email, notifications_marketing, two_factor_enabled, theme, language (#9) = **3 + 1 + 12 = 16 columns**). So the migration adds 16 columns to `users`.
|
||||
|
||||
The redundant `profile_image_url` vs `avatar_url` pair is documented in `docs/SCHEMA_MAP.md` § "Known schema smells" #1 and surfaced as the `unify-user-avatar-column` follow-up. Both must be in fresh envs for parity.
|
||||
|
||||
## Target migration file
|
||||
|
||||
Path: `migrations/1781000000005_reconcile-user-profile.js`
|
||||
|
||||
Contents:
|
||||
|
||||
```js
|
||||
/**
|
||||
* Reconcile two overlapping historical user-profile scripts into the
|
||||
* migration history, taking the union of their effects:
|
||||
*
|
||||
* - scripts/add-user-profile-columns.js (the earlier, narrower
|
||||
* script): first_name, last_name, username UNIQUE, profile_image_url
|
||||
*
|
||||
* - scripts/add-user-profile-fields.js (the later, broader script;
|
||||
* overlaps the earlier script on first_name / last_name / username
|
||||
* and additionally adds): bio, avatar_url, favorite_games (JSONB
|
||||
* DEFAULT '["MTG"]'), collection_visibility, preferred_currency,
|
||||
* cards_per_page, default_view, notifications_email,
|
||||
* notifications_marketing, two_factor_enabled, theme, language,
|
||||
* + the new user_settings + user_avatars tables, + 6 CHECK
|
||||
* constraints, + 6 indexes.
|
||||
*
|
||||
* Result on a fresh env: 16 new columns on `users`, 2 new tables,
|
||||
* 6 CHECK constraints, 6 indexes. On any long-lived env: every
|
||||
* statement is a no-op (IF NOT EXISTS / DO $$ EXCEPTION).
|
||||
*
|
||||
* Per-row UPDATE backfills from both scripts are intentionally NOT
|
||||
* folded in — column DEFAULTs handle new rows; fresh envs have no
|
||||
* rows to backfill.
|
||||
*
|
||||
* The profile_image_url / avatar_url redundancy is intentional for
|
||||
* parity with prod and is flagged in docs/SCHEMA_MAP.md § "Known
|
||||
* schema smells" #1; future cleanup is the queued
|
||||
* `unify-user-avatar-column` follow-up.
|
||||
*
|
||||
* CHECK constraint adds wrap in DO $$ ... EXCEPTION WHEN
|
||||
* duplicate_object THEN NULL END $$ because Postgres doesn't accept
|
||||
* ADD CONSTRAINT ... IF NOT EXISTS for CHECK. Each constraint gets
|
||||
* its own DO block so a failure in one doesn't block the rest.
|
||||
*
|
||||
* @type {import('node-pg-migrate').ColumnDefinitions | undefined}
|
||||
*/
|
||||
export const shorthands = undefined;
|
||||
|
||||
/**
|
||||
* @param {import('node-pg-migrate').MigrationBuilder} pgm
|
||||
*/
|
||||
export const up = (pgm) => {
|
||||
pgm.sql(`
|
||||
-- 16 columns on users (union of add-user-profile-columns.js + add-user-profile-fields.js)
|
||||
ALTER TABLE users
|
||||
ADD COLUMN IF NOT EXISTS first_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS last_name VARCHAR(255),
|
||||
ADD COLUMN IF NOT EXISTS username VARCHAR(255) UNIQUE,
|
||||
ADD COLUMN IF NOT EXISTS profile_image_url TEXT,
|
||||
ADD COLUMN IF NOT EXISTS bio TEXT,
|
||||
ADD COLUMN IF NOT EXISTS avatar_url TEXT,
|
||||
ADD COLUMN IF NOT EXISTS favorite_games JSONB DEFAULT '["MTG"]',
|
||||
ADD COLUMN IF NOT EXISTS collection_visibility VARCHAR(20) DEFAULT 'private',
|
||||
ADD COLUMN IF NOT EXISTS preferred_currency VARCHAR(3) DEFAULT 'USD',
|
||||
ADD COLUMN IF NOT EXISTS cards_per_page INTEGER DEFAULT 50,
|
||||
ADD COLUMN IF NOT EXISTS default_view VARCHAR(10) DEFAULT 'grid',
|
||||
ADD COLUMN IF NOT EXISTS notifications_email BOOLEAN DEFAULT true,
|
||||
ADD COLUMN IF NOT EXISTS notifications_marketing BOOLEAN DEFAULT false,
|
||||
ADD COLUMN IF NOT EXISTS two_factor_enabled BOOLEAN DEFAULT false,
|
||||
ADD COLUMN IF NOT EXISTS theme VARCHAR(10) DEFAULT 'system',
|
||||
ADD COLUMN IF NOT EXISTS language VARCHAR(5) DEFAULT 'en';
|
||||
|
||||
-- user_settings table
|
||||
CREATE TABLE IF NOT EXISTS user_settings (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
setting_key VARCHAR(100) NOT NULL,
|
||||
setting_value JSONB NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(user_id, setting_key)
|
||||
);
|
||||
|
||||
-- user_avatars table
|
||||
CREATE TABLE IF NOT EXISTS user_avatars (
|
||||
id SERIAL PRIMARY KEY,
|
||||
user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
|
||||
filename VARCHAR(255) NOT NULL,
|
||||
original_name VARCHAR(255),
|
||||
mime_type VARCHAR(100),
|
||||
file_size INTEGER,
|
||||
file_path TEXT NOT NULL,
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
-- 6 indexes
|
||||
CREATE INDEX IF NOT EXISTS idx_users_username ON users (username);
|
||||
CREATE INDEX IF NOT EXISTS idx_users_email ON users (email);
|
||||
CREATE INDEX IF NOT EXISTS idx_user_settings_user_id ON user_settings (user_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_user_settings_key ON user_settings (setting_key);
|
||||
CREATE INDEX IF NOT EXISTS idx_user_avatars_user_id ON user_avatars (user_id);
|
||||
CREATE INDEX IF NOT EXISTS idx_user_avatars_active ON user_avatars (user_id, is_active);
|
||||
|
||||
-- 6 CHECK constraints (each in its own DO block so one failure doesn't block the rest)
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_collection_visibility
|
||||
CHECK (collection_visibility IN ('private', 'public', 'unlisted'));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_preferred_currency
|
||||
CHECK (preferred_currency IN ('USD', 'EUR', 'GBP', 'CAD', 'JPY'));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_cards_per_page
|
||||
CHECK (cards_per_page IN (25, 50, 100));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_default_view
|
||||
CHECK (default_view IN ('grid', 'list'));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_theme
|
||||
CHECK (theme IN ('light', 'dark', 'system'));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
|
||||
DO $$ BEGIN
|
||||
ALTER TABLE users ADD CONSTRAINT check_language
|
||||
CHECK (language IN ('en', 'es', 'fr', 'de', 'ja'));
|
||||
EXCEPTION WHEN duplicate_object THEN NULL; END $$;
|
||||
`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Down-migration intentionally throws. Dropping 16 user-profile columns
|
||||
* + user_settings + user_avatars on a long-lived env would erase every
|
||||
* user's profile data, preferences, avatar history, and settings, and
|
||||
* break runtime reads in pages/api/user/{settings,profile,avatar}.js.
|
||||
*
|
||||
* @returns {void}
|
||||
*/
|
||||
export const down = () => {
|
||||
throw new Error(
|
||||
'[migration:1781000000005_reconcile-user-profile] Down not supported. ' +
|
||||
'Dropping these columns + tables would erase every user profile, preference, ' +
|
||||
'avatar history, and settings row, and break runtime reads in ' +
|
||||
'pages/api/user/{settings,profile,avatar}.js. Write a new dated migration ' +
|
||||
'for any future schema correction.'
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/db-and-schema.mdc` § "Schema source of truth" — `migrations/` is canonical.
|
||||
- `.cursor/rules/no-go-zones.mdc` — both source scripts are append-only history.
|
||||
- Style: raw `pgm.sql(...)` template literals. Per D2.
|
||||
- ESM exports; `"type": "module"`.
|
||||
- `IF NOT EXISTS` on every ALTER + CREATE INDEX + CREATE TABLE.
|
||||
- CHECK constraints in `DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL END $$;` blocks, one block per constraint.
|
||||
- Match the source scripts' column types, defaults, FK rules, and CHECK values verbatim.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `migrations/1781000000005_reconcile-user-profile.js` exists with the exact filename above.
|
||||
- [ ] The file's `up()` adds exactly **16 columns** to `users` (per the dedup count in the source-scripts note above), creates **2 tables** (`user_settings`, `user_avatars`), creates **6 indexes**, and adds **6 CHECK constraints** each in its own `DO $$ EXCEPTION` block.
|
||||
- [ ] BOTH `profile_image_url` AND `avatar_url` are present (parity with prod; redundancy is documented).
|
||||
- [ ] The file's `down()` throws with a clear message.
|
||||
- [ ] The file's docstring cites both source scripts + the convoy file + the `unify-user-avatar-column` follow-up.
|
||||
- [ ] Per-row UPDATE backfill DML is NOT in the migration.
|
||||
- [ ] `node --check migrations/1781000000005_reconcile-user-profile.js` passes.
|
||||
- [ ] `node -e "import('./migrations/1781000000005_reconcile-user-profile.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`.
|
||||
- [ ] `npm run lint` matches baseline.
|
||||
- [ ] `npm run test:run` reports 21/21 passing.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
node --check migrations/1781000000005_reconcile-user-profile.js
|
||||
node -e "import('./migrations/1781000000005_reconcile-user-profile.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Expected: `node --check` silent, `node -e` prints `function function undefined`, lint baseline, 21/21 tests pass.
|
||||
|
||||
**Do NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
feat(migrations): reconcile user profile fields into migration history (brief 5/7)
|
||||
|
||||
Captures the deduplicated union of scripts/add-user-profile-columns.js
|
||||
and scripts/add-user-profile-fields.js into one new node-pg-migrate
|
||||
migration:
|
||||
|
||||
- 16 columns on users (basic profile + preferences + notifications + display)
|
||||
- 2 new tables (user_settings, user_avatars)
|
||||
- 6 CHECK constraints (each in its own DO $$ EXCEPTION block)
|
||||
- 6 indexes
|
||||
|
||||
Both profile_image_url (from script #1) and avatar_url (from script #2)
|
||||
are added for parity with prod. The redundancy is flagged in
|
||||
docs/SCHEMA_MAP.md § "Known schema smells" #1 and queued for cleanup as
|
||||
the `unify-user-avatar-column` follow-up.
|
||||
|
||||
Per-row UPDATE backfill DML from both scripts is intentionally NOT
|
||||
folded in — column DEFAULTs handle new rows; fresh envs have no rows
|
||||
to backfill.
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B5.
|
||||
Idempotent re-apply (IF NOT EXISTS guards + per-CHECK DO blocks).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `feat(migrations): reconcile user profile fields into migration history (brief 5/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 5 of the `reconcile-historical-add-scripts` convoy. See
|
||||
[`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
## What this PR does
|
||||
|
||||
Adds `migrations/1781000000005_reconcile-user-profile.js` — captures
|
||||
the deduplicated union of `scripts/add-user-profile-columns.js`
|
||||
(earlier, narrower) and `scripts/add-user-profile-fields.js` (later,
|
||||
broader) into a single new `node-pg-migrate` migration.
|
||||
|
||||
- 16 new columns on `users` (first_name, last_name, username UNIQUE,
|
||||
profile_image_url, bio, avatar_url, favorite_games JSONB, …, theme,
|
||||
language) — all `ADD COLUMN IF NOT EXISTS`
|
||||
- 2 new tables: `user_settings`, `user_avatars` — both
|
||||
`CREATE TABLE IF NOT EXISTS`
|
||||
- 6 indexes — `CREATE INDEX IF NOT EXISTS`
|
||||
- 6 CHECK constraints (each in its own
|
||||
`DO $$ ... EXCEPTION WHEN duplicate_object THEN NULL END $$;` block)
|
||||
|
||||
## Why both `profile_image_url` and `avatar_url`?
|
||||
|
||||
Script #1 added `profile_image_url`, script #2 added `avatar_url` —
|
||||
both exist on prod and both are in this migration for fresh-env
|
||||
parity. The redundancy is flagged in
|
||||
`docs/SCHEMA_MAP.md` § "Known schema smells" #1 and queued for cleanup
|
||||
as the `unify-user-avatar-column` follow-up.
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit either source script (no-go-zones).
|
||||
- Does **NOT** fold in the per-row UPDATE backfill DML from either
|
||||
source script — column DEFAULTs handle new rows.
|
||||
- Does **NOT** unify `profile_image_url` / `avatar_url` — that's the
|
||||
`unify-user-avatar-column` follow-up.
|
||||
- Does **NOT** edit `scripts/setup-neon-db.js`, `package.json`, README,
|
||||
`AGENTS.md`, or `docs/SCHEMA_MAP.md` (B7 owns SCHEMA_MAP).
|
||||
- Does **NOT** run `npm run migrate up` against any environment.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `node --check migrations/1781000000005_reconcile-user-profile.js` exits 0
|
||||
- [ ] `node -e "import('./migrations/1781000000005_reconcile-user-profile.js').then(m => console.log(typeof m.up, typeof m.down, typeof m.shorthands))"` prints `function function undefined`
|
||||
- [ ] `npm run lint` matches baseline
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Did not run `npm run migrate up` against any environment in this PR
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Source scripts (no-go-zones, audit reference only):
|
||||
`scripts/add-user-profile-columns.js`, `scripts/add-user-profile-fields.js`
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit either source script or any file under `scripts/`.
|
||||
- DO NOT edit any other file under `migrations/`.
|
||||
- DO NOT edit `scripts/setup-neon-db.js`, `package.json`, README, `AGENTS.md`, or `docs/SCHEMA_MAP.md`.
|
||||
- DO NOT run `npm run migrate up` against any environment.
|
||||
- DO NOT pick one of `profile_image_url` / `avatar_url` to omit — both must be present for parity.
|
||||
- DO NOT collapse the 6 CHECK constraints into a single `DO $$ EXCEPTION` block — one block per constraint so one duplicate doesn't swallow the others.
|
||||
- DO NOT include the per-row UPDATE backfill DML.
|
||||
- DO NOT call `npm run migrate create`.
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
This is the largest single migration in the convoy because both historical scripts are tightly coupled to the `users` table surface and splitting them would create artificial boundaries (e.g., separating "users columns" from "CHECK constraints on users columns" makes no sense). Per-CHECK `DO $$ EXCEPTION` blocks mirror the historical scripts' per-statement try/catch pattern and ensure one duplicate-constraint failure doesn't block the rest. Keeping both avatar-style columns matches prod-as-is and explicitly defers the cleanup to a scoped follow-up convoy.
|
||||
|
|
@ -1,457 +0,0 @@
|
|||
---
|
||||
convoy: reconcile-historical-add-scripts
|
||||
brief_number: 7
|
||||
depends_on: [1, 2, 3, 4, 5]
|
||||
files:
|
||||
- docs/SCHEMA_MAP.md
|
||||
- docs/MIGRATION_VERIFICATION_RUNBOOK.md
|
||||
- AGENTS.md
|
||||
- .convoys/ship-readiness.md
|
||||
---
|
||||
|
||||
# Brief 7: Documentation + verification runbook
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Update the four documentation surfaces that describe the post-convoy schema and onboarding state — `docs/SCHEMA_MAP.md` (correct doc bugs + cross-reference new migrations), `docs/MIGRATION_VERIFICATION_RUNBOOK.md` (new — manual operator runbook from D5), `AGENTS.md` Gotcha #6 (cross-reference this convoy as the closing follow-up), `.convoys/ship-readiness.md` (flip this convoy's queued entry to RESOLVED + unblock `retire-graveyard-scripts-after-audit` + add new follow-ups) — so the next operator onboarding a fresh Neon branch can do so by `npm install` → `npm run setup-db` alone and verify the result.
|
||||
|
||||
## Scope (files in scope — do not edit anything else)
|
||||
|
||||
- `docs/SCHEMA_MAP.md` — **modified**
|
||||
- `docs/MIGRATION_VERIFICATION_RUNBOOK.md` — **new**
|
||||
- `AGENTS.md` — **modified** (small Gotcha #6 cross-reference update only)
|
||||
- `.convoys/ship-readiness.md` — **modified** (queued convoys section)
|
||||
|
||||
This brief is **sequenced last** because it cross-references the 5 new migration files that B1-B5 add; it cannot land before B1-B5 are merged. The architect's `slice_dependencies` block in the convoy file declares `depends_on: [1, 2, 3, 4, 5]`.
|
||||
|
||||
## Per-file scope
|
||||
|
||||
### 1. `docs/SCHEMA_MAP.md` — modified
|
||||
|
||||
Targeted edits (keep all other content as-is):
|
||||
|
||||
1. **Preamble update.** The current preamble (lines 1-18) notes that *"the initial backfill captures only the post-`setup-neon-db.js` shape. … A follow-up convoy (`reconcile-historical-add-scripts`) will fold the historical effects into the migration history; until then this file remains the curated reference for the full prod shape."* Replace with a sentence noting the convoy has **landed**, the migration history now captures the full prod shape, and the operator verification runbook lives at `docs/MIGRATION_VERIFICATION_RUNBOOK.md`. Bump the "Last reviewed" date.
|
||||
|
||||
2. **`### users` notes column updates** (lines 43-57): each row references `add-user-profile-columns.js` / `add-user-profile-fields.js` — leave those references in place (they're historical context); ADD a single line at the end of the table noting *"All columns above are now captured by `migrations/1781000000005_reconcile-user-profile.js` (B5 of `reconcile-historical-add-scripts`, 2026-06-14)."*
|
||||
|
||||
3. **`### cards` notes column updates** (lines 78-79): for the `quantity` and `favorited` rows, change the "Unused; consider dropping" annotation to *"Unused; captured by `migrations/1781000000001_reconcile-cards-columns.js` for fresh-env parity. Drop tracked as queued `drop-dead-cards-columns` follow-up."*
|
||||
|
||||
4. **`### user_cards` index/constraint notes** (lines 90-102): add a brief note clarifying the canonical constraint is `UNIQUE(user_id, card_id, is_foil)` (3-col) from initial-schema, and that `scripts/fix-user-cards-constraints.js`'s stricter 2-col variant was either never-applied or reverted (Finding 1 of the reconcile convoy → Outcome A, 2026-06-14). This is the SCHEMA_MAP equivalent of the Drift Finding 1 resolution.
|
||||
|
||||
5. **`### user_favorites` table** (lines 104-111): **FIX THE DOC BUG.** Current shape lists only `(user_id, card_id)`. Replace with the actual polymorphic shape per the runtime in `pages/api/favorites.js`:
|
||||
|
||||
```markdown
|
||||
### user_favorites
|
||||
|
||||
| Column | Type | Notes |
|
||||
| --- | --- | --- |
|
||||
| `id` | `SERIAL PK` | |
|
||||
| `user_id` | `INTEGER FK users(id) ON DELETE CASCADE` | |
|
||||
| `item_type` | `VARCHAR(50) NOT NULL` | `'card' | 'collection' | 'deck'` — polymorphic |
|
||||
| `item_id` | `INTEGER NOT NULL` | FK depends on `item_type`; not enforced at DB level |
|
||||
| `created_at` | `TIMESTAMP` | |
|
||||
| | | **UNIQUE(user_id, item_type, item_id)** |
|
||||
|
||||
Indexes: `idx_user_favorites_user_id`, `idx_user_favorites_item_type`,
|
||||
`idx_user_favorites_item_id`, `idx_user_favorites_user_type
|
||||
(user_id, item_type)` — all in `migrations/1781000000004_reconcile-favorites-system.js`.
|
||||
```
|
||||
|
||||
6. **`### collections` notes**: add a line at the bottom noting *"`visibility`, `tcg`, `tags`, `slug` (+ `idx_collections_slug` unique + `check_slug_format` CHECK), `image` are now captured by `migrations/1781000000002_reconcile-collections-columns.js`."*
|
||||
|
||||
7. **`### collection_permissions` + `### collection_activity` sections**: add a line at the bottom of each noting *"Captured by `migrations/1781000000003_reconcile-collaboration-tables.js`."*
|
||||
|
||||
8. **NEW SECTION: `### user_settings`** (currently a one-liner at line 217). Expand to a proper column table matching the actual schema:
|
||||
|
||||
```markdown
|
||||
### user_settings
|
||||
|
||||
Per-user key/value store for settings that don't warrant a column on `users`.
|
||||
Captured by `migrations/1781000000005_reconcile-user-profile.js`.
|
||||
|
||||
| Column | Type | Notes |
|
||||
| --- | --- | --- |
|
||||
| `id` | `SERIAL PK` | |
|
||||
| `user_id` | `INTEGER FK users(id) ON DELETE CASCADE` | |
|
||||
| `setting_key` | `VARCHAR(100) NOT NULL` | |
|
||||
| `setting_value` | `JSONB NOT NULL` | |
|
||||
| `created_at`, `updated_at` | `TIMESTAMP` default now | |
|
||||
| | | **UNIQUE(user_id, setting_key)** |
|
||||
|
||||
Indexes: `idx_user_settings_user_id`, `idx_user_settings_key`.
|
||||
```
|
||||
|
||||
9. **`### user_avatars` expansion** (currently one paragraph at lines 222-223). Replace with:
|
||||
|
||||
```markdown
|
||||
### user_avatars
|
||||
|
||||
Tracks uploaded avatar history. Captured by
|
||||
`migrations/1781000000005_reconcile-user-profile.js`. Older avatars
|
||||
are typically deleted from blob storage; verify the cleanup job runs.
|
||||
|
||||
| Column | Type | Notes |
|
||||
| --- | --- | --- |
|
||||
| `id` | `SERIAL PK` | |
|
||||
| `user_id` | `INTEGER FK users(id) ON DELETE CASCADE` | |
|
||||
| `filename` | `VARCHAR(255) NOT NULL` | |
|
||||
| `original_name` | `VARCHAR(255)` | |
|
||||
| `mime_type` | `VARCHAR(100)` | |
|
||||
| `file_size` | `INTEGER` | |
|
||||
| `file_path` | `TEXT NOT NULL` | |
|
||||
| `is_active` | `BOOLEAN DEFAULT true` | |
|
||||
| `created_at`, `updated_at` | `TIMESTAMP` default now | |
|
||||
|
||||
Indexes: `idx_user_avatars_user_id`, `idx_user_avatars_active (user_id, is_active)`.
|
||||
```
|
||||
|
||||
10. **`## Known schema smells` section updates** (lines 226-232):
|
||||
|
||||
- **Smell #2** (`is_public` vs `visibility`): add a sentence noting both columns are now captured by separate migrations (initial-schema for `is_public`, B2 for `visibility`); resolution lives in a future `unify-collection-visibility` follow-up.
|
||||
- **Smell #3** (`cards.quantity` + `cards.favorited`): add the cross-reference to the queued `drop-dead-cards-columns` follow-up.
|
||||
- **NEW: Smell #7 — `users.profile_image_url` vs `users.avatar_url`** (the parity smell that B5 perpetuates intentionally). Both columns are present for prod parity; cleanup is the queued `unify-user-avatar-column` follow-up.
|
||||
|
||||
11. **`## Regeneration` section update** (lines 234-245): the manual-regeneration instructions can be removed entirely since the migration history is now authoritative. Replace with:
|
||||
|
||||
```markdown
|
||||
## Regeneration
|
||||
|
||||
The migration history under `migrations/` is the authoritative source
|
||||
of truth. To verify this file matches a live env (prod, preview, or a
|
||||
fresh Neon branch), use the operator runbook at
|
||||
[`docs/MIGRATION_VERIFICATION_RUNBOOK.md`](MIGRATION_VERIFICATION_RUNBOOK.md).
|
||||
|
||||
When you add a new migration, update the relevant table section here
|
||||
in the same PR. New tables get a new `###` section with the same
|
||||
column-table shape.
|
||||
```
|
||||
|
||||
### 2. `docs/MIGRATION_VERIFICATION_RUNBOOK.md` — new
|
||||
|
||||
Lift verbatim from `.convoys/reconcile-historical-add-scripts.md` § Verification plan (D5), with a small intro framing it as the canonical operator runbook (not just a convoy artifact). Suggested skeleton:
|
||||
|
||||
```markdown
|
||||
# Migration verification runbook
|
||||
|
||||
How to verify that the migration history under `migrations/` produces
|
||||
the same schema as a long-lived environment (prod, preview, or
|
||||
similar). Use this runbook:
|
||||
|
||||
- **After this repo's `reconcile-historical-add-scripts` convoy** (the
|
||||
initial reconciliation), to confirm a fresh Neon branch reaches
|
||||
parity with prod via `npm install` → `npm run setup-db` alone.
|
||||
- **After any new migration lands on `main`**, to spot-check that
|
||||
applying the migration to prod (via the operator's
|
||||
`POSTGRES_URL=<prod> npm run migrate up`) produced the intended
|
||||
effect.
|
||||
- **When suspecting drift** between an env's actual schema and the
|
||||
migration history (rare; the migration history is authoritative).
|
||||
|
||||
This runbook is the manual precursor to the automated check planned
|
||||
in the queued `wire-migrate-into-ci` follow-up (see
|
||||
`.convoys/ship-readiness.md` § "Queued convoys").
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `pg_dump` (PostgreSQL 16+) installed locally.
|
||||
- `POSTGRES_URL` for the env you're verifying.
|
||||
- `ADMIN_INITIAL_PASSWORD` (for the fresh-branch onboarding step) —
|
||||
see `AGENTS.md` § 5 "Running locally".
|
||||
- A Neon account with permission to create a branch (or any other
|
||||
way to spin up a fresh Postgres DB on the same major version as
|
||||
prod).
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 1 — Snapshot the reference env's structural shape
|
||||
|
||||
Run against the env you consider canonical (usually prod):
|
||||
|
||||
\`\`\`bash
|
||||
POSTGRES_URL=<reference-url> pg_dump --schema-only --no-owner --no-acl \
|
||||
--schema=public > /tmp/reference-schema.sql
|
||||
\`\`\`
|
||||
|
||||
### Step 2 — Create a fresh DB and onboard via `setup-db`
|
||||
|
||||
Create a clean Neon branch from an **empty** parent (or any other
|
||||
fresh Postgres DB on the same major version):
|
||||
|
||||
\`\`\`bash
|
||||
POSTGRES_URL=<fresh-branch-url> \
|
||||
ADMIN_INITIAL_PASSWORD=$(openssl rand -base64 24) \
|
||||
npm run setup-db
|
||||
\`\`\`
|
||||
|
||||
`setup-db` runs `npm run migrate up` (applying every migration in
|
||||
`migrations/` in timestamp order) and seeds the admin user.
|
||||
|
||||
### Step 3 — Snapshot the fresh DB's structural shape
|
||||
|
||||
\`\`\`bash
|
||||
POSTGRES_URL=<fresh-branch-url> pg_dump --schema-only --no-owner --no-acl \
|
||||
--schema=public > /tmp/fresh-schema.sql
|
||||
\`\`\`
|
||||
|
||||
### Step 4 — Diff
|
||||
|
||||
\`\`\`bash
|
||||
diff <(sort /tmp/reference-schema.sql) <(sort /tmp/fresh-schema.sql)
|
||||
\`\`\`
|
||||
|
||||
**Expected non-material differences** (acceptable; do not chase):
|
||||
|
||||
- Constraint or index NAME differences. Prod constraints created via
|
||||
the historical `scripts/add-*` / `scripts/fix-*` jobs may have
|
||||
autogenerated tuple-UNIQUE names that differ from the migrations'
|
||||
explicit names.
|
||||
- Column-ORDER differences. Prod has columns in historical-script-ALTER
|
||||
order; fresh envs have them in migration-order.
|
||||
|
||||
**Material differences** (bug — fix before declaring verified):
|
||||
|
||||
- A column type, default, or NULL/NOT NULL state that differs.
|
||||
- A missing or extra table.
|
||||
- A missing or extra CHECK constraint that changes accepted values.
|
||||
- A missing or extra index that changes query plan shape.
|
||||
|
||||
## Supplementary spot-checks
|
||||
|
||||
For the highest-risk surfaces (frequently-edited tables), run these
|
||||
information-schema queries against both envs and confirm the
|
||||
column-count / constraint-count / index-count totals match exactly:
|
||||
|
||||
\`\`\`sql
|
||||
-- Every column on every table
|
||||
SELECT table_name, column_name, data_type, is_nullable, column_default
|
||||
FROM information_schema.columns
|
||||
WHERE table_schema = 'public'
|
||||
ORDER BY table_name, ordinal_position;
|
||||
|
||||
-- Every constraint
|
||||
SELECT table_name, constraint_name, constraint_type
|
||||
FROM information_schema.table_constraints
|
||||
WHERE table_schema = 'public'
|
||||
ORDER BY table_name, constraint_name;
|
||||
|
||||
-- Every index
|
||||
SELECT tablename, indexname, indexdef
|
||||
FROM pg_indexes
|
||||
WHERE schemaname = 'public'
|
||||
ORDER BY tablename, indexname;
|
||||
\`\`\`
|
||||
|
||||
A mismatch in column count, constraint count, or index count is a
|
||||
material difference and indicates a bug.
|
||||
|
||||
## What to do if you find a material difference
|
||||
|
||||
1. **Identify which env is canonical.** Usually prod. If the diff
|
||||
surfaces a missing column on prod that's in the migration history,
|
||||
the migration was never applied to prod — run
|
||||
`POSTGRES_URL=<prod> npm run migrate up` to catch up.
|
||||
2. **If the diff surfaces a column on prod that's NOT in the
|
||||
migration history**, you've found a drift bug. Write a new
|
||||
reconciliation migration (under `migrations/`) that captures the
|
||||
prod column, following the pattern in `.convoys/reconcile-historical-add-scripts/`.
|
||||
3. **Do not edit existing migrations** — they're pinned by
|
||||
`pgmigrations` rows. Always write a new dated migration to correct
|
||||
schema.
|
||||
|
||||
## Cross-references
|
||||
|
||||
- `AGENTS.md` § 4 Gotcha #6 — migration tool adoption history.
|
||||
- `.convoys/migration-tool.md` — the convoy that adopted `node-pg-migrate`.
|
||||
- `.convoys/reconcile-historical-add-scripts.md` — the convoy that folded
|
||||
the 13 historical scripts into the migration history.
|
||||
- `.cursor/rules/db-and-schema.mdc` — schema-change conventions.
|
||||
```
|
||||
|
||||
### 3. `AGENTS.md` — modified (small Gotcha #6 cross-reference)
|
||||
|
||||
Gotcha #6 is already "RESOLVED" per `migration-tool` (2026-05-26). This brief adds **one sentence** to the end of Gotcha #6 cross-referencing this convoy as the closing follow-up. Verbatim addition (insert immediately before the `- **#7**` line at AGENTS.md line 120):
|
||||
|
||||
> Post-`reconcile-historical-add-scripts` (2026-06-14), the
|
||||
> migration history additionally captures the full effect of the 13
|
||||
> historical `scripts/add-*.js` / `scripts/fix-*.js` /
|
||||
> `scripts/seed-*.js` jobs (where applicable — pure-DML seed scripts
|
||||
> stay out per D4 of that convoy). A brand-new Neon branch can now be
|
||||
> onboarded by `npm install` → `npm run setup-db` alone. Operator
|
||||
> verification runbook at
|
||||
> [`docs/MIGRATION_VERIFICATION_RUNBOOK.md`](docs/MIGRATION_VERIFICATION_RUNBOOK.md).
|
||||
> The 13 historical scripts remain no-go-zones until the queued
|
||||
> `retire-graveyard-scripts-after-audit` (P3) cleanup convoy lands;
|
||||
> that convoy is now unblocked.
|
||||
|
||||
Do NOT flip Gotcha #6's RESOLVED marker — it's already RESOLVED by the right convoy (`migration-tool`). Just append the cross-reference.
|
||||
|
||||
### 4. `.convoys/ship-readiness.md` — modified (queued convoys section)
|
||||
|
||||
Find the existing line under § "Queued convoys" that reads:
|
||||
|
||||
> - **`reconcile-historical-add-scripts`** (priority: P1 quality — needed for fresh-env onboarding). Surfaced 2026-05-26 by `migration-tool` (PR #32). Fold the effects of the 27 historical `scripts/add-*.js` / `fix-*.js` / `seed-*.js` jobs … Documented in `.convoys/migration-tool.md` § R1.
|
||||
|
||||
Replace with:
|
||||
|
||||
> - **`reconcile-historical-add-scripts`** — **RESOLVED 2026-06-14** by [convoy](../.convoys/reconcile-historical-add-scripts.md) (PRs #XX-#XX). Captured 7 of the 13 historical scripts' effects into 5 new migrations under `migrations/` (B1-B5); 2 scripts were already captured by `initial-schema` + `1780378340194_system-collection-description`; 3 are DML-only and stay as dev fixtures; 1 (`fix-user-cards-constraints.js`) is a no-op on prod per Finding 1 (Outcome A — the canonical 3-col `UNIQUE(user_id, card_id, is_foil)` from `initial-schema` is what prod has, and `fix-user-cards-constraints.js`'s stricter 2-col variant is not present). A brand-new Neon branch now onboards via `npm install` → `npm run setup-db` alone. Operator verification at [`docs/MIGRATION_VERIFICATION_RUNBOOK.md`](../docs/MIGRATION_VERIFICATION_RUNBOOK.md). Entry kept (not deleted) for audit trail.
|
||||
|
||||
Find the existing line:
|
||||
|
||||
> - **`retire-graveyard-scripts-after-audit`** (priority: P3 polish; **blocked on `reconcile-historical-add-scripts`**). …
|
||||
|
||||
Replace the `**blocked on `reconcile-historical-add-scripts`**` marker with `**UNBLOCKED 2026-06-14**` and leave the rest of the description intact.
|
||||
|
||||
Add two new queued entries (driven by Findings 2 + 3 of the reconcile convoy):
|
||||
|
||||
> - **`unify-user-avatar-column`** (priority: P3 hygiene). Surfaced 2026-06-14 by `reconcile-historical-add-scripts` Finding 2. `users.profile_image_url` (added by `scripts/add-user-profile-columns.js`) and `users.avatar_url` (added by `scripts/add-user-profile-fields.js`) coexist on prod and in the migration history (both columns are needed for parity per B5). Pick one canonical column, migrate the other's data to it, drop the loser, and sweep runtime readers in `pages/api/user/avatar*.js` + UI surfaces. Requires a query-trace audit first.
|
||||
> - **`drop-dead-cards-columns`** (priority: P3 hygiene). Surfaced 2026-06-14 by `reconcile-historical-add-scripts` Finding 3. `cards.quantity INTEGER` and `cards.favorited BOOLEAN` are documented unused (per `docs/SCHEMA_MAP.md` § "Known schema smells" #3); reconciled into the migration history by B1 for parity, but the actual semantics live on `user_cards` / `user_favorites`. After a query-trace audit confirms zero runtime readers, ship a migration that DROPs both columns with a real `down()` that recreates them.
|
||||
|
||||
(Do NOT add the withdrawn `add-system-collection-on-register` or `unify-user-cards-foil-tracking` entries — both were withdrawn during the reconcile convoy. See `.convoys/reconcile-historical-add-scripts.md` § Follow-ups.)
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `.cursor/rules/no-go-zones.mdc` — no edits to `scripts/add-*` / `fix-*` / `seed-*`.
|
||||
- `.cursor/rules/db-and-schema.mdc` — schema-change conventions; SCHEMA_MAP is updated alongside any migration.
|
||||
- Markdown style: match the existing tone of `docs/SCHEMA_MAP.md` (compact tables, "Notes" column explains intent not type semantics) and `AGENTS.md` (numbered Gotchas, cross-reference convoy files).
|
||||
- For `.convoys/ship-readiness.md`: match the existing entry style under § "Queued convoys" (one bullet per convoy, leading `- **`name`**`, RESOLVED entries get the "Entry kept (not deleted) for audit trail" closer when applicable).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `docs/SCHEMA_MAP.md` preamble bumped (post-convoy state); "Last reviewed" date is 2026-06-14.
|
||||
- [ ] `docs/SCHEMA_MAP.md` § `user_favorites` shape is the polymorphic `(item_type, item_id)` — NOT the previous `(card_id)` shape.
|
||||
- [ ] Every reconciled table/column has a "captured by `migrations/<file>`" cross-reference.
|
||||
- [ ] `### user_settings` and `### user_avatars` sections are expanded from one-liners to full column tables matching B5's migration.
|
||||
- [ ] New schema smell #7 (`profile_image_url` vs `avatar_url`) is added to § "Known schema smells".
|
||||
- [ ] `docs/MIGRATION_VERIFICATION_RUNBOOK.md` exists with the 4-step procedure from D5 + the spot-check queries + the "material vs non-material differences" guidance.
|
||||
- [ ] `AGENTS.md` Gotcha #6 gains a single appended paragraph cross-referencing this convoy + the new runbook + the unblocked `retire-graveyard-scripts-after-audit` follow-up. Gotcha #6's existing "RESOLVED by `migration-tool`" marker is NOT changed.
|
||||
- [ ] `.convoys/ship-readiness.md` § "Queued convoys" → `reconcile-historical-add-scripts` entry is flipped to RESOLVED 2026-06-14 with a one-paragraph summary; `retire-graveyard-scripts-after-audit` is marked UNBLOCKED 2026-06-14; two new entries (`unify-user-avatar-column`, `drop-dead-cards-columns`) are added.
|
||||
- [ ] No edits to any file under `scripts/`, `migrations/`, `pages/`, `lib/`, `components/`, `test/`, or `package.json`.
|
||||
- [ ] `npm run lint` matches baseline (these are markdown-only edits; lint should be unaffected).
|
||||
- [ ] `npm run test:run` reports 21/21 passing (these are markdown-only edits; no test surface).
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
Both must match baseline / be green. No additional verification for this brief — the migrations themselves are exercised by Brief 7's verification runbook AFTER an operator runs it manually post-merge.
|
||||
|
||||
For the SCHEMA_MAP edits, eyeball the diff against the prior state and confirm every cross-reference to a migration file is accurate (the file actually exists, and the timestamp matches the assigned reservation).
|
||||
|
||||
## Commit message
|
||||
|
||||
```
|
||||
docs(reconcile): update SCHEMA_MAP, verification runbook, AGENTS, ship-readiness (brief 7/7)
|
||||
|
||||
Closes the reconcile-historical-add-scripts convoy:
|
||||
|
||||
- docs/SCHEMA_MAP.md: cross-reference 5 new migrations from B1-B5;
|
||||
fix user_favorites doc bug (polymorphic shape, not (card_id));
|
||||
expand user_settings + user_avatars one-liners to full column tables;
|
||||
add schema smell #7 (profile_image_url vs avatar_url redundancy).
|
||||
- docs/MIGRATION_VERIFICATION_RUNBOOK.md (new): canonical operator
|
||||
runbook for verifying fresh-env vs prod schema parity (lifted from
|
||||
D5 of the convoy).
|
||||
- AGENTS.md Gotcha #6: append cross-reference to this convoy + the
|
||||
new runbook + the now-unblocked retire-graveyard-scripts-after-audit
|
||||
follow-up. Existing "RESOLVED by migration-tool" marker unchanged.
|
||||
- .convoys/ship-readiness.md: flip reconcile-historical-add-scripts
|
||||
entry to RESOLVED 2026-06-14; mark retire-graveyard-scripts-after-audit
|
||||
UNBLOCKED; add new queued unify-user-avatar-column (Finding 2) +
|
||||
drop-dead-cards-columns (Finding 3).
|
||||
|
||||
Per .convoys/reconcile-historical-add-scripts.md § Brief outline → B7.
|
||||
Depends on B1-B5 having merged (this brief cross-references their files).
|
||||
```
|
||||
|
||||
## PR shape
|
||||
|
||||
**Title:** `docs(reconcile): update SCHEMA_MAP, verification runbook, AGENTS, ship-readiness (brief 7/7)`
|
||||
|
||||
**Body template:**
|
||||
|
||||
```markdown
|
||||
Brief 7 (final) of the `reconcile-historical-add-scripts` convoy.
|
||||
See [`.convoys/reconcile-historical-add-scripts.md`](../.convoys/reconcile-historical-add-scripts.md)
|
||||
for the full plan and rationale.
|
||||
|
||||
This is the closing brief — depends on B1-B5 having merged (PR
|
||||
references below).
|
||||
|
||||
## What this PR does
|
||||
|
||||
- **`docs/SCHEMA_MAP.md`** — cross-reference all 5 new migrations from
|
||||
B1-B5; fix the `user_favorites` doc bug (the table uses the
|
||||
polymorphic `(item_type, item_id)` shape, not `(card_id)`); expand
|
||||
`user_settings` + `user_avatars` from one-liners to full column
|
||||
tables matching the B5 migration; add a new "Known schema smell" #7
|
||||
for the `profile_image_url` / `avatar_url` redundancy.
|
||||
- **`docs/MIGRATION_VERIFICATION_RUNBOOK.md`** (new) — canonical
|
||||
operator runbook for verifying fresh-env vs prod schema parity.
|
||||
Pulls verbatim from D5 of the convoy file. Useful both for the
|
||||
one-time reconciliation verification and for ongoing post-migration
|
||||
spot-checks.
|
||||
- **`AGENTS.md`** — append one paragraph to Gotcha #6 cross-referencing
|
||||
this convoy as the closing follow-up. The "RESOLVED by `migration-tool`"
|
||||
marker is unchanged (that's still the right resolution attribution
|
||||
for the gotcha itself).
|
||||
- **`.convoys/ship-readiness.md`** § "Queued convoys" — flip the
|
||||
`reconcile-historical-add-scripts` entry to RESOLVED 2026-06-14;
|
||||
flip `retire-graveyard-scripts-after-audit` from "blocked on
|
||||
reconcile-historical-add-scripts" to UNBLOCKED 2026-06-14; add two
|
||||
new queued entries (`unify-user-avatar-column` from Finding 2,
|
||||
`drop-dead-cards-columns` from Finding 3).
|
||||
|
||||
## Prerequisite PRs (all must be merged first)
|
||||
|
||||
- B1 #XX — reconcile cards columns
|
||||
- B2 #XX — reconcile collections columns
|
||||
- B3 #XX — reconcile collaboration tables
|
||||
- B4 #XX — reconcile favorites system
|
||||
- B5 #XX — reconcile user profile
|
||||
|
||||
## What this PR does NOT do
|
||||
|
||||
- Does **NOT** edit any file under `migrations/`, `scripts/`, `pages/`,
|
||||
`lib/`, `components/`, `test/`, or `package.json`.
|
||||
- Does **NOT** run the verification runbook itself — that's the
|
||||
operator's post-merge job; see the runbook's "Procedure" section.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] `npm run lint` matches baseline
|
||||
- [ ] `npm run test:run` reports 21/21 passing
|
||||
- [ ] Every "captured by `migrations/<file>.js`" cross-reference in
|
||||
SCHEMA_MAP points at a file that actually exists in `migrations/`
|
||||
(eyeballed against `ls migrations/`)
|
||||
- [ ] `AGENTS.md` Gotcha #6 still has its original RESOLVED marker
|
||||
(we only APPEND to it, not rewrite it)
|
||||
- [ ] `.convoys/ship-readiness.md` § "Queued convoys" has the flipped
|
||||
`reconcile-historical-add-scripts` entry, the UNBLOCKED
|
||||
`retire-graveyard-scripts-after-audit` marker, and the two new
|
||||
follow-up entries
|
||||
- [ ] Operator post-merge: run `docs/MIGRATION_VERIFICATION_RUNBOOK.md`
|
||||
against prod + a fresh Neon branch and confirm the diff is
|
||||
non-material
|
||||
|
||||
## Cross-references
|
||||
|
||||
- Convoy file: `.convoys/reconcile-historical-add-scripts.md`
|
||||
- Per-brief files: `.convoys/reconcile-historical-add-scripts/brief-{1,2,3,4,5}-*.md`
|
||||
```
|
||||
|
||||
## DO NOT
|
||||
|
||||
- DO NOT edit any file under `scripts/`, `migrations/`, `pages/`, `lib/`, `components/`, `test/`.
|
||||
- DO NOT edit `package.json`, README, `next.config.js`, or any rule under `.cursor/rules/`.
|
||||
- DO NOT change `AGENTS.md` Gotcha #6's "RESOLVED by `migration-tool`" marker — append the new paragraph; don't rewrite the existing resolution attribution.
|
||||
- DO NOT add a `B6` reference anywhere — that brief was removed (Finding 1 → Outcome A).
|
||||
- DO NOT add `add-system-collection-on-register` or `unify-user-cards-foil-tracking` to the ship-readiness queued list — both were withdrawn during this convoy.
|
||||
- DO NOT remove the existing `wire-migrate-into-ci` entry from ship-readiness — it's still queued and unrelated to this convoy.
|
||||
- DO NOT run the verification runbook itself (that's the operator's post-merge step).
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Sequencing this brief last lets every documentation cross-reference point at a real file under `migrations/` rather than a placeholder. Bundling all four doc surfaces into one PR keeps the convoy's "as-shipped" record consistent (the migrations, the operator runbook, the AGENTS gotcha, and the ship-readiness ledger all flip together). The `docs/MIGRATION_VERIFICATION_RUNBOOK.md` extraction promotes a one-time convoy artifact into an evergreen operator tool that future migrations can reuse.
|
||||
|
|
@ -1,233 +0,0 @@
|
|||
---
|
||||
name: scan-visual-catalog-search
|
||||
classification: feature
|
||||
success_metric: |
|
||||
After catalog embeddings exist and the new kNN path is on, ≥50% of
|
||||
legitimate card scans (scan_attempts excluding not_a_card) auto-match
|
||||
a printing with no picker — the original add-real-ocr-layer 70%
|
||||
target, measured honestly. Gemini L2 share of attempts falls vs the
|
||||
Phase 1 post-ship baseline.
|
||||
skip:
|
||||
- ia
|
||||
- ui-design
|
||||
- visual
|
||||
- a11y
|
||||
- design
|
||||
- flag
|
||||
status: shipped
|
||||
created: 2026-08-14
|
||||
depends_on:
|
||||
- improve-scan-card-detection
|
||||
umbrella: scanner-identify-upgrade
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
|
||||
# Convoy: scan-visual-catalog-search
|
||||
|
||||
Phase 3 of `scanner-identify-upgrade`. Identify cards by **what they
|
||||
look like**, not by reading the name. This is how Manabox / Delver-style
|
||||
scanners get printing-accurate matches on foil and alt-art.
|
||||
|
||||
Blocked on `improve-scan-card-detection`: embeddings of unwarped
|
||||
phone crops will not match catalog `image_url`s reliably.
|
||||
|
||||
## Why
|
||||
|
||||
Name-only `pg_trgm` cannot distinguish printings. Tesseract fails on
|
||||
foil and stylized type even when it emits 8–20 characters (76.7% L1
|
||||
escalate with non-empty text). Gemini can read a name but still
|
||||
returns a picker when set/number are missing, and costs 5/min.
|
||||
|
||||
The catalog already stores `cards.image_url` for every imported
|
||||
printing. Precompute an embedding per row; at scan time embed the
|
||||
warped crop and take top-k cosine. OCR / Gemini become hints and
|
||||
unknown-card fallback.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- **Migration:** `pgvector` (confirm Neon availability) +
|
||||
`cards.embedding` (or a side table `card_embeddings`) + ANN index.
|
||||
Update `docs/SCHEMA_MAP.md`.
|
||||
- **Offline embed job:** new dated script or `npm run` task that
|
||||
reads `image_url`, writes vectors. Idempotent. Rate-limit the
|
||||
embedding provider. Do **not** edit historical `scripts/add-*.js`.
|
||||
- **Architect picks the embedder** (one):
|
||||
1. Gateway embedding model (same `AI_GATEWAY_API_KEY`, server-only).
|
||||
2. In-browser MobileCLIP-S2 / SigLIP ONNX for the *query* crop, with
|
||||
catalog vectors baked or fetched — only if weight license + size
|
||||
are acceptable.
|
||||
- **Identify path:** new Layer-0 (or replace L1) — kNN then
|
||||
auto-match / disambiguate / escalate to existing L2. Log
|
||||
`scan_attempts.layer = 0` (or Architect-ratified value).
|
||||
- **Similarity thresholds** analogous to 0.85 / 0.60, tuned on a
|
||||
held-out set of scan captures if any exist in Blob.
|
||||
- Auth + rate-limit on any new route. No client-side API keys
|
||||
(`forbidden-client-side-llm-keys` must stay green).
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Replacing Gemini entirely on day one — keep L2 for catalog misses
|
||||
and low similarity.
|
||||
- Training a custom card CNN.
|
||||
- Python GPU service.
|
||||
- Changing scanner chrome / cart.
|
||||
- Auto-approving the 27 pending `card_submissions`.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-architect` — embedder, schema, layer numbering, thresholds,
|
||||
brief split (migration / backfill / route). Security-sensitive:
|
||||
escalate to Sonnet if schema + new route land together.
|
||||
2. `role-implementer`.
|
||||
3. Audit: `role-reviewer` + `role-security-auditor` (required).
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] Architect: confirm `pgvector` on prod Neon tier
|
||||
- [x] Brief 1 — migration + SCHEMA_MAP
|
||||
- [x] Brief 2 — catalog backfill job (idempotent)
|
||||
- [x] Brief 3 — identify kNN route + client escalate order
|
||||
- [x] Threshold bake-off on real crops (initial: 0.82 match / 0.58 disambig — tune post-backfill)
|
||||
- [ ] Re-measure auto-match % excluding `not_a_card` (blocked: L0 traffic + backfill)
|
||||
- [ ] Operator: finish `npm run backfill-embeddings` — **14.9%** (9,865 / 66,211) as of 2026-08-15
|
||||
|
||||
## Post-ship (2026-08-15)
|
||||
|
||||
**Merged:** PR #160 (Layer-0 visual catalog search), PR #162 (CI gates).
|
||||
|
||||
**Pipeline roles (kickoff complete):**
|
||||
|
||||
| Role | Outcome |
|
||||
| --- | --- |
|
||||
| Conductor | Convoy ratified; skip ia/ui-design/visual/a11y/design/flag |
|
||||
| UX reviewer | No new screens; L0→L1→L2 order; silent escalate when index empty |
|
||||
| Architect | D1–D4 decisions + 3 briefs (`.convoys/scan-visual-catalog-search/brief-*`) |
|
||||
| Implementer | Briefs 1–3 shipped in #160 |
|
||||
| Reviewer + security-auditor | #160 audit fan-out; #162 CI fix |
|
||||
| Doc-writer | SCHEMA_MAP layer 0 documented |
|
||||
|
||||
**CI fixes (#162):** `lib/card-embed.js` allowlist + pgvector migration graceful
|
||||
skip on non-superuser homelab CI.
|
||||
|
||||
**Neon:** pgvector v0.8.0; `cards.embedding vector(1024)` + HNSW index applied.
|
||||
Backfill **in progress** (9,865 / 66,211 = 14.9%). **0** `scan_attempts` with
|
||||
`layer = 0` yet — L0 path live but index too sparse / no post-#160 scans logged.
|
||||
|
||||
**scan_attempts snapshot** (all-time n=250):
|
||||
|
||||
| Signal | Value | Baseline |
|
||||
| --- | --- | --- |
|
||||
| L1 escalate | 78.4% (87/111) | 76.7% |
|
||||
| L1 matched | 5.4% (6/111) | 5.8% |
|
||||
| L2 not_a_card | 43.9% (61/139) | 44.6% |
|
||||
| End-to-end auto-match | 13.2% excl. not_a_card | 13.5% |
|
||||
| L0 attempts | 0 | — |
|
||||
|
||||
**Aug 15 session (n=26):** See umbrella `.convoys/scanner-identify-upgrade.md`
|
||||
§ Post-ship telemetry.
|
||||
|
||||
Re-measure after backfill completes and preview scanning generates L0 rows.
|
||||
|
||||
## Likely file ownership
|
||||
|
||||
| Area | Files |
|
||||
| --- | --- |
|
||||
| Schema | `migrations/*_card-embeddings.js`, `docs/SCHEMA_MAP.md` |
|
||||
| Backfill | new `scripts/` job (dated) or `lib/card-embed-backfill.js` |
|
||||
| Query | new `lib/card-visual-match.js`, `pages/api/scan/identify-by-image.js` **or** fold into existing identify |
|
||||
| Client | `lib/scanner-card-identify.js` (`tryLayer1TextIdentify` sibling) |
|
||||
|
||||
Do not rewrite `lib/scanner-card-detection.js` here.
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
Brief 1 first. Brief 2 after 1. Brief 3 after 1 (can overlap 2 if the
|
||||
route degrades to escalate-when-empty-index).
|
||||
|
||||
```
|
||||
/multitask role-reviewer + role-security-auditor
|
||||
```
|
||||
|
||||
Group id: `audit-scan-visual-catalog-search-<pr>`.
|
||||
|
||||
## CI impact
|
||||
|
||||
| Workflow / job | Behavior |
|
||||
| --- | --- |
|
||||
| `schema-map-fresh` | **Fires** — migration + SCHEMA_MAP |
|
||||
| `ci.yml` migrate | Must apply `pgvector` on CT 102 CI Postgres — Architect must verify the extension is available there or gate the migration |
|
||||
| `forbidden-client-side-llm-keys` | Blocking |
|
||||
|
||||
## Operator action
|
||||
|
||||
- Confirm Neon `pgvector` (or Neon’s equivalent) on the prod project.
|
||||
- Budget: one embedding per catalog image, plus one per live scan if
|
||||
the query embed is server-side. Architect publishes a cost note
|
||||
before Brief 2 runs against prod images.
|
||||
- No new browser secrets.
|
||||
|
||||
## Conductor notes
|
||||
|
||||
This is the accuracy leap. Do not start it to "try CLIP" before Phase 2
|
||||
crops are rectified — that wastes the backfill. If Architect finds
|
||||
`pgvector` unavailable on CI Postgres, stop and write a fallback
|
||||
(external index vs skip-CI-extension plan) rather than shipping an
|
||||
untestable migration.
|
||||
|
||||
## UX
|
||||
|
||||
No new screens. Scan flow stays L0 → L1 → L2 with the same
|
||||
disambiguation picker and error toasts. When the catalog index is empty
|
||||
(backfill not run), L0 escalates silently with no embed cost.
|
||||
|
||||
Gallery uploads now try visual match before OCR.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Decision D1 — Gateway multimodal embedder (`cohere/embed-v4.0`)
|
||||
|
||||
Server-only via `AI_GATEWAY_API_KEY`. 1024-dim vectors in
|
||||
`cards.embedding`. Env: `SCAN_EMBED_MODEL`, `SCAN_EMBED_DIMENSION`.
|
||||
|
||||
### Decision D2 — Layer numbering
|
||||
|
||||
| Layer | Path |
|
||||
| --- | --- |
|
||||
| 0 | `POST /api/scan/identify-by-image` |
|
||||
| 1 | Tesseract + `identify-by-text` |
|
||||
| 2 | Gemini + `scan/identify` |
|
||||
|
||||
### Decision D3 — Thresholds
|
||||
|
||||
Match ≥ **0.82** (0.06 gap). Disambiguation ≥ **0.58**.
|
||||
|
||||
### Decision D4 — Rate limit
|
||||
|
||||
`checkScanRateLimit` on identify-by-image. L0 429 falls through to L1
|
||||
(not a hard stop).
|
||||
|
||||
Audit group id: `audit-scan-visual-catalog-search-<pr>`.
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
---
|
||||
convoy: scan-visual-catalog-search
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5
|
||||
model_tier: standard
|
||||
files:
|
||||
- migrations/1782000000001_add-card-embeddings.js
|
||||
- docs/SCHEMA_MAP.md
|
||||
---
|
||||
|
||||
# Brief 1: pgvector migration + SCHEMA_MAP
|
||||
|
||||
## Goal
|
||||
|
||||
Add `vector(1024)` embedding column + HNSW index on `cards`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `CREATE EXTENSION IF NOT EXISTS vector`
|
||||
- [ ] `cards.embedding`, `cards.embedded_at`
|
||||
- [ ] `idx_cards_embedding_hnsw` partial index
|
||||
- [ ] SCHEMA_MAP documents layer 0 + pgvector
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
---
|
||||
convoy: scan-visual-catalog-search
|
||||
brief_number: 2
|
||||
depends_on: [1]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/card-embed.js
|
||||
- scripts/backfill-card-embeddings.js
|
||||
- package.json
|
||||
- test/lib/card-embed.test.js
|
||||
---
|
||||
|
||||
# Brief 2: Catalog embedding backfill
|
||||
|
||||
## Goal
|
||||
|
||||
Server-side embed job using `cohere/embed-v4.0` via AI Gateway; idempotent backfill from `cards.image_url`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `lib/card-embed.js` exports `embedCardImage`, `formatEmbeddingForPg`
|
||||
- [ ] `npm run backfill-embeddings` script (skips rows with embedding unless FORCE=1)
|
||||
- [ ] Rate-limited (`SLEEP_MS`) and DRY_RUN support
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
convoy: scan-visual-catalog-search
|
||||
brief_number: 3
|
||||
depends_on: [1]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/card-visual-match.js
|
||||
- pages/api/scan/identify-by-image.js
|
||||
- lib/scanner-card-identify.js
|
||||
- lib/use-scanner-identification.js
|
||||
- test/lib/card-visual-match.test.js
|
||||
---
|
||||
|
||||
# Brief 3: Layer-0 identify route + client orchestration
|
||||
|
||||
## Goal
|
||||
|
||||
kNN visual match before L1/L2; log `scan_attempts.layer = 0`.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `POST /api/scan/identify-by-image` — auth + `checkScanRateLimit` + embed + kNN
|
||||
- [ ] `identifyTrackedCardCapture` order: L0 → L1 → L2
|
||||
- [ ] Gallery path runs L0 → L1 → L2
|
||||
- [ ] Skip auto Gemini refine when disambiguation from L0 (same as L1)
|
||||
- [ ] Thresholds: match 0.82, disambiguation 0.58
|
||||
|
|
@ -1,902 +0,0 @@
|
|||
---
|
||||
name: scanner-desktop-layout
|
||||
classification: feature
|
||||
success_metric: |
|
||||
On md+ viewports, /scanner keeps the desktop app chrome (sidebar +
|
||||
top bar), shows a framed camera workstation with a real webcam
|
||||
device picker, Upload Image, Batch Scan, Auto-detect, Scanner
|
||||
Tips, a live match inspector, and a bottom strip with Recent
|
||||
Scans / Scan Queue / Duplicates — without regressing the mobile
|
||||
immersive checkout.
|
||||
skip: []
|
||||
status: shipped
|
||||
created: 2026-08-15
|
||||
depends_on:
|
||||
- scanner-mobile-checkout
|
||||
- scanner-rebuild
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
design_direction:
|
||||
source: role-ui-designer
|
||||
skill: ui-ux-pro-max
|
||||
skill_version: "2.5.0"
|
||||
version: 1
|
||||
locked_at: 2026-08-15
|
||||
product_type: desktop trading card scanner workstation
|
||||
pattern: Feature-Rich Showcase (workstation variant)
|
||||
style: Liquid Glass / glassmorphism
|
||||
stack: nextjs
|
||||
layout_reference: image-1eeebe23-9983-4a96-a3e7-4e3cdfdceb5b.png
|
||||
---
|
||||
|
||||
# Convoy: scanner-desktop-layout
|
||||
|
||||
Give `/scanner` a dedicated desktop workstation layout from the
|
||||
attached dark/light mock (camera + live result + history strip),
|
||||
while leaving the shipped mobile immersive checkout alone.
|
||||
|
||||
Worktree: `tcg-vault-worktrees/scanner-desktop-layout` on
|
||||
`convoy/scanner-desktop-layout` (branched from `origin/main` @
|
||||
`0d52858`). Layout reference:
|
||||
`image-1eeebe23-9983-4a96-a3e7-4e3cdfdceb5b.png`.
|
||||
|
||||
Do **not** land this on `dashboard-home-realignment` — that convoy
|
||||
owns sidebar IA + top-bar chrome. Do **not** land this on
|
||||
`scanner-identify-upgrade` — that epic owns detect/identify accuracy.
|
||||
|
||||
## Why
|
||||
|
||||
`scanner-mobile-checkout` shipped the phone job: full-bleed camera,
|
||||
local cart, checkout sheet. Desktop (`md+`) got the leftover
|
||||
composition — the same camera chrome plus a 360px cart side panel
|
||||
(`ScannerReview` `variant="side-panel"`). That is not a desk
|
||||
workstation.
|
||||
|
||||
On a laptop the user wants to see the webcam, inspect the current
|
||||
match (set, rarity, number, condition, foil, confidence), decide
|
||||
what to do with it, and keep a history/queue in view — without
|
||||
losing the app sidebar or search bar. The mock is that layout.
|
||||
Today they get a phone overlay stretched into a column.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- **Desktop-only composition (`md+`).** Keep Layout sidebar +
|
||||
TopSearchBar. Stop treating desktop as an immersive camera page
|
||||
with a bolted-on cart. Mobile (`max-md`) stays
|
||||
`chrome="immersive"` + checkout sheet.
|
||||
- **Framed camera viewport.** Large live feed with ember corner
|
||||
brackets (already in `ScannerCamera`), Auto-detect status, and
|
||||
desk controls under the frame. Camera is a panel in the page,
|
||||
not a full-bleed overlay.
|
||||
- **Real webcam device picker.** `enumerateDevices` + `deviceId`
|
||||
in `useCameraScanner` (not facing-mode swap relabeled). Persist
|
||||
the last-used device for the tab if cheap. Empty-list / denied-
|
||||
permission fallback. Mobile keeps the existing facing-mode
|
||||
toggle — do not replace the phone chrome with a device `<select>`.
|
||||
- **Upload Image + Batch Scan.** Upload Image stays single-file
|
||||
(existing gallery path). **Batch Scan** is a multi-file picker
|
||||
that runs each image through `identifyFromGalleryFile`
|
||||
**sequentially** (respect existing identify rate limits; no
|
||||
parallel Gemini storm, no new batch API). Progress and failures
|
||||
show in Scan Queue. Live multi-card on the webcam stays
|
||||
Auto-detect — do not build a new pile-in-one-frame detector.
|
||||
- **Scanner Tips.** Header control from the mock. Glass popover
|
||||
or modal (use `<Modal>` / `GlassSurface`, no custom scrim) with
|
||||
short lighting / framing / foil / auto-detect guidance. No new
|
||||
route. Copy authored in this convoy (IA + UI Designer).
|
||||
- **Live match inspector (right rail).** Current identify result:
|
||||
thumbnail, name, set, rarity, collector number, condition,
|
||||
foil, confidence, primary add, Rescan. This replaces the cart
|
||||
list as the primary right-hand surface.
|
||||
- **Bottom history / queue strip.** Three tabs over the existing
|
||||
cart + ownership model: **Recent Scans** (session history),
|
||||
**Scan Queue** (uncommitted cart), **Duplicates** (already in
|
||||
My Collection via `ownershipMap`, and/or same-session
|
||||
name+set repeats from `mergeScannedCardEntry`). Badge counts
|
||||
on Queue and Duplicates. Clear + view-all as IA/UX refine.
|
||||
- **Reuse, don't rewrite, the scan engine.** Same hooks:
|
||||
`useCameraScanner`, `useScannerIdentification`, `useScannerQueue`,
|
||||
`scanner-session`. Identify / OCR / Gemini stay out.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Identify / detection / Gemini (`lib/scanner-card-identify.js`,
|
||||
`pages/api/scan/identify.js`, OpenCV). Sibling:
|
||||
`scanner-identify-upgrade`.
|
||||
- Mobile immersive checkout, scan peek, or checkout sheet — no
|
||||
visual or interaction regression below `md`.
|
||||
- Layout nav IA, Daily Ember, notifications, profile cluster.
|
||||
Sibling: `dashboard-home-realignment`. Mock items Wishlist /
|
||||
Trades / Market / Events / Binders are **not** product nav.
|
||||
- Wishlist as a feature (no table / API). Mock "Save to Wishlist"
|
||||
maps to **Add to List** or drops — IA decides.
|
||||
- A new identify / batch-OCR API, parallel Gemini calls, or a
|
||||
pile-in-one-frame detector. Batch Scan is multi-file sequential
|
||||
identify on the existing path.
|
||||
- Schema / new tables. Cart remains client session state.
|
||||
- Changing the homepage visual-diff baseline except as a
|
||||
side-effect of `/scanner` desktop chrome (scanner surfaces only).
|
||||
|
||||
### Product-vocab lock (from mock → Deck Hearth)
|
||||
|
||||
| Mock copy | Ship as |
|
||||
| --- | --- |
|
||||
| Add to Collection | `VOCAB.ADD_TO_MY_COLLECTION` |
|
||||
| Save to Wishlist | Add to List, or omit |
|
||||
| Binders (nav) | Lists — not this convoy |
|
||||
| Collection (nav) | My Collection — not this convoy |
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-ia-architect` — desktop flow vs mobile cart; inspector
|
||||
vs queue commit; Duplicates membership (`ownershipMap` vs
|
||||
session repeat); Batch Scan progress / failure; Tips content
|
||||
outline; device-picker empty/denied states.
|
||||
2. `role-ui-designer` — lock the md+ workstation against the
|
||||
attached mock using Liquid Glass tokens (`ui-ux-pro-max` is
|
||||
installed), including Tips popover, device `<select>`, Batch
|
||||
Scan progress, and the three-tab strip. Do **not** skip
|
||||
`ui-design`.
|
||||
3. `role-ux-reviewer` — inspect-then-add vs scan-all-then-checkout
|
||||
on desktop; Auto-detect off; Rescan; empty inspector; leave
|
||||
with an uncommitted queue; sequential batch cancel; duplicate
|
||||
tab actions (increment qty vs skip vs still add).
|
||||
4. `role-architect` — briefs. Likely: (1) page composition +
|
||||
Layout chrome split, (2) camera panel + `deviceId` picker,
|
||||
(3) result inspector, (4) history/queue/duplicates strip,
|
||||
(5) batch multi-file identify + Tips. `slice_dependencies`
|
||||
must mark what can run in parallel.
|
||||
5. `role-implementer` — per brief.
|
||||
6. Audit fan-out: reviewer + security-auditor + design-system-auditor
|
||||
+ a11y-auditor.
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] IA: desktop screen inventory + inspector-add vs cart-commit;
|
||||
Duplicates membership; Batch Scan + Tips content
|
||||
- [x] UI Designer: lock md+ workstation (tokens, not hex) from
|
||||
the attached mock; light + dark; Tips, device picker,
|
||||
batch progress, three-tab strip
|
||||
- [x] UX: Auto-detect off, Rescan, empty state, leave-with-queue,
|
||||
keyboard on desk controls, batch cancel, duplicate actions
|
||||
- [x] Architect: briefs + `slice_dependencies`; confirm Layout
|
||||
is `chrome="default"` on md+ only
|
||||
- [ ] Desktop composition in `pages/scanner.js` (do not hide
|
||||
sidebar / top bar at md+)
|
||||
- [ ] Camera as a framed panel; `deviceId` picker + Upload +
|
||||
Batch Scan + Auto-detect; hide mobile overlay chrome at md+
|
||||
- [ ] Live match inspector wired to the latest unprocessed
|
||||
identify (condition / foil already on the cart entry)
|
||||
- [ ] Bottom strip: Recent Scans + Scan Queue + Duplicates over
|
||||
`useScannerQueue` / `ownershipMap` / `scanner-session`
|
||||
- [ ] Scanner Tips popover/modal with convoy-authored copy
|
||||
- [ ] Sequential multi-file Batch Scan through
|
||||
`identifyFromGalleryFile` (cancellable, queue progress)
|
||||
- [ ] Tests for desktop composition (inspector + queue +
|
||||
duplicates + batch enqueue, no mobile sheet) and
|
||||
no-regression on checkout sheet at `max-width: 767px`
|
||||
- [ ] Visual-diff: desktop `/scanner` surface; refresh Linux
|
||||
baselines if the page is in the visual suite
|
||||
|
||||
## What exists today (conductor survey)
|
||||
|
||||
`/scanner` is one route, two compositions, one engine.
|
||||
|
||||
| Layer | Files | Today |
|
||||
| --- | --- | --- |
|
||||
| Page | `pages/scanner.js` | Auth gate; `Layout chrome="immersive"` on **all** viewports; camera column + `md:` 360px `ScannerReview` cart; mobile-only `ScannerCheckoutSheet` |
|
||||
| Layout | `components/Layout.js` | Immersive hides **mobile** nav + top bar (`max-md` only). Desktop sidebar + TopSearchBar already stay visible. |
|
||||
| Camera chrome | `components/scanner/ScannerCamera.js` | Full-bleed video, overlay top bar (back / title / gallery), bottom bar (flash / facing / status / Review N), scan peek, disambiguation. Same chrome on desktop. |
|
||||
| Cart | `lib/use-scanner-queue.js`, `lib/scanner-session.js` | Identify enqueues locally (`processed: false`). Commit via `commitSelectedToOwned` / `commitSelectedToCollection`. `sessionStorage` persist. `addSingleCardToOwned` already exists. |
|
||||
| Identify | `lib/use-scanner-identification.js`, `lib/use-camera-scanner.js` | Facing-mode swap only — **no** `deviceId` / `enumerateDevices`. Auto-detect is always on unless `verificationPausedRef` (checkout / list picker / disambiguation). |
|
||||
| Review | `components/scanner/ScannerReview.js` | Thin wrapper: desktop side panel titled "Cart" that mounts `ScannerCheckoutContent`. |
|
||||
|
||||
Mobile checkout decisions that still apply unless IA overturns them
|
||||
for desktop only: stay on camera after commit (D1), skip Setup
|
||||
(D3), My Collection + List only (D4), gallery in-scope (D5),
|
||||
cart in `sessionStorage` (D7).
|
||||
|
||||
## Conductor notes (build shape)
|
||||
|
||||
Likely file ownership for Architect to refine:
|
||||
|
||||
| Area | Files |
|
||||
| --- | --- |
|
||||
| Viewport split | `pages/scanner.js` — `chrome` default on md+, immersive on mobile; desktop grid vs mobile overlay |
|
||||
| Camera panel | `components/scanner/ScannerCamera.js` (desktop variant or `variant="workstation"`), `lib/use-camera-scanner.js` (`enumerateDevices` + `deviceId`) |
|
||||
| Inspector | new `components/scanner/ScannerResultPanel.js` — latest cart entry + condition/foil + add/rescan |
|
||||
| History strip | new `components/scanner/ScannerHistoryStrip.js` — Recent / Queue / Duplicates over `queue.scannedCards` + `ownershipMap` |
|
||||
| Batch Scan | `lib/use-scanner-identification.js` (`identifyFromGalleryFile` loop), queue progress UI |
|
||||
| Tips | new `components/scanner/ScannerTips.js` — `<Modal>` or popover, convoy copy |
|
||||
| Cart reuse | `lib/use-scanner-queue.js`, `lib/scanner-session.js`, `ScannerCheckoutSheet.js` (mobile only) |
|
||||
| Copy | `lib/collection-vocabulary.js` |
|
||||
|
||||
Do not rewrite identification. Prefer a desktop layout shell that
|
||||
**hides** mobile overlay chrome at `md+` rather than forking the
|
||||
camera hook.
|
||||
|
||||
## Decisions (post-conductor)
|
||||
|
||||
Locked 2026-08-15 from the parent session. IA / UX / Architect
|
||||
treat these as settled.
|
||||
|
||||
| # | Decision |
|
||||
| --- | --- |
|
||||
| C1 | **Batch Scan is in.** Multi-file sequential identify via the existing gallery path. No new batch API, no parallel Gemini, no new pile detector. |
|
||||
| C2 | **Duplicates tab is in.** Strip tab with a badge. Membership = already-owned (`ownershipMap`) and/or same-session name+set repeats. IA picks the exact rule and tab actions. |
|
||||
| C3 | **Scanner Tips is in.** Header control → glass popover/modal. Copy in this convoy. |
|
||||
| C4 | **Real webcam device picker is in.** `enumerateDevices` + `deviceId` on desktop. Mobile keeps facing-mode swap. |
|
||||
| C5 | **Inspector can commit this card now** *and* the queue strip remains for multi-add (same cart, two commit surfaces). Overturn only if IA finds a conflict. |
|
||||
|
||||
## Open questions (IA / product)
|
||||
|
||||
1. **Duplicates membership + actions.** Owned-in-collection only,
|
||||
session repeats only, or both? From the tab, can the user still
|
||||
add (increment qty), skip, or jump the inspector to that row?
|
||||
2. **Wishlist.** Out as a feature. Confirm "Save to Wishlist" →
|
||||
Add to List on the inspector, or omit the third action.
|
||||
3. **Auto-detect toggle.** User-facing pause of identification
|
||||
(extend `verificationPausedRef`), or just a status badge?
|
||||
4. **Batch Scan cancel / errors.** Mid-batch cancel: keep already-
|
||||
identified rows? Per-file failure: continue the rest and flag
|
||||
the row, or stop?
|
||||
5. **Tips content.** Four or five short tips (lighting, frame the
|
||||
card, foil glare, hold still, auto-detect). IA drafts; UI
|
||||
Designer locks the surface.
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
Planning is serial: IA → UI Designer → UX → Architect.
|
||||
|
||||
After architect: implementer fan-out only if briefs have
|
||||
`depends_on: []` and disjoint `files:`. Device picker
|
||||
(`use-camera-scanner.js`) and Tips (`ScannerTips.js`) are the
|
||||
best candidates to parallelize with the inspector if they do
|
||||
not both own `pages/scanner.js`. Page composition likely
|
||||
blocks the strip and Batch Scan wiring.
|
||||
|
||||
After PR draft: `/multitask` audit fan-out
|
||||
`role-reviewer + role-security-auditor + role-design-system-auditor + role-a11y-auditor`
|
||||
(group id: `audit-scanner-desktop-layout-<pr>`).
|
||||
|
||||
## IA
|
||||
|
||||
### Affected routes
|
||||
|
||||
- `/scanner` — **[modified]** Single route, two viewport compositions. Desktop (`md+`) switches to `Layout chrome="default"` (sidebar + TopSearchBar visible), framed camera workstation, live match inspector (right rail), and bottom history strip. Mobile (`max-md`) stays `chrome="immersive"` with checkout sheet — no regression.
|
||||
- `/login` — **[impacted]** Existing `returnUrl=/scanner` auth gate unchanged; desktop users land on the workstation after sign-in.
|
||||
- `/collections`, `/my-cards` — **[impacted]** Post-commit navigation targets only (Add to List picker, success flows). No route or nav IA changes in this convoy.
|
||||
|
||||
No new routes. No API route changes.
|
||||
|
||||
### User flow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["/scanner (auth)"] --> B{"md+?"}
|
||||
B -->|Yes| C["Workstation"]
|
||||
B -->|No| D["Immersive mobile"]
|
||||
C --> E["Scan / Upload / Batch"]
|
||||
E --> F["Match inspector"]
|
||||
F --> G["Add or queue"]
|
||||
C --> H["Strip tabs"]
|
||||
H --> F
|
||||
```
|
||||
|
||||
Desktop path: user opens `/scanner` with app chrome → scans via webcam, single Upload Image, or Batch Scan (sequential gallery identify) → latest match appears in the right-rail inspector → commits one card via inspector **or** batches via Scan Queue strip → Duplicates tab surfaces owned + session-repeat rows for review/increment. Mobile path unchanged: full-bleed camera → checkout sheet.
|
||||
|
||||
### Screen inventory
|
||||
|
||||
| Screen | Path | New/modified | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Scanner Desktop Workstation | `/scanner` | modified | `md+` grid: framed camera panel (device picker, Upload, Batch Scan, Auto-detect toggle, Tips), right-rail inspector, bottom strip. Replaces 360px cart side panel as primary right-hand surface. |
|
||||
| Scanner Mobile Immersive | `/scanner` | impacted (no regression) | `max-md`: `chrome="immersive"`, overlay camera chrome, `ScannerCheckoutSheet`. D1/D3/D4/D5/D7 decisions preserved. |
|
||||
| Live Match Inspector | `/scanner` | new (sub-surface) | Right rail on desktop. Shows latest unprocessed identify: thumbnail, name, set, rarity, collector #, condition, foil, confidence. Actions: `VOCAB.ADD_TO_MY_COLLECTION`, `VOCAB.ADD_TO_LIST`, Rescan. Single-card commit without opening checkout sheet. |
|
||||
| History / Queue Strip | `/scanner` | new (sub-surface) | Bottom strip on desktop. Tabs: **Recent Scans** (session history), **Scan Queue** (uncommitted cart, badge = unprocessed count), **Duplicates** (badge = duplicate row count). Row click focuses card in inspector. |
|
||||
| Scanner Tips | `/scanner` | new (sub-surface) | Header control → glass `<Modal>` or popover. Five convoy-authored tips (see Content deltas). No route change. |
|
||||
| List Picker | `/scanner` | impacted | Existing "Choose a List" `<Modal>`. Opened from inspector `VOCAB.ADD_TO_LIST` on desktop (and unchanged on mobile). |
|
||||
| Leave Scanner | `/scanner` | impacted | Existing leave-with-uncommitted-queue modal. Applies to both viewports when navigating away with queue items. |
|
||||
|
||||
### Content / data model deltas
|
||||
|
||||
**Copy (ship from `lib/collection-vocabulary.js`):**
|
||||
|
||||
- Primary add: `VOCAB.ADD_TO_MY_COLLECTION` ("Add to My Collection").
|
||||
- Secondary add: `VOCAB.ADD_TO_LIST` ("Add to List") — **not** "Save to Wishlist" (feature omitted).
|
||||
- Strip tab labels: "Recent Scans", "Scan Queue", "Duplicates".
|
||||
- Camera controls: "Upload Image", "Batch Scan", "Auto-detect" (toggle + status on/off), "Scanner Tips", "Rescan".
|
||||
- Device picker: "Camera" or "Webcam" `<select>` label; empty/denied fallback copy (UI Designer).
|
||||
|
||||
**Scanner Tips content (draft for UI Designer):**
|
||||
|
||||
1. Good lighting — avoid glare on foil cards.
|
||||
2. Fill the frame with one card; keep corners visible.
|
||||
3. Hold still until Auto-detect locks the match.
|
||||
4. Use Batch Scan for a pile of photos from your gallery.
|
||||
5. Switch webcam if the image is dark or mirrored.
|
||||
|
||||
**No schema changes.** Cart remains client `sessionStorage` via `lib/scanner-session.js`. Duplicates derive from existing `ownershipMap` (already in My Collection) and `mergeScannedCardEntry` (same-session name+set repeats) — no new tables or API fields.
|
||||
|
||||
**IA decisions (locked — formerly open questions):**
|
||||
|
||||
| Topic | Decision |
|
||||
| --- | --- |
|
||||
| Duplicates membership | **Both** sources: `ownershipMap` (already-owned) **and** same-session name+set repeats via `mergeScannedCardEntry`. Badge = count of rows in the Duplicates set. Row click focuses that card in the inspector. User can still add (increment qty) from inspector or queue. |
|
||||
| Wishlist | **Omit.** Inspector third action is `VOCAB.ADD_TO_LIST`, not wishlist. |
|
||||
| Auto-detect | **Real pause toggle** on desktop. Extends `verificationPausedRef` (user off = paused identify). Status badge reflects on/off. Mobile behavior unchanged unless UX specifies otherwise. |
|
||||
| Batch cancel / errors | Mid-batch **cancel keeps** already-identified rows. Per-file failure **continues** the rest and flags that row in Scan Queue — do not stop the batch. |
|
||||
| Inspector vs queue commit | **Both surfaces** (C5): inspector commits one card now; Scan Queue strip handles multi-add / bulk commit. Same cart, two commit paths. |
|
||||
| Webcam picker | Desktop only: `enumerateDevices` + `deviceId`. Mobile keeps facing-mode swap (C4). |
|
||||
|
||||
### Open IA questions
|
||||
|
||||
None — all five conductor questions resolved above.
|
||||
|
||||
## Design direction
|
||||
|
||||
Locked v1 against `image-1eeebe23-9983-4a96-a3e7-4e3cdfdceb5b.png`
|
||||
(dark + light side-by-side). **Incremental redesign** of an existing
|
||||
Liquid Glass surface — not a new palette. Generator run:
|
||||
`desktop trading card scanner workstation camera inspector queue
|
||||
glassmorphism` (`ui-ux-pro-max` v2.5.0).
|
||||
|
||||
### Summary
|
||||
|
||||
On `md+`, `/scanner` is a **desk workstation** inside normal app
|
||||
chrome (sidebar + TopSearchBar): a framed live-camera panel with
|
||||
ember corner brackets, a right-rail **live match inspector**, and a
|
||||
bottom **history / queue strip** — inspect one card, commit from the
|
||||
rail, or batch from the strip. Mobile stays immersive; this direction
|
||||
applies only at `md+`.
|
||||
|
||||
### Pattern + style
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Product type | Desktop trading card scanner workstation |
|
||||
| Landing / app pattern | Feature-Rich Showcase → **workstation grid** (camera + inspector + strip; not a marketing landing) |
|
||||
| UI style | **Liquid Glass** (existing Deck Hearth DS) — translucent panels, rim-light, ember accent rings |
|
||||
| Stack notes | nextjs · React 18 · Tailwind + CSS variables · `<Modal>` / `<GlassSurface>` / `<Button>` primitives |
|
||||
|
||||
**Generator vs repo (repo wins):**
|
||||
|
||||
| Generator | Locked override |
|
||||
| --- | --- |
|
||||
| Exaggerated Minimalism (oversized type, massive whitespace) | **Rejected** — match existing app density; page title `text-2xl` / `font-semibold`, subtitle `text-sm text-secondary` |
|
||||
| Palette `#1E293B` / `#2563EB` scan blue | **Rejected** — use `--accent-ember`, `--accent-flame`, `--accent-gold`, `--bg-*`, `--text-*` from `styles/globals.css` |
|
||||
| Inter typography | **Rejected** — keep system stack (`-apple-system, BlinkMacSystemFont, …`) |
|
||||
| Feature-Rich Showcase sections | **Adapted** — three functional zones (camera, inspector, strip) replace marketing feature cards |
|
||||
|
||||
### Layout authority (`md+` only)
|
||||
|
||||
Viewport split at `md` (768px). Below `md`, no changes (immersive +
|
||||
checkout sheet).
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ [Layout sidebar] │ TopSearchBar + profile │
|
||||
├──────────────────┼──────────────────────────────────────────────┤
|
||||
│ │ Card Scanner [Scanner Tips] │
|
||||
│ │ <subtitle> │
|
||||
│ ├──────────────────────────┬───────────────────┤
|
||||
│ │ ┌─ Auto-detect ON ─┐ │ Scan Result 98% │
|
||||
│ │ │ [live video] │ │ ┌────┐ metadata │
|
||||
│ │ │ ember brackets │ │ │thumb│ set/rarity │
|
||||
│ │ └──────────────────┘ │ condition ▾ foil │
|
||||
│ │ [Camera ▾][Upload][Batch] │ confidence bar │
|
||||
│ │ [Auto-detect]│ + Add to My Coll. │
|
||||
│ │ │ Rescan | Add List │
|
||||
│ ├──────────────────────────┴───────────────────┤
|
||||
│ │ Recent │ Queue (N) │ Dupes (N) Clear All│
|
||||
│ │ [chip][chip][chip]… │
|
||||
│ │ [ View All Scans ] │
|
||||
└──────────────────┴──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Zone | Width / placement | Surface recipe |
|
||||
| --- | --- | --- |
|
||||
| Page header | Full content width above grid | Flat on `--bg-primary`; Tips = `<Button variant="ghost">` + lightbulb icon |
|
||||
| Camera column | `flex-1` / `min-w-0`; ~60–65% | Viewport frame: `--glass-surface-low` + `--ember-rim-subtle` on outer frame; **ember corner brackets** on video (existing `ScannerCamera`) |
|
||||
| Desk control bar | Directly under viewport | `--glass-surface-mid` bar, `rounded-xl`, horizontal flex wrap at `md` |
|
||||
| Inspector rail | Fixed `w-[360px]` or `max-w-sm`; sticky top optional | `--glass-surface-low` panel, `--elevation-ambient`, `--rim-light-inner/outer` |
|
||||
| Bottom strip | Full content width below main grid | `--glass-surface-mid` container; tab row + chip scroller |
|
||||
|
||||
**Page copy (header):**
|
||||
|
||||
- Title: **Card Scanner**
|
||||
- Subtitle: *Identify cards with your webcam and add them to My
|
||||
Collection.*
|
||||
|
||||
### Colors
|
||||
|
||||
All values via CSS variables — **no hex in `.js`**.
|
||||
|
||||
| Role | Token | Usage on this surface |
|
||||
| --- | --- | --- |
|
||||
| Page background | `--bg-primary` | Workstation canvas behind glass panels |
|
||||
| Panel fill | `--glass-surface-{low,mid,high}` | Camera frame (low), control bar + strip (mid), popovers (high) |
|
||||
| Primary text | `--text-primary` | Titles, card names, tab labels |
|
||||
| Secondary text | `--text-secondary` | Subtitle, set/rarity, timestamps |
|
||||
| CTA / primary action | `--accent-ember` | **Add to My Collection** button; active tab underline; selected chip border |
|
||||
| Accent highlight | `--accent-flame`, `--accent-gold` | Confidence bar fill; match badge when ≥90% |
|
||||
| Interactive rim | `--ember-rim-subtle` / `--ember-rim-pronounced` | Camera frame rest; primary button hover/focus |
|
||||
| Success / match | `--accent-gold` or existing success token | Auto-detect ON dot; high-confidence pill |
|
||||
| Error / batch fail | `--accent-ember` at reduced opacity or danger variant | Failed queue row indicator |
|
||||
| Border | `--border` | Control bar dividers, chip separators |
|
||||
|
||||
Light and dark both use the same token names; theme context switches
|
||||
values. Mock's cool-navy dark is approximated by existing
|
||||
`--bg-primary-dark` — do not introduce a new dark base.
|
||||
|
||||
### Typography
|
||||
|
||||
| Role | Font | Notes |
|
||||
| --- | --- | --- |
|
||||
| Page title | System stack, `text-2xl font-semibold` | "Card Scanner" |
|
||||
| Subtitle | System stack, `text-sm`, `--text-secondary` | One line under title |
|
||||
| Section labels | `text-sm font-medium uppercase tracking-wide` | "Scan Result", strip tab labels |
|
||||
| Card name (inspector) | `text-lg font-semibold` | Primary identify headline |
|
||||
| Metadata | `text-sm`, `--text-secondary` | Set · rarity · collector # |
|
||||
| Chip / queue row | `text-sm` name, `text-xs` meta | Timestamps right-aligned |
|
||||
|
||||
### Camera viewport + desk controls
|
||||
|
||||
**Inside frame (overlay on video):**
|
||||
|
||||
- **Auto-detect badge** — top-left pill: green status dot +
|
||||
`Auto-detect ON` / `Auto-detect OFF` (reflects pause toggle).
|
||||
- **Ember corner brackets** — four L-shaped corners on the card
|
||||
alignment region (ship existing `ScannerCamera` bracket styling).
|
||||
- Optional alignment guide (mock dotted vertical line) — **omit in
|
||||
v1** unless implementer brief explicitly includes it; brackets +
|
||||
badge are required.
|
||||
|
||||
**Desk control bar (below frame, left → right):**
|
||||
|
||||
| Control | Component | Notes |
|
||||
| --- | --- | --- |
|
||||
| Camera | `<select>` or styled native picker, label **Camera** | `enumerateDevices` video inputs; desktop only |
|
||||
| Upload Image | `<Button variant="secondary">` + upload icon | Single-file; existing gallery path |
|
||||
| Batch Scan | `<Button variant="secondary">` + stack icon | Multi-file picker; triggers sequential identify |
|
||||
| Auto-detect | Toggle switch + label **Auto-detect** | Right-aligned on wide screens; extends `verificationPausedRef` |
|
||||
|
||||
**Webcam device picker — fallback copy (locked):**
|
||||
|
||||
| State | Message | Action hint |
|
||||
| --- | --- | --- |
|
||||
| Loading | Detecting cameras… | Disable `<select>` until resolved |
|
||||
| Empty list | No camera found | Connect a webcam or use **Upload Image**. |
|
||||
| Permission denied | Camera access blocked | Allow camera in your browser settings, or use **Upload Image**. |
|
||||
| Error (enumerate failed) | Couldn't list cameras | Use **Upload Image** or reload the page. |
|
||||
|
||||
When empty or denied, render the message inline below the disabled
|
||||
`<select>` (`text-sm`, `--text-secondary`); do not use a blocking
|
||||
modal for device errors.
|
||||
|
||||
### Live match inspector (right rail)
|
||||
|
||||
Header row: **Scan Result** + confidence pill (e.g. `98% Match`).
|
||||
|
||||
**Empty state** (no identify yet): centered illustration area +
|
||||
*"Point your camera at a card or upload an image to see a match."*
|
||||
|
||||
**Populated state** (latest unprocessed cart entry):
|
||||
|
||||
- Thumbnail + name, set, rarity icon, collector number
|
||||
- **Condition** — `<select>` (existing condition options)
|
||||
- **Foil** — toggle switch
|
||||
- Confidence — percentage + horizontal bar + caption (*Excellent match.*
|
||||
/ *Good match.* / *Low confidence — verify before adding.*)
|
||||
- Actions (top → bottom priority):
|
||||
1. **Primary:** `VOCAB.ADD_TO_MY_COLLECTION` (`<Button variant="primary">`, `+` icon optional)
|
||||
2. **Secondary row:** **Rescan** (ghost) · `VOCAB.ADD_TO_LIST` (ghost)
|
||||
- **Never** ship "Add to Collection", "Save to Wishlist", or "Mark
|
||||
Owned".
|
||||
|
||||
### Bottom history / queue strip
|
||||
|
||||
**Tab row:** **Recent Scans** · **Scan Queue** `(N)` · **Duplicates**
|
||||
`(N)` — badge = unprocessed count / duplicate row count per IA.
|
||||
**Clear All** — text link, right-aligned (`text-sm`, destructive on
|
||||
hover).
|
||||
|
||||
**Card chips** (horizontal scroll, `overflow-x-auto`):
|
||||
|
||||
- Thumbnail, name, set · rarity · condition snippet
|
||||
- Status: confidence % + relative time (*Just now*, *2 min ago*)
|
||||
- Active / focused row: `--ember-rim-pronounced` border (matches mock
|
||||
ember outline on leftmost chip)
|
||||
- **No `backdrop-filter` on individual chips** — solid
|
||||
`--bg-secondary` per per-card grid performance budget
|
||||
(`docs/DESIGN_TOKENS.md` § Per-card grid performance budget)
|
||||
|
||||
**View All Scans** — full-width ghost button at strip bottom; opens
|
||||
expanded queue view or scrolls strip — Architect brief decides;
|
||||
visual = translucent bar button from mock.
|
||||
|
||||
**Row click** — focuses that card in the inspector (IA-locked).
|
||||
|
||||
### Batch Scan progress (Scan Queue tab)
|
||||
|
||||
When batch is running, **Scan Queue** tab auto-focuses (or shows an
|
||||
inline banner):
|
||||
|
||||
- Progress line: **Scanning 3 of 12…** with determinate progress bar
|
||||
(`--accent-ember` fill)
|
||||
- **Cancel** — ghost button; **keeps already-identified rows** (IA)
|
||||
- Per-file failure — enqueue row with error flag, label **Identify
|
||||
failed**, `text-sm` reason if available; batch **continues** remaining
|
||||
files
|
||||
- On complete — banner dismisses; failed rows stay in queue with
|
||||
visual error state (ember left border or warning icon)
|
||||
|
||||
### Scanner Tips (surface locked)
|
||||
|
||||
**`<Modal>`** — five tips exceed popover length; use
|
||||
`components/ui/Modal` + modal panel recipe (`--glass-surface-low`,
|
||||
`--modal-scrim`). Trigger: header **Scanner Tips** button (lightbulb
|
||||
icon + label).
|
||||
|
||||
| # | Tip |
|
||||
| --- | --- |
|
||||
| 1 | **Good lighting** — avoid glare on foil cards. |
|
||||
| 2 | **Fill the frame** with one card; keep corners visible. |
|
||||
| 3 | **Hold still** until Auto-detect locks the match. |
|
||||
| 4 | **Use Batch Scan** for a pile of photos from your gallery. |
|
||||
| 5 | **Switch camera** if the image is dark or mirrored. |
|
||||
|
||||
Modal title: **Scanner Tips**. Dismiss via close control + Esc +
|
||||
scrim click (standard `<Modal>` behavior).
|
||||
|
||||
### Effects + motion
|
||||
|
||||
- Panel transitions: **150–200ms** ease on hover/focus for buttons and
|
||||
chips (`docs/MOTION_SYSTEM.md` if defined; else `transition-colors
|
||||
duration-200`)
|
||||
- Auto-detect badge dot: subtle pulse when ON; **respect
|
||||
`prefers-reduced-motion`** (static dot when reduced)
|
||||
- Confidence bar: width transition 300ms on value change; no animation
|
||||
when reduced
|
||||
- Tab switch: instant content swap (no slide); optional 150ms fade on
|
||||
chip row refresh
|
||||
- Hover: `cursor-pointer` on all clickable chips, tabs, buttons;
|
||||
`--ember-rim-subtle` → `--ember-rim-pronounced` on primary hover
|
||||
|
||||
### Anti-patterns (do not ship)
|
||||
|
||||
- Full-bleed camera overlay on desktop (mobile-only chrome)
|
||||
- Hex colors in `.js` / inline styles
|
||||
- Generator slate/blue palette or Inter font import
|
||||
- `backdrop-filter` on per-card strip chips or thumbnail tiles
|
||||
- "Add to Collection", "Save to Wishlist", "Mark Owned", "All My
|
||||
Cards" in UI copy
|
||||
- Custom modal scrim (must use `<Modal>` primitive)
|
||||
- Popover for five tips (use Modal)
|
||||
- Parallel batch identify UI implying concurrent Gemini calls
|
||||
- Device `<select>` on mobile (facing-mode toggle stays)
|
||||
|
||||
### Pre-delivery checklist
|
||||
|
||||
- [ ] No emojis as icons (SVG: Lucide / Heroicons)
|
||||
- [ ] `cursor-pointer` on clickable elements
|
||||
- [ ] Hover/focus transitions 150–300ms
|
||||
- [ ] Text contrast ≥ 4.5:1 on glass-over-flat surfaces
|
||||
- [ ] Keyboard focus visible (`--ember-rim-pronounced` focus ring)
|
||||
- [ ] `prefers-reduced-motion` respected (badge pulse, bar animate)
|
||||
- [ ] Responsive: mobile immersive unchanged; workstation at 768 /
|
||||
1024 / 1440
|
||||
- [ ] Light + dark verified against mock reference
|
||||
- [ ] Copy from `lib/collection-vocabulary.js` for add actions
|
||||
- [ ] Visual-diff: desktop `/scanner` if in suite
|
||||
|
||||
### Conflict rule
|
||||
|
||||
**Repo design tokens win** when they disagree with generator output.
|
||||
This lock intentionally overrides `ui-ux-pro-max` palette and typography
|
||||
only. Layout proportions follow the attached mock; nav items in the
|
||||
mock that are not product routes (Wishlist, Trades, etc.) are **not**
|
||||
in scope — existing Layout sidebar IA stands.
|
||||
|
||||
## UX
|
||||
|
||||
### 1. Existing components to reuse
|
||||
|
||||
| Component | Path | Use on desktop workstation |
|
||||
| --- | --- | --- |
|
||||
| `<Modal>` | `components/ui/Modal.js` | Leave-with-queue, List picker, **Scanner Tips** (five tips — no custom scrim) |
|
||||
| `<Button>` | `components/ui/Button.js` | Upload Image, Batch Scan, Auto-detect toggle label area, inspector primary/ghost actions, batch Cancel, View All Scans |
|
||||
| `<GlassSurface>` | `components/ui/GlassSurface.js` | Camera frame, desk control bar, inspector rail, strip container, strip chips (solid `--bg-secondary` fill inside — no per-chip blur) |
|
||||
| `<Input>` | `components/ui/Input.js` | Not required v1; strip search deferred to Architect brief |
|
||||
| `ScannerCamera` | `components/scanner/ScannerCamera.js` | Framed viewport, ember brackets, overlay Auto-detect badge; hide mobile overlay chrome at `md+` via variant prop |
|
||||
| `ScannerDisambiguation` | `components/scanner/ScannerDisambiguation.js` | Unchanged multi-match picker; pauses identify via existing `verificationPausedRef` wiring |
|
||||
| `ScannerToast` | `components/scanner/ScannerToast.js` | Post-commit confirmation, batch complete summary, identify errors |
|
||||
| `ScannerCheckoutSheet` | `components/scanner/ScannerCheckoutSheet.js` | **Mobile only** (`max-md`) — do not mount at `md+` |
|
||||
| `ScannerCountPill` | `components/scanner/ScannerCountPill.js` | **Mobile only** — desktop uses strip Queue badge instead |
|
||||
| `ReviewCardItem` | `components/scanner/ReviewCardItem.js` | **Pattern donor** for condition `<select>`, foil toggle, confidence ring/color helpers, increment/decrement — lift constants (`CONDITION_OPTIONS`, `confidencePercent`, `confidenceRingColor`) into shared export or duplicate minimally in `ScannerResultPanel` |
|
||||
| Leave modal + List picker | `pages/scanner.js` | Reuse verbatim markup and handlers; extend leave trigger to desktop back/nav paths |
|
||||
|
||||
**New surfaces** (`ScannerResultPanel`, `ScannerHistoryStrip`, `ScannerTips`) compose primitives only — no new modal shell, no hex in `.js`.
|
||||
|
||||
### 2. Design direction alignment
|
||||
|
||||
- **Liquid Glass tokens:** All panels use `--glass-surface-{low,mid,high}`, `--ember-rim-{subtle,pronounced}`, `--elevation-ambient` per Design direction layout authority table. Inspector rail = `GlassSurface` tint `low`; desk bar + strip = `mid`.
|
||||
- **Ember accent:** Primary add, active tab underline, focused chip border, Auto-detect ON dot use `--accent-ember` / `--accent-flame` — not generator slate/blue.
|
||||
- **Copy lock:** Inspector and strip actions import `VOCAB.ADD_TO_MY_COLLECTION` and `VOCAB.ADD_TO_LIST` from `lib/collection-vocabulary.js`. Wishlist omitted (IA-locked).
|
||||
- **Performance budget:** Strip chips and inspector thumbnail tiles use solid `--bg-secondary` — **no `backdrop-filter` on per-card elements** (Design direction + `docs/DESIGN_TOKENS.md`).
|
||||
- **Tips surface:** `<Modal size="md">` with glass panel recipe — matches Design direction "Popover for five tips" rejection.
|
||||
- **Motion:** 150–200ms color/rim transitions; badge pulse and confidence bar width animate only when `prefers-reduced-motion: no-preference` (see §7 interaction patterns).
|
||||
|
||||
### 3. Existing patterns to follow
|
||||
|
||||
- **Viewport split:** `pages/scanner.js` already gates mobile checkout with `md:hidden` / `hidden md:flex` — extend to `Layout chrome="default"` at `md+` only; keep `chrome="immersive"` below `md`.
|
||||
- **Pause identify:** `verificationPausedRef` in `pages/scanner.js` (lines 59–63) — extend desktop Auto-detect OFF to set ref; keep existing pauses for list picker + disambiguation + mobile checkout.
|
||||
- **Single-card commit:** `queue.addSingleCardToOwned(card)` in `lib/use-scanner-queue.js` — inspector primary action; same API path as mobile bulk commit.
|
||||
- **Leave with queue:** Existing `<Modal title="Leave scanner?">` + `clearScannerCartStorage()` — trigger from desktop back, sidebar nav away, and `router.back()` when `unprocessedCount > 0`.
|
||||
- **List commit:** Existing List picker `<Modal>` + `handleListPick` — inspector `VOCAB.ADD_TO_LIST` opens same modal scoped to **focused inspector card** (single selection), not bulk strip selection.
|
||||
- **Error alerts:** Match `ScannerCheckoutContent` / `pages/scanner.js` list picker — `role="alert"` div with `color-mix(in srgb, var(--color-error) …)` for commit and batch failures.
|
||||
- **Confidence UX:** Reuse `ReviewCardItem` thresholds: `<70%` ember warning, `≥90%` gold/high — caption text from Design direction (*Excellent match.* / *Good match.* / *Low confidence — verify before adding.*).
|
||||
- **Device picker fallbacks:** Inline `text-sm` `--text-secondary` messages below disabled `<select>` per Design direction table — not a blocking modal.
|
||||
- **Focus rings:** `Button` / `ChromeIconButton` pattern — `focus-visible:ring-2` + `'--tw-ring-color': 'var(--accent-ember)'` (`components/scanner/ScannerCamera.js`).
|
||||
|
||||
### 4. A11y constraints
|
||||
|
||||
Hand to `role-a11y-auditor`:
|
||||
|
||||
- **1.4.3 Contrast (Minimum):** All `--text-primary` / `--text-secondary` on `--glass-surface-*` over `--bg-primary` must meet **4.5:1** for body text, **3:1** for large/bold card name (`text-lg font-semibold`). Confidence bar track vs fill must meet **3:1** non-text contrast.
|
||||
- **1.4.10 Reflow:** At 768px width with 200% zoom, workstation grid stacks camera above inspector; strip tabs remain horizontally scrollable without two-dimensional scroll traps.
|
||||
- **1.4.11 Focus Not Obscured (Minimum):** Sticky inspector rail and batch progress banner must not fully hide focused desk controls or strip chips.
|
||||
- **2.1.1 Keyboard:** Every action reachable without pointer: desk controls, strip tabs (tablist), chip rows, inspector add/rescan, batch Cancel, Tips open/close.
|
||||
- **2.4.3 Focus Order:** DOM order = visual order: page header (Tips) → camera frame → desk bar (Camera → Upload → Batch → Auto-detect) → inspector → strip tabs → chip scroller → View All.
|
||||
- **2.4.7 Focus Visible:** Ember focus ring on all interactive elements; native `<select>` gets `focus-visible:ring-2` wrapper if browser default ring is suppressed.
|
||||
- **2.4.11 Focus Not Obscured:** Modal open (Tips, leave, list picker) uses existing `useFocusTrap` — no focus escape to camera video underneath.
|
||||
- **4.1.2 Name, Role, Value:**
|
||||
- Auto-detect toggle: `role="switch"`, `aria-checked={!verificationPausedRef}`, visible label **Auto-detect** associated via `htmlFor` / `aria-labelledby`.
|
||||
- Strip tabs: `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected`, `aria-controls`, badge counts in `aria-label` (e.g. `Scan Queue, 3 unprocessed cards`).
|
||||
- Camera `<select>`: `<label>` **Camera** + `aria-describedby` pointing to empty/denied fallback text when present.
|
||||
- Inspector condition `<select>`: accessible name includes card name (`Condition for {card.name}`).
|
||||
- Foil toggle: `role="switch"`, `aria-checked`, label **Foil**.
|
||||
- **4.1.3 Status Messages:** Auto-detect ON/OFF badge exposes `aria-live="polite"` region; batch progress (`Scanning 3 of 12…`) uses `aria-live="polite"`; commit success via `ScannerToast` with `role="status"`.
|
||||
- **3.3.1 Error Identification:** Batch per-file failures show **Identify failed** + reason text on the queue row; commit errors in inspector use `role="alert"` (same pattern as checkout footer).
|
||||
- **2.5.3 Label in Name:** Visible button text must appear in accessible name — e.g. **Upload Image**, not icon-only without `aria-label`.
|
||||
- **Live region discipline:** Only one polite live region for batch progress; avoid duplicate announcements on tab auto-focus during batch.
|
||||
|
||||
### 5. Interaction patterns
|
||||
|
||||
#### Locked decisions (opinionated — one pattern each)
|
||||
|
||||
| Topic | Decision | Nielsen / rationale |
|
||||
| --- | --- | --- |
|
||||
| **Empty inspector** | Centered muted camera/scan illustration + single line: *"Point your camera at a card or upload an image to see a match."* No duplicate Upload/Batch CTAs in the rail (controls live in desk bar). | **H8** aesthetic minimalism; **H6** recognition — one place for actions. |
|
||||
| **Leave with uncommitted queue** | Keep existing `<Modal title="Leave scanner?">` — **Keep scanning** (secondary) / **Leave** (danger). Same copy and `clearScannerCartStorage()` behavior on desktop nav-away. | **H3** user control; **H5** error prevention. |
|
||||
| **Inspector add success** | **Advance inspector to next unprocessed queue entry** (or empty state if queue clear). Show `ScannerToast` (*Added to My Collection*). Committed card appears in **Recent Scans** with processed styling. Do **not** linger on committed card in inspector. | **H2** real-world scan rhythm; **H1** toast + strip update confirm status without blocking next decision. |
|
||||
| **Auto-detect OFF** | Real pause via `verificationPausedRef` — no identify/OCR while OFF. Badge reads **Auto-detect OFF**; dot static gray. Toggle is independent of mobile checkout pause logic. | **H3** user control; **H1** badge reflects system state. |
|
||||
| **Rescan** | Clears focus card's identify metadata and re-queues same physical capture path (webcam frame or re-read gallery source if batch row) — card stays in queue unprocessed. | **H3** undo/recover from bad match. |
|
||||
| **Duplicate row click** | Focuses that card in inspector (scroll chip into view, `--ember-rim-pronounced` on active chip). **Add still allowed** — increment qty via inspector primary or existing queue increment if duplicate already unprocessed. No separate "Skip" action in v1. | **H6** recognition over recall; **H4** consistency with Queue tab. |
|
||||
| **Batch cancel** | Ghost **Cancel** in Scan Queue tab progress banner. Cancels remaining files; **keeps** already-identified rows (IA-locked). Banner dismisses; toast *Batch scan stopped* (info). | **H3** user control; **H9** recover from long batch. |
|
||||
| **Batch per-file failure** | Row stays in Scan Queue with ember left border + **Identify failed** label; batch **continues**. Row click focuses inspector for manual Rescan or remove. | **H9** graceful recovery; **H1** visible error on row. |
|
||||
| **Strip row click (all tabs)** | Sets inspector focus to that card; does not auto-commit. Recent / Queue / Duplicates share one focus model. | **H4** consistency. |
|
||||
| **Clear All** | Destructive text link — confirm via existing pattern or inline `window.confirm` only if Architect brief adds it; default: immediate clear with undo **not** required v1 (queue is session-scoped). Architect to confirm in brief. | **H5** prevent accidental loss — if no confirm, disable when batch running. |
|
||||
|
||||
#### Required
|
||||
|
||||
- **Loading — identify in flight (H1):** Inspector shows skeleton/thumbnail placeholder + *Identifying…* on desk bar Upload/Batch busy states disable repeat picks.
|
||||
- **Loading — commit (H1):** Inspector primary `<Button loading>` during `addSingleCardToOwned`; disable Rescan and secondary actions while processing.
|
||||
- **Empty strip tabs (H9):** Recent: *No scans yet this session.* Queue: *Scan queue is empty — matches appear here before you add them.* Duplicates: *No duplicates detected.*
|
||||
- **Auto-detect ON feedback (H1):** Green pulsing dot in frame badge (respect reduced motion); optional success chime already in `ScannerCamera` — desktop may keep muted default.
|
||||
- **Batch running (H1):** Auto-select **Scan Queue** tab; determinate progress bar; Cancel visible throughout.
|
||||
- **Focus management (H3):** Opening Tips/list/leave modals traps focus; closing returns focus to trigger button.
|
||||
- **Hover/focus (H4):** Chips and tabs: `--ember-rim-subtle` → `--ember-rim-pronounced` on hover/focus; `cursor-pointer` on all click targets.
|
||||
|
||||
#### Nice-to-have
|
||||
|
||||
- **Optimistic UI:** Inspector advance on commit can happen after API success only (no optimistic skip) — queue hook already marks `processed` post-success.
|
||||
- **Keyboard shortcut:** `A` to trigger inspector **Add to My Collection** when inspector populated and not processing — defer unless Architect brief adds; not v1 blocker.
|
||||
- **View All Scans:** Expanded modal or full-width strip — Architect decides; v1 may scroll chip row only.
|
||||
|
||||
### 6. Anti-patterns to avoid
|
||||
|
||||
- **Duplicate CTAs in empty inspector** — Upload/Batch already in desk bar (**H8** minimalist design).
|
||||
- **Custom modal scrim for Tips or device errors** — must use `<Modal>` or inline text only (**H4** consistency).
|
||||
- **Device `<select>` on mobile** — facing-mode swap stays (**H4**).
|
||||
- **Popover for five Scanner Tips** — too long; Modal only (**H8**).
|
||||
- **Linger on committed card in inspector after add** — blocks scan rhythm (**H2**).
|
||||
- **Stop entire batch on one file failure** — IA forbids (**H9**).
|
||||
- **Discard identified rows on batch cancel** — IA forbids (**H3**).
|
||||
- **"Save to Wishlist" / "Mark Owned" / "Add to Collection"** copy — CI forbidden strings (**H4**).
|
||||
- **`backdrop-filter` on strip chips or inspector thumbnail** — GPU budget violation.
|
||||
- **Full-bleed camera overlay on desktop** — mobile-only chrome (**H2**).
|
||||
- **Parallel batch progress implying concurrent API calls** — misleading (**H1** honest status).
|
||||
- **Icon-only desk controls without `aria-label`** — fails **2.5.3** / **4.1.2**.
|
||||
- **Auto-commit on strip row click** — user loses inspect step (**H3** user control).
|
||||
- **Slide animation on tab switch** — Design direction specifies instant swap; fade optional ≤150ms only.
|
||||
|
||||
### 7. Mobile / responsive notes
|
||||
|
||||
**Below `md` (767px) — zero regression:**
|
||||
|
||||
- Keep `Layout chrome="immersive"`, `ScannerCamera` overlay chrome (back, gallery, flash, facing, Review N pill), `ScannerCheckoutSheet`, `ScannerCountPill`, scan peek, disambiguation sheet behavior unchanged.
|
||||
- Do not render desktop workstation grid, inspector rail, history strip, device `<select>`, Batch Scan desk control, or Tips header button on mobile unless Tips is also added to mobile overlay (out of scope — **Tips = desktop header only v1**).
|
||||
- `verificationPausedRef` mobile checkout pause unchanged (`isCheckoutOpen && max-width 767px`).
|
||||
|
||||
**At `md+` (768px+):**
|
||||
|
||||
- `Layout chrome="default"` — sidebar + `TopSearchBar` visible.
|
||||
- Workstation grid: camera column `flex-1 min-w-0` (~60–65%) + inspector `w-[360px] max-w-sm` + full-width bottom strip.
|
||||
- Hide mobile-only elements: checkout sheet, Review N pill, overlay top/bottom camera bars, facing-mode toggle (replace with Camera `<select>`).
|
||||
- Desk control bar wraps at `md`; Auto-detect toggle right-aligned at `lg+`.
|
||||
- Strip chip scroller: `overflow-x-auto`, `-webkit-overflow-scrolling: touch` for trackpad/touch on hybrid devices; min chip height **44px** touch target.
|
||||
- **`prefers-reduced-motion`:** Disable Auto-detect badge pulse, confidence bar width transition, optional chip-row fade — use `@media (prefers-reduced-motion: reduce)` instant state swaps; keep color/rim hover transitions ≤150ms or disable per `docs/MOTION_SYSTEM.md` if defined.
|
||||
- **Breakpoints to verify:** 768 / 1024 / 1440 — inspector sticky top optional; strip never collapses tabs into mystery meat menu v1.
|
||||
- **Visual-diff:** Desktop `/scanner` only; mobile baseline must not change.
|
||||
|
||||
## Architecture
|
||||
|
||||
### File plan
|
||||
|
||||
| File | Action | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `lib/use-camera-scanner.js` | modified | `enumerateDevices`, `deviceId` selection, picker status, sessionStorage persist |
|
||||
| `test/lib/use-camera-scanner.test.js` | new | Mock `mediaDevices` — device list, constraint switch, persist |
|
||||
| `components/scanner/ScannerTips.js` | new | Header trigger + five-tip `<Modal>` |
|
||||
| `test/components/ScannerTips.test.js` | new | Open/close, copy lock |
|
||||
| `components/scanner/ScannerResultPanel.js` | new | Right-rail live match inspector |
|
||||
| `test/components/ScannerResultPanel.test.js` | new | Empty/populated, add loading, vocab |
|
||||
| `components/scanner/ScannerHistoryStrip.js` | new | Recent / Queue / Duplicates strip + `getDuplicateCards` |
|
||||
| `test/components/ScannerHistoryStrip.test.js` | new | Tabs, duplicates helper, batch banner |
|
||||
| `lib/scanner-batch-identify.js` | new | Sequential `runSequentialGalleryIdentify` |
|
||||
| `test/lib/scanner-batch-identify.test.js` | new | Progress, cancel, error continuation |
|
||||
| `pages/scanner.js` | modified | md+ workstation grid, focus state, pause composite, chrome split |
|
||||
| `components/scanner/ScannerCamera.js` | modified | `workstation` variant — framed viewport, hide mobile overlay at md+ |
|
||||
| `lib/use-scanner-identification.js` | modified | Remove redundant `verificationPausedRef` overwrite effect |
|
||||
| `lib/use-scanner-queue.js` | modified | Boolean return from `addSingleCardToOwned` / `addSingleCardToCollection` |
|
||||
| `test/pages/scanner.test.js` | new | Mobile checkout regression + desktop composition smoke |
|
||||
| `test/components/ScannerCamera.test.js` | new | Workstation variant hides overlay chrome |
|
||||
|
||||
**Not touched:** `components/Layout.js` (immersive already equals default at md+),
|
||||
`lib/scanner-card-identify.js`, `pages/api/scan/identify.js`, `ScannerCheckoutSheet.js`
|
||||
(mobile only), nav IA (`dashboard-home-realignment`).
|
||||
|
||||
### API surface
|
||||
|
||||
No new or modified API routes. Client cart remains `sessionStorage` via
|
||||
`lib/scanner-session.js`. All commits reuse existing `scanner-route-api.js` helpers
|
||||
(`addScannedCardToOwned`, `addScannedCardToCollection`).
|
||||
|
||||
### Schema diff
|
||||
|
||||
None.
|
||||
|
||||
### Test plan
|
||||
|
||||
| Area | File | What to lock |
|
||||
| --- | --- | --- |
|
||||
| Device picker hook | `test/lib/use-camera-scanner.test.js` | `deviceId` constraints, enumerate, persist, status messages |
|
||||
| Batch helper | `test/lib/scanner-batch-identify.test.js` | Sequential order, cancel mid-batch, error continues |
|
||||
| Tips modal | `test/components/ScannerTips.test.js` | Five tips, Modal primitive |
|
||||
| Inspector | `test/components/ScannerResultPanel.test.js` | Empty state (no duplicate CTAs), `VOCAB` labels |
|
||||
| History strip | `test/components/ScannerHistoryStrip.test.js` | `getDuplicateCards`, tab badges, batch banner |
|
||||
| Camera variant | `test/components/ScannerCamera.test.js` | Overlay hidden for `workstation` at md+ |
|
||||
| Page orchestration | `test/pages/scanner.test.js` | Checkout sheet at max-md; workstation surfaces at md+ |
|
||||
| Mobile regression | `test/components/ScannerCheckoutSheet.test.js` | Existing suite stays green — do not weaken |
|
||||
| Layout chrome | `test/components/Layout.test.js` | Existing immersive tests — no change expected |
|
||||
|
||||
**Visual-diff:** `tests/visual/` contains only `homepage.spec.ts` / `home.png` —
|
||||
no `/scanner` baseline update required for this convoy.
|
||||
|
||||
### Risk list
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| `verificationPausedRef` race between page and `useScannerIdentification` | Brief 6 deletes identification hook's direct ref assignment; page owns composite pause including `isAutoDetectPaused` |
|
||||
| `addSingleCardToOwned` lacks success signal today | Brief 6 adds boolean return in `use-scanner-queue.js` |
|
||||
| `chrome="immersive"` on all viewports today | Boot finding: Layout already shows sidebar at md+; page uses explicit `default` vs `immersive` via `matchMedia` for clarity |
|
||||
| Batch identify failures invisible in queue | Page enqueues `identifyFailed` rows; strip shows ember border + label |
|
||||
| Rescan without stored capture | v1: re-identify via `scanImageUrl` fetch; else toast to rescan from camera |
|
||||
| Desktop/mobile class split regressions | Tests mock `matchMedia`; mobile paths keep `md:hidden` gates |
|
||||
| Forbidden copy in new surfaces | Import `VOCAB` from `collection-vocabulary.js`; CI `forbidden-stale-strings` |
|
||||
| Brief 6 LOC >400 | Accepted — single serializer for `pages/scanner.js`; components split across Briefs 2–4 |
|
||||
| `getDuplicateCards` over-counts | Helper uses ownershipMap + session name/set + quantity>1; tune in strip tests |
|
||||
|
||||
### Decomposition
|
||||
|
||||
| Brief # | Title | Files | Depends on | Est. PR size |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Camera device picker hook | `use-camera-scanner.js`, test | — | S (~180 LOC) |
|
||||
| 2 | Scanner Tips modal | `ScannerTips.js`, test | — | S (~100 LOC) |
|
||||
| 3 | Live match inspector | `ScannerResultPanel.js`, test | — | M (~280 LOC) |
|
||||
| 4 | History / queue strip | `ScannerHistoryStrip.js`, test | — | M (~300 LOC) |
|
||||
| 5 | Sequential batch helper | `scanner-batch-identify.js`, test | — | S (~120 LOC) |
|
||||
| 6 | Page workstation wiring | `scanner.js`, `ScannerCamera.js`, identification + queue hooks, tests | 1, 2, 3, 4, 5 | L (~450 LOC) |
|
||||
|
||||
**Estimated PRs:** 6 (Briefs 1–5 parallelizable; Brief 6 after merge or rebase).
|
||||
|
||||
### Slice dependencies (multitask-ready)
|
||||
|
||||
```yaml
|
||||
slice_dependencies:
|
||||
- brief: 1
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/use-camera-scanner.js
|
||||
- test/lib/use-camera-scanner.test.js
|
||||
- brief: 2
|
||||
depends_on: []
|
||||
files:
|
||||
- components/scanner/ScannerTips.js
|
||||
- test/components/ScannerTips.test.js
|
||||
- brief: 3
|
||||
depends_on: []
|
||||
files:
|
||||
- components/scanner/ScannerResultPanel.js
|
||||
- test/components/ScannerResultPanel.test.js
|
||||
- brief: 4
|
||||
depends_on: []
|
||||
files:
|
||||
- components/scanner/ScannerHistoryStrip.js
|
||||
- test/components/ScannerHistoryStrip.test.js
|
||||
- brief: 5
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/scanner-batch-identify.js
|
||||
- test/lib/scanner-batch-identify.test.js
|
||||
- brief: 6
|
||||
depends_on: [1, 2, 3, 4, 5]
|
||||
files:
|
||||
- pages/scanner.js
|
||||
- components/scanner/ScannerCamera.js
|
||||
- lib/use-scanner-identification.js
|
||||
- lib/use-scanner-queue.js
|
||||
- test/pages/scanner.test.js
|
||||
- test/components/ScannerCamera.test.js
|
||||
```
|
||||
|
||||
### Boot-the-brief findings (fixed in briefs)
|
||||
|
||||
1. **Layout chrome:** `chrome="immersive"` already renders sidebar + TopSearchBar at
|
||||
`md+` (`Layout.js` uses `max-md:hidden` only). Brief 6 uses `matchMedia` to pass
|
||||
`chrome="default"` on desktop for semantic clarity — no `Layout.js` edit.
|
||||
2. **`verificationPausedRef` overwrite:** `useScannerIdentification` lines 62–66 set
|
||||
the ref to `Boolean(disambiguation)` only, racing page composite pause — Brief 6
|
||||
removes that effect.
|
||||
3. **`addSingleCardToOwned` return:** No success boolean today — Brief 6 extends
|
||||
`use-scanner-queue.js` to return `true`/`false`.
|
||||
4. **Visual suite:** `/scanner` not in `tests/visual/` — no Linux baseline refresh.
|
||||
5. **No new packages** — dep-set check N/A; all primitives exist (`Modal`, `GlassSurface`, `Button`).
|
||||
6. **Gallery batch path verified:** `identifyFromGalleryFile` exists in
|
||||
`use-scanner-identification.js` (line 326) — Brief 5 wraps it sequentially.
|
||||
|
||||
## As-shipped
|
||||
|
||||
Shipped 2026-08-15 as PR #165 (squash `938c161`, commit subject
|
||||
`feat(scanner): add desktop workstation layout (#165)`). All six briefs'
|
||||
surfaces landed: md+ workstation chrome, device picker, Upload Image,
|
||||
Batch Scan, Auto-detect toggle, live match inspector, and the bottom
|
||||
Recent Scans / Scan Queue / Duplicates strip; mobile immersive checkout
|
||||
unchanged below `md`.
|
||||
|
||||
Related post-merge scanner fixes on adjacent convoys (not this scope):
|
||||
#166 (multi-card flow + frame overlay + rate limits) and #167 (manual
|
||||
tap-to-scan shutter).
|
||||
|
|
@ -1,147 +0,0 @@
|
|||
# A11y audit — scanner-desktop-layout
|
||||
|
||||
**Reviewer:** role-a11y-auditor
|
||||
**Convoy:** `scanner-desktop-layout`
|
||||
**Surface:** local UI diff vs `origin/main` (+ untracked workstation components) — audit group `audit-scanner-desktop-layout-local`
|
||||
**Date:** 2026-08-15
|
||||
**Model:** cursor-grok-4.5-high (`model_tier=fast`)
|
||||
**Skill note:** `.cursor/skills/accessibility-audit/SKILL.md` was not present in-repo; audit follows `role-a11y-auditor.md`, prior report shape (`.convoys/scanner-mobile-checkout/audits/a11y-20260814.md`), convoy UX §4 A11y constraints, and WCAG 2.2 AA.
|
||||
|
||||
## Diff scope (UI)
|
||||
|
||||
| Path | Status |
|
||||
| --- | --- |
|
||||
| `pages/scanner.js` | modified (workstation wiring) |
|
||||
| `components/scanner/ScannerCamera.js` | modified (`variant="workstation"`, Auto-detect badge) |
|
||||
| `components/scanner/ScannerResultPanel.js` | **new** |
|
||||
| `components/scanner/ScannerHistoryStrip.js` | **new** |
|
||||
| `components/scanner/ScannerTips.js` | **new** |
|
||||
| `test/components/ScannerHistoryStrip.test.js` | new (a11y-adjacent: tab `aria-label`s) |
|
||||
| `test/components/ScannerResultPanel.test.js` | new (condition name / foil switch) |
|
||||
| `test/components/ScannerTips.test.js` | new |
|
||||
| `test/components/ScannerCamera.test.js` | new |
|
||||
|
||||
Non-UI (`lib/use-camera-scanner.js`, batch helper, queue hooks) excluded from findings except where they gate AT-visible status.
|
||||
|
||||
Patterns referenced: `components/ui/Modal.js` (`useFocusTrap`, `role="dialog"`), `components/ui/Button.js` (ember `focus-visible` ring, visible label in name).
|
||||
|
||||
## Executive summary
|
||||
|
||||
- Desktop workstation ships strong foundations: Tips via `<Modal>` + trap, Auto-detect / Foil `role="switch"`, strip `tablist`/`tab`/`tabpanel` with badge counts in `aria-label`, condition `aria-label` includes card name, commit errors `role="alert"`, ember `focus-visible` rings, toast `role="status"`, mobile checkout `inert`/`trapActive` carry-forward.
|
||||
- **No severity ≥ 3 findings.** Several **sev-2** gaps vs promised UX §4 constraints: Camera fallback lacks `aria-describedby`; Auto-detect overlay badge has no `aria-live`; batch progress + Cancel live only inside the Queue `tabpanel` (often `hidden`); empty-inspector “Identifying…” is wired to disambiguation, not identify-in-flight; queue badge white-on-ember is ~4.44:1; `--color-*` semantic tokens appear undefined in `styles/`.
|
||||
- **Recommendation:** comment-only for merge gate (no sev ≥ 3); fix the §4 constraint fails (A1–A4) in this PR or an immediate a11y follow-up.
|
||||
|
||||
**Counts:** 8 findings (sev ≥ 3: **0**, sev < 3: **8**). Constraint checklist: **8 pass / 3 partial / 3 fail**.
|
||||
|
||||
## Convoy constraint checklist (UX §4)
|
||||
|
||||
| # | Constraint | Result | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | **1.4.3** Contrast text on glass | **Partial** | Body `--text-primary/secondary` on solid `--bg-*` ≥ 4.5:1 (sampled). Queue badge `#ffffff` on `--accent-ember` ≈ **4.44:1** (fails normal text). Glass composite not instrumented. |
|
||||
| 2 | **1.4.10** Reflow @ 768 / 200% | **Pass*** | `md:flex-row` → column below `md`; strip `overflow-x-auto` only (*static; no browser zoom run). |
|
||||
| 3 | **1.4.11** Focus not obscured (sticky) | **Pass** | Inspector rail is flex column sibling — not `position: sticky/fixed`. Batch banner sits in strip flow. |
|
||||
| 4 | **2.1.1** Keyboard all actions | **Partial** | Desk controls, tips, inspector, tabs, chips, Clear All, View All are `<button>`/`<select>`. Batch **Cancel** only mounts on Queue tab — reachable after tab switch, not after Batch Scan without navigating. |
|
||||
| 5 | **2.4.3** Focus order | **Pass** | DOM ≈ convoy: Tips → camera → desk (Camera → Upload → Batch → Auto-detect) → inspector → strip tabs → chips → View All. |
|
||||
| 6 | **2.4.7** Focus visible | **Pass** | Ember `focus-visible:ring-2` on Button, switches, selects, tabs, chips, Clear All. |
|
||||
| 7 | **2.4.11** Focus not obscured (modals) | **Pass** | Tips / leave / list picker use `Modal` + `useFocusTrap`; Escape closes. |
|
||||
| 8 | **4.1.2** Auto-detect switch | **Pass** | `role="switch"` `aria-checked={!isAutoDetectPaused}` `aria-labelledby` → visible **Auto-detect**. |
|
||||
| 9 | **4.1.2** Strip tabs | **Pass** | `tablist` / `tab` / `tabpanel`, `aria-selected`, `aria-controls`, badge counts in `aria-label` (locked by tests). |
|
||||
| 10 | **4.1.2** Camera `<select>` + `aria-describedby` | **Fail** | Visible `<label>Camera</label>` OK; fallback `<p>` has **no `id` / no `aria-describedby`**. |
|
||||
| 11 | **4.1.2** Condition + Foil | **Pass** | Condition `aria-label={`Condition for ${card.name}`}`; Foil switch + `aria-labelledby`. |
|
||||
| 12 | **4.1.3** Auto-detect badge live region | **Fail** | Overlay badge is visual only (decorative dot `aria-hidden`); **no `aria-live`**. Switch announces only when focused/toggled. |
|
||||
| 13 | **4.1.3** Batch progress live + toast | **Partial** | Banner has `aria-live="polite"` + `progressbar`; toast `role="status"`. Banner lives only inside Queue panel — silent when another tab is selected. |
|
||||
| 14 | **3.3.1** Identify failed + commit alert | **Pass** | Chip shows **Identify failed** + reason; inspector `role="alert"` for commit errors. |
|
||||
| 15 | **2.5.3** Label in Name | **Pass** | Upload Image / Batch Scan / Scanner Tips / vocab CTAs use visible text (not icon-only). |
|
||||
| 16 | Live region discipline | **Partial** | One batch banner (good); camera toast + page toast both `aria-live="polite"`; DetectionFrame also polite (pre-existing). |
|
||||
|
||||
## Findings
|
||||
|
||||
| Sev | Layer | WCAG | Surface | Issue | Fix |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **2** | Robust / Name | 1.3.1, 4.1.2 | `pages/scanner.js` ~L415–418 | Device fallback message is not linked to the Camera `<select>` (`aria-describedby` promised). Disabled empty/denied states are orphaned for AT. | Give message `id="scanner-camera-select-hint"`; set `aria-describedby={camera.devicePickerMessage ? 'scanner-camera-select-hint' : undefined}` on `<select>`. |
|
||||
| **2** | Status | 4.1.3 | `ScannerCamera.js` ~L350–370 | Workstation Auto-detect ON/OFF badge has no live region (constraint 12). | Wrap badge text in `role="status" aria-live="polite"` (or `aria-live` on the GlassSurface), e.g. announce `Auto-detect ON` / `OFF` when `autoDetectOn` changes. Keep decorative dot `aria-hidden`. |
|
||||
| **2** | Status / Operable | 4.1.3, 2.1.1 | `ScannerHistoryStrip.js` ~L277–285; `pages/scanner.js` `handleBatchChange` | `BatchProgressBanner` (live region + Cancel) renders only inside Queue `tabpanel`. Default/other tabs leave banner `hidden` → progress often unannounced; Cancel not in immediate focus path after Batch Scan. | On batch start: `setStripActiveTab(TAB_QUEUE)`; and/or mount a single always-visible polite region + Cancel above the tablist (one live region). |
|
||||
| **2** | Status | 4.1.3 | `pages/scanner.js` ~L520; `ScannerResultPanel.js` ~L83–86 | `isIdentifying={Boolean(identification.disambiguation)}` never reflects gallery/webcam identify-in-flight → empty rail stays “Point your camera…” instead of “Identifying…”. | Pass a real identifying flag from identification hook (or `galleryBusy \|\| batchBusy` / in-flight promise); keep disambiguation separate. Prefer `aria-live="polite"` on the Identifying copy. |
|
||||
| **2** | Perceivable | 1.4.3 | `ScannerHistoryStrip.js` ~L246–254 | Badge uses hardcoded `#ffffff` on `--accent-ember` (~**4.44:1**) under 4.5:1 for `text-xs`. | Use a tokenized on-accent color that clears 4.5:1, or enlarge/bold to large-text threshold, or place count in `aria-label` only with a higher-contrast chip chrome. |
|
||||
| **2** | Perceivable | 1.4.11, 1.4.1 | `ScannerResultPanel.js` `confidenceRingColor`; error alerts | `--color-success` / `--color-warning` / `--color-error` / `--color-info` are **referenced but not defined** under `styles/` (or Tailwind theme). Mid/high confidence fills and error tints may not paint; low band still uses `--accent-ember`. Text % + captions / `role="alert"` mitigate. | Define semantic tokens in the design-token surface (or map to existing `--accent-*` / documented status colors) so bar fill meets **3:1** vs track and error text remains distinguishable. |
|
||||
| **1** | Keyboard | 2.1.1 (APG) | `ScannerHistoryStrip.js` tablist | Tabs are all in Tab order; no arrow-key roving `tabIndex` (ARIA APG tabs pattern). | Optional: selected tab `tabIndex={0}`, others `-1`; Left/Right moves selection. Not required for WCAG if all tabs remain operable. |
|
||||
| **1** | Status | 4.1.3 | `pages/scanner.js` + `ScannerCamera.js` | Page-level `ScannerToast` and in-camera toast are both polite live regions; DetectionFrame adds more. Risk of duplicate/noisy announcements. | Prefer one page-level toast on desktop workstation; suppress camera toast when `variant="workstation"`, or share a single live region host. |
|
||||
|
||||
### Severity ≥ 3 detail
|
||||
|
||||
None.
|
||||
|
||||
## Layer walk (5 layers, summary)
|
||||
|
||||
| Layer | Verdict |
|
||||
| --- | --- |
|
||||
| **1 Perceivable** | Token body text contrast OK on solids; badge white/ember short; confidence mid/high fill tokens missing; confidence still has % + caption (not color-only); reflow structure OK statically. |
|
||||
| **2 Operable** | Focus rings consistent with Button/Modal; modals trapped; batch Cancel discoverability weak; tab APG optional. |
|
||||
| **3 Understandable** | Labels strong (Camera, Auto-detect, Foil, condition-with-name, vocab CTAs); leave modal copy includes count + “Keep scanning”; device fallback not programmatically associated. |
|
||||
| **4 Robust** | Switch/tablist/tabpanel/progressbar/alert/status mostly correct; missing `aria-describedby` + badge live region; Identifying flag mis-wired. |
|
||||
| **5 Consistency** | Correctly lifts Modal/Button/GlassSurface; matches ReviewCardItem condition/foil naming; mobile `inert` + `trapActive={!isListPickerOpen}` retained from prior a11y fix. |
|
||||
|
||||
## Suggested diffs (priority)
|
||||
|
||||
1. **P1** — Camera `aria-describedby` ↔ fallback message id.
|
||||
2. **P1** — Auto-detect badge `aria-live="polite"` (or `role="status"`).
|
||||
3. **P1** — On batch start, select Queue tab **or** hoist progress+Cancel outside `hidden` tabpanels (single polite region).
|
||||
4. **P1** — Wire real `isIdentifying` for empty inspector + polite announcement.
|
||||
5. **P2** — Badge contrast; define `--color-success|warning|error|info`.
|
||||
6. **P3** — Optional tab roving tabindex; dedupe desktop toasts.
|
||||
|
||||
### Minimal patches (illustrative)
|
||||
|
||||
```jsx
|
||||
// pages/scanner.js — Camera describedby
|
||||
<p id="scanner-camera-select-hint" className="text-xs" style={{ color: 'var(--text-secondary)' }}>
|
||||
{camera.devicePickerMessage}
|
||||
</p>
|
||||
<select
|
||||
id="scanner-camera-select"
|
||||
aria-describedby={camera.devicePickerMessage ? 'scanner-camera-select-hint' : undefined}
|
||||
…
|
||||
/>
|
||||
```
|
||||
|
||||
```jsx
|
||||
// ScannerCamera.js — badge live region
|
||||
<GlassSurface … role="status" aria-live="polite">
|
||||
<span className="…" aria-hidden="true" />
|
||||
Auto-detect {autoDetectOn ? 'ON' : 'OFF'}
|
||||
</GlassSurface>
|
||||
```
|
||||
|
||||
```js
|
||||
// pages/scanner.js — batch start
|
||||
setStripActiveTab(TAB_QUEUE);
|
||||
setBatchProgress({ active: true, current: 0, total: files.length, onCancel: … });
|
||||
```
|
||||
|
||||
## Patterns to lift
|
||||
|
||||
- `Button` — visible children + ember `focus-visible` ring; keep for desk/inspector CTAs.
|
||||
- `Modal` + `useFocusTrap` — correct Tips / leave / list picker shell; do not invent a second dialog.
|
||||
- Strip tab `aria-label` helpers (`queueTabAriaLabel` / `duplicatesTabAriaLabel`) — good; keep badge `aria-hidden` on visual count.
|
||||
- Foil / Auto-detect switch markup — reusable 44×44 hit pad + `aria-labelledby`.
|
||||
- Prior mobile fix: `inert` + `trapActive={!isListPickerOpen}` — retain.
|
||||
|
||||
## Automated checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| axe-core / CI a11y job | Not run (static role audit) |
|
||||
| Contrast math | Sampled token pairs + white/ember badge (see § checklist) |
|
||||
| Manual SR | Recommend VoiceOver: toggle Auto-detect; start Batch Scan from Recent tab; deny camera permission and inspect select description; commit error alert |
|
||||
|
||||
## Approval recommendation
|
||||
|
||||
- [ ] approve
|
||||
- [ ] request-changes (sev ≥ 3)
|
||||
- [x] **comment-only** — no sev ≥ 3; **fix A1–A4 (sev 2 constraint fails) before or immediately after merge**
|
||||
|
||||
## Hand-off
|
||||
|
||||
A11y audit complete. **8 findings** (sev ≥ 3: **0**, sev < 3: **8**).
|
||||
Report: `.convoys/scanner-desktop-layout/audits/a11y-20260815.md`.
|
||||
Recommend fixing sev ≥ 3 before merge — none open; still land P1 constraint fixes (describedby, badge live region, batch progress visibility, Identifying wiring).
|
||||
|
|
@ -1,153 +0,0 @@
|
|||
# Design-System Audit — scanner-desktop-layout
|
||||
|
||||
**Role:** `role-design-system-auditor`
|
||||
**Surface:** `convoy/scanner-desktop-layout` workstation UI (`git diff origin/main` + untracked scanner components)
|
||||
**Convoy:** `.convoys/scanner-desktop-layout.md`
|
||||
**Multitask group:** `audit-scanner-desktop-layout-local`
|
||||
**Date:** 2026-08-15
|
||||
**Scope:** UI / DS only — read-only; no code changes
|
||||
|
||||
**Inputs reviewed**
|
||||
|
||||
| Source | Notes |
|
||||
| --- | --- |
|
||||
| Diff UI (vs `origin/main`) | `pages/scanner.js`, `components/scanner/ScannerCamera.js` (+ unrelated dashboard/Layout noise in same branch tip — **out of audit scope**) |
|
||||
| Untracked (convoy) | `ScannerTips.js`, `ScannerResultPanel.js`, `ScannerHistoryStrip.js` + component tests |
|
||||
| Direction lock | `design_direction` v1 + `## Design direction` + `## UX` |
|
||||
| Tokens | `docs/DESIGN_TOKENS.md`, `styles/globals.css` |
|
||||
| Primitives | `components/ui/{GlassSurface,Button,Modal,Input}.js` |
|
||||
| Skill | `.cursor/skills/design-systems/SKILL.md` **not installed**; report follows prior Liquid Glass audit shape + role file |
|
||||
|
||||
---
|
||||
|
||||
## Audit summary
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Direction lock (md+ workstation grid) | ✅ Strong | Framed camera + desk bar + inspector rail + history strip + Tips Modal; mobile immersive left alone |
|
||||
| Hex in JSX (new convoy files) | ❌ | `#ffffff` on Queue/Duplicates badge in `ScannerHistoryStrip.js` |
|
||||
| VOCAB / stale strings | ✅ | `VOCAB.ADD_TO_*` / `MY_COLLECTION`; no Wishlist / Mark Owned / All My Cards |
|
||||
| `backdrop-filter` on strip chips | ✅ | Chips solid `--bg-secondary`; container is `GlassSurface tint="mid"` |
|
||||
| GlassSurface / Button / Modal reuse | ✅ High | Tips=`Modal`; inspector/strip/desk/camera frame=`GlassSurface`; primary CTAs=`Button` |
|
||||
| Custom modal scrim | ✅ | Tips + leave + list picker use `<Modal>` only |
|
||||
| Sev ≥ 3 findings | **1** | Hex literal on tab badges |
|
||||
|
||||
---
|
||||
|
||||
## Maturity scoring (repo DS + this surface)
|
||||
|
||||
Scores 0–4. Evidence cites paths/counts.
|
||||
|
||||
| Axis | Score | Evidence |
|
||||
| --- | --- | --- |
|
||||
| **Tokens (T)** | **3** | Workstation surfaces consume `--glass-surface-*` via `GlassSurface`, `--text-*`, `--accent-ember` / `--accent-flame`, `--ember-rim-*`, `--border`. Residual: on-accent text still `#ffffff` in new strip badges (and pre-existing `Button.js` primary/danger). No `--text-on-accent` alias in `globals.css`. |
|
||||
| **Components (C)** | **3** | Kit: GlassSurface, Modal, Button, Input, SearchBar, StatCard. New surfaces compose GlassSurface + Button + Modal. Gaps: no Switch / TabList primitive — Auto-detect + Foil switches and strip tabs are raw `<button>` (acceptable; pattern repeated ×3). |
|
||||
| **Patterns (P)** | **3** | Locked workstation pattern largely shipped: `Layout chrome="default"` at md+, camera `variant="workstation"` with ember brackets + reduced-motion scan-line (`ScannerCamera.js` `DetectionFrame`), desk `GlassSurface mid`, inspector `tint="low"`, strip three tabs + batch banner, Tips `<Modal size="md">`. Minor drift: confidence fill uses `--color-warning` / `--color-success` vs direction’s flame/gold highlight row (aligned with UX “reuse ReviewCardItem” instead). |
|
||||
| **Governance (G)** | **3** | Convoy `design_direction` locked 2026-08-15; `ui-and-theming.mdc` + vocab CI; `forbidden-hex-in-jsx` documented in `DESIGN_TOKENS.md`. Design-systems skill package still absent in-repo. |
|
||||
| **Adoption (A)** | **3** | Desktop surface counts: `<Button>` ×12 across `scanner.js` + ResultPanel + HistoryStrip + Tips; `<GlassSurface>` on camera frame, desk bar, inspector, strip container, Auto-detect badge; `<Modal>` ×1 Tips + leave/list on page. Chips correctly **avoid** GlassSurface blur. Raw `<button>` ×7 mostly switches/tabs/Clear All (direction allows Clear All as text link). |
|
||||
|
||||
**Composite:** T3 / C3 / P3 / G3 / A3
|
||||
|
||||
**Top leverage:** **Tokens (T)** — introduce a shared on-accent text token (or route badge text through `<Button>` / a tiny Badge primitive) and purge `#ffffff` from convoy JSX so the hex gate and Liquid Glass lock stay green.
|
||||
|
||||
---
|
||||
|
||||
## Direction lock
|
||||
|
||||
Locked fields enforced: Liquid Glass; md+ workstation (camera + inspector + strip); ember accents; VOCAB CTAs; no hex; no per-chip `backdrop-filter`; Tips via `<Modal>`; no custom scrim; mobile immersive unchanged.
|
||||
|
||||
| Locked requirement | Diff status |
|
||||
| --- | --- |
|
||||
| md+ `chrome="default"`; mobile immersive | ✅ `pages/scanner.js` |
|
||||
| Page title / subtitle + Scanner Tips | ✅ Header + `ScannerTips` |
|
||||
| Camera framed panel + ember brackets | ✅ `variant="workstation"` + `DetectionFrame` L-brackets + scan-line + `prefers-reduced-motion` |
|
||||
| Desk bar: Camera / Upload / Batch / Auto-detect | ✅ `GlassSurface tint="mid"` + native `<select>` + `Button`×2 + switch |
|
||||
| Device picker fallbacks inline (not modal) | ✅ `camera.devicePickerMessage` under select |
|
||||
| Inspector rail `w-[360px]` + GlassSurface low | ✅ `ScannerResultPanel` |
|
||||
| Empty / confidence / VOCAB primary + Rescan / Add to List | ✅ |
|
||||
| Strip: Recent / Queue / Dupes + Clear All + View All | ✅ `ScannerHistoryStrip` |
|
||||
| Chips solid `--bg-secondary`; focused ember rim | ✅; no chip `backdrop-filter` |
|
||||
| Batch progress + Cancel | ✅ `BatchProgressBanner` |
|
||||
| Tips = `<Modal>` five tips (not popover) | ✅ `ScannerTips.js` |
|
||||
| No hex / no Wishlist / Mark Owned | ❌ one `#ffffff`; vocab clean |
|
||||
| Checkout sheet mobile-only | ✅ `md:hidden` mount |
|
||||
|
||||
---
|
||||
|
||||
## Token audit (3-tier)
|
||||
|
||||
| Tier | Expectation | Diff notes |
|
||||
| --- | --- | --- |
|
||||
| Primitives | Hex only in CSS token definitions | No new CSS hex from convoy. **JSX** `#ffffff` in strip badge violates consumer rule. |
|
||||
| Aliases | `--glass-surface-*`, blur, rim, elevation, text, accent | Correctly used via GlassSurface props + `var(--*)` styles. Missing alias for on-accent / inverse text (primitives still hardcode `#ffffff`). |
|
||||
| Components | GlassSurface / Button / Modal compose aliases | Desk, inspector, strip, Tips comply. Tab badge invents parallel on-accent styling instead of composing Button/Badge. |
|
||||
|
||||
---
|
||||
|
||||
## Component / adoption audit (scoped desktop surface)
|
||||
|
||||
| Element | Expected | Actual | Rate |
|
||||
| --- | --- | --- | --- |
|
||||
| Camera frame | `GlassSurface` low + ember rim | Yes (`ScannerCamera` workstation branch) | High |
|
||||
| Desk control bar | `GlassSurface` mid | Yes (`pages/scanner.js`) | High |
|
||||
| Inspector | `GlassSurface` low | Yes (`ScannerResultPanel`) | High |
|
||||
| History strip shell | `GlassSurface` mid | Yes | High |
|
||||
| Strip chips | Solid `--bg-secondary` (no blur) | Yes | High |
|
||||
| Tips | `<Modal>` | Yes | High |
|
||||
| Primary / secondary CTAs | `<Button>` | Yes (Upload, Batch, Add, Rescan, Cancel, View All) | High |
|
||||
| Auto-detect / Foil | Switch pattern | Raw `<button role="switch">` ×2 | Medium — no Switch primitive |
|
||||
| Strip tabs | tablist | Raw `<button role="tab">` | Medium — correct a11y; not Button |
|
||||
| Clear All | Text link | Raw `<button>` ember text | Medium — matches direction “text link” |
|
||||
| Leave / List | `<Modal>` | Yes (page) | High |
|
||||
|
||||
**Missing primitive (optional follow-up):** `Switch` (and optionally `Badge`) would remove duplicated toggle/`#ffffff` badge styling across desk + inspector + strip.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
Severity 0–4. Cap prioritized; sev ≥ 3 blocks merge recommendation for DS gate.
|
||||
|
||||
| ID | Sev | Finding | Evidence | Fix |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| DS-1 | **3** | Hardcoded hex in convoy JSX | `ScannerHistoryStrip.js` tab badge `color: '#ffffff'` (≈L250) | Replace with theme token (add `--text-on-accent` / reuse Button’s on-accent once tokenized) so `forbidden-hex-in-jsx` stays green |
|
||||
| DS-2 | **2** | Toggle knobs use Tailwind `bg-white` | `pages/scanner.js` Auto-detect knob; `ScannerResultPanel.js` Foil knob | Prefer `backgroundColor: 'var(--bg-primary)'` or a documented knob token — avoid raw white utility on themed surfaces |
|
||||
| DS-3 | **1** | Confidence bar accent drift vs Design direction color table | `ScannerResultPanel` `confidenceRingColor`: mid `--color-warning`, high `--color-success` | Optional align to `--accent-flame` / `--accent-gold` for ≥90% match badge; or document UX override (ReviewCardItem reuse) as accepted |
|
||||
| DS-4 | **1** | Clear All lacks destructive hover | Always `--accent-ember` | Direction: destructive on hover — add hover token mix if shipping polish pass |
|
||||
| DS-5 | **1** | Systemic on-accent hex in primitive (context) | `components/ui/Button.js` primary/danger still `#ffffff` / `#dc2626` | Out of convoy scope but explains copy-paste; tokenize in a follow-up DS convoy |
|
||||
|
||||
### Passes (not findings)
|
||||
|
||||
- No `"Add to Collection"`, `"Save to Wishlist"`, `"Mark Owned"`, `"All My Cards"` in scoped new UI.
|
||||
- Inspector + strip CTAs import `VOCAB.ADD_TO_MY_COLLECTION` / `VOCAB.ADD_TO_LIST`.
|
||||
- Tips uses `<Modal size="md">` with convoy-authored five tips; no custom scrim.
|
||||
- Strip chips: solid `--bg-secondary`, focused `--ember-rim-pronounced`; no per-chip blur.
|
||||
- Camera detection chrome: ember/flame L-brackets + scan-line with `prefers-reduced-motion` static mid-line.
|
||||
- Auto-detect badge: `motion-safe:animate-pulse` when ON.
|
||||
- Confidence bar width transition gated with `@media (prefers-reduced-motion: reduce)`.
|
||||
- Icons are SVG (lightbulb / empty-state camera), not emoji.
|
||||
- Mobile checkout sheet remains `md:hidden`; workstation controls `hidden md:flex`.
|
||||
|
||||
---
|
||||
|
||||
## Governance notes
|
||||
|
||||
- Contribution path: `docs/DESIGN_TOKENS.md` + `.cursor/rules/ui-and-theming.mdc`.
|
||||
- CI: `forbidden-hex-in-jsx` + stale-vocab gates — **DS-1 will fail the hex gate once these files are in CI’s path**.
|
||||
- Design-systems skill/templates not under `.cursor/skills/design-systems/` — G capped partly by missing shared audit tooling.
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Treat DS as not merge-clean until DS-1 is fixed** (one-line / token swap on the strip badge). DS-2 is the next polish item for light/dark knob contrast. DS-3–DS-5 are non-blocking documentation / follow-up token work.
|
||||
|
||||
**Child tasks (sev ≥ 3):**
|
||||
|
||||
1. Remove `#ffffff` from `ScannerHistoryStrip.js` badge text — use a CSS variable (prefer adding `--text-on-accent: #fff` in `globals.css` and referencing it from Button + badge).
|
||||
|
||||
---
|
||||
|
||||
## Hand-off
|
||||
|
||||
DS audit complete. Maturity: **T3/C3/P3/G3/A3**. Top leverage: invest in **Tokens** (on-accent alias + purge convoy hex). Sev ≥ 3 findings: **1**. Report: `.convoys/scanner-desktop-layout/audits/design-system-20260815.md`.
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
## Reviewer Report
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Scope match | ✅ | Working-tree JS/tests match the union of briefs 1–6 `files:` (camera hook, Tips/Result/History components, batch helper, page + Camera + queue/identification hooks, matching tests). Convoy docs under `.convoys/scanner-desktop-layout/` expected. No out-of-list app code. **Note:** branch tip is behind `origin/main` (merge-base `0d52858`); a naive `git diff origin/main` includes unrelated dashboard-home-realignment reversals — rebase before PR. |
|
||||
| Conventions | ✅ | `VOCAB` used for add actions; `<Modal>` / `GlassSurface` / `Button`; CSS variables (no hex / forbidden stale strings in scanner surfaces); relative imports; no new API routes or schema. |
|
||||
| Security | ✅ | No new auth/API surfaces; client-only. Device id in `sessionStorage` only. Depth deferred to `role-security-auditor` in this fan-out. |
|
||||
| Regression risk | medium | Touches `/scanner` composition, `useCameraScanner` stream constraints, and `verificationPausedRef` ownership (identification overwrite removed). Mobile chrome gated via `variant` + `isDesktop`, but pause/batch heuristics are easy to break. |
|
||||
| Test coverage | ✅ | 45 tests green across briefs 1–6 artifacts (`use-camera-scanner`, batch helper, Tips/Result/History/Camera, page viewport split). Gaps: checkout sheet not exercised open on mobile; Identifying… never wired to real in-flight identify. |
|
||||
| Documentation | ✅ | Convoy + briefs present; no AGENTS.md change required for this UI composition. |
|
||||
|
||||
### Findings
|
||||
|
||||
- 🟡 **Suggestion:** `isIdentifying={Boolean(identification.disambiguation)}` in `pages/scanner.js` does not match Brief 3’s “Identifying…” intent — disambiguation is post-match choice, and the hook has no in-flight identify flag. Empty rail will not show Identifying… during real scans; it may flash the wrong copy if disambiguation opens with no focused card. Wire a real verifying signal or leave `false` until one exists.
|
||||
- 🟡 **Suggestion:** Batch Scan does not switch the strip to **Scan Queue** when `batchProgress.active` (Design direction / strip UX). Progress banner only appears if the user is already on that tab.
|
||||
- 🟡 **Suggestion:** Device picker messages use short status strings (`No camera found`, etc.) but Design direction’s locked table includes action hints (e.g. “Connect a webcam or use Upload Image”). Align copy with the Design table.
|
||||
- 🟡 **Suggestion:** `test/pages/scanner.test.js` asserts the checkout sheet is absent when closed on mobile, but Brief 6 asks for no-regression coverage of the sheet at narrow width — open `isCheckoutOpen` (or equivalent) and assert the sheet mounts under `max-md`.
|
||||
- 🟢 **Nice to have:** Rebase/merge `origin/main` before opening the PR so the diff does not look like a dashboard revert; implementation itself stays in-scope once compared to the brief file union.
|
||||
|
||||
### Approval recommendation
|
||||
- approve
|
||||
|
|
@ -1,30 +0,0 @@
|
|||
## Security Audit
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Auth boundary | ✅ | No new API route or auth flow. `/scanner` keeps its `useAuth` redirect, and the unchanged scan endpoint verifies the Bearer token before its per-user scan rate limit. |
|
||||
| Authorization (IDOR) | ✅ | The desktop list picker uses the existing collection-card API; its server-side POST path confirms authenticated owner/editor permission before mutation. Client-held `collectionId` is not trusted as authorization. |
|
||||
| Input / injection | ⚠️ | File names and server error text are rendered as React text (no HTML sink), but new batch intake has no client-side file-size or count bound before decoding images into a canvas. |
|
||||
| Secrets exposure | ✅ | Device IDs are stored only in tab-scoped `sessionStorage`; no new secret, `NEXT_PUBLIC_*` value, token, or credential was found in the scanner additions. |
|
||||
| Dependencies | ⚠️ | No dependency manifest change is in the supplied diff, but `npm audit --omit=dev --json` reports five pre-existing production high-severity advisories (including `next`, `jws`, `nanoid`, `postcss`, and `sharp`). |
|
||||
|
||||
### Findings
|
||||
|
||||
1. **[Severity 4 — scope expansion]** `git diff origin/main -- . ':!.convoys/.metrics.jsonl'` contains 15 tracked paths outside Briefs 1–6, including dashboard/nav work, `components/Layout.js`, `pages/dashboard.js`, `pages/my-cards.js`, and `pages/api/user-cards.js`; it also deletes the separate `dashboard-home-realignment` convoy artifacts. This violates every brief's explicit file scope and prevents a trustworthy scanner-only review. **Fix:** rebase/cherry-pick the scanner implementation onto `origin/main` (or split the unrelated dashboard/API changes into their own convoy) and re-run the audit. Note that the supplied `git diff` does not show untracked scanner files, so this audit additionally inspected their working-tree contents.
|
||||
|
||||
2. **[Severity 1 — file intake hardening]** `pages/scanner.js:269-300` accepts an arbitrary number of arbitrary-sized `image/*` files, and `lib/use-scanner-identification.js:20-42` decodes each selected image at full natural dimensions into a canvas before the existing server-side 6 MB request cap can apply. A logged-in user can select a very large or decompression-bomb image set, freezing their tab and creating repeated scan attempts. `accept="image/*"` is only a picker hint, not validation. **Fix:** before `runSequentialGalleryIdentify`, enforce a maximum file count, MIME allowlist, and conservative byte limit compatible with the 6 MB base64 server limit; reject failures per file before calling `readFileToImageData`.
|
||||
|
||||
3. **[Severity 2 — inherited production dependency advisories]** `npm audit --omit=dev --json` reports five high-severity production vulnerabilities. The most material is the direct `next` range `<16.2.11`; the audit also identifies transitive `jws`, `nanoid`, `postcss`, and `sharp`. No package manifest changed in this convoy, so this is not introduced by the scanner work, but it remains a release risk. **Fix:** open or link the dependency-upgrade/accepted-risk work before release, and verify the deployed Next.js version against the advisories.
|
||||
|
||||
### Layer notes
|
||||
|
||||
- **Layer 1:** Existing scanner endpoints retain authentication and the scan rate-limit gate; this convoy adds no server action or API route.
|
||||
- **Layer 2:** The list picker is UI convenience only. `pages/api/collections/[identifier]/cards.js:90-101` independently requires an authenticated owner/editor for POST, preventing a forged picker ID from becoming an IDOR.
|
||||
- **Layer 3:** React escapes the batch-derived file basename (`pages/scanner.js:226-235`) and failure strings (`components/scanner/ScannerHistoryStrip.js:91-94`); no `dangerouslySetInnerHTML`, `eval`, or shell construction was found. The file-bound finding above remains.
|
||||
- **Layer 4:** `lib/use-camera-scanner.js:37-90` stores only opaque camera device IDs in `sessionStorage`, using a fixed key and guarded reads/writes. No scanner secret is exposed to the client.
|
||||
- **Layer 5:** See dependency finding 3. The full audit reports 16 issues including dev dependencies; the production-only audit reports five high findings.
|
||||
- **Layer 6:** No middleware, Next config, CORS, cookie, or header change was included.
|
||||
|
||||
### Recommendation
|
||||
|
||||
**Do not merge as currently scoped.** Resolve the severity-4 scope expansion first. After isolating the scanner-only diff, add the file size/count/type guard (or document an accepted risk) and re-audit; the existing dependency findings should be tracked or risk-accepted separately because they were not introduced here.
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/use-camera-scanner.js
|
||||
- test/lib/use-camera-scanner.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 6
|
||||
description: |
|
||||
Exports `videoDevices`, `selectedDeviceId`, `setSelectedDeviceId`,
|
||||
`devicePickerStatus` (`loading` | `ready` | `empty` | `denied` | `error`),
|
||||
and `devicePickerMessage` for the desk Camera `<select>` in Brief 6.
|
||||
Mobile callers keep using `facingMode` / `switchFacingMode` only — do not
|
||||
mount the device picker below `md`.
|
||||
---
|
||||
|
||||
# Brief 1: Webcam device picker hook
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Extend `useCameraScanner` with `enumerateDevices` + `deviceId` stream selection for desktop webcams while preserving mobile facing-mode swap.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `lib/use-camera-scanner.js`
|
||||
- `test/lib/use-camera-scanner.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- Tagged-template / relative imports only; no path aliases.
|
||||
- No hex in JS — use CSS variables if any inline styles are needed in tests.
|
||||
- `getUserMedia` constraints: when `selectedDeviceId` is set, use
|
||||
`{ video: { deviceId: { exact: selectedDeviceId }, width: { ideal: 1280 }, height: { ideal: 720 } } }`;
|
||||
when unset, keep existing `facingMode` constraint shape.
|
||||
- Call `enumerateDevices` after the first successful stream (labels require an
|
||||
active permission grant). Filter `kind === 'videoinput'`.
|
||||
- Optional cheap persist: `sessionStorage` key `scanner:last-camera-device-id`
|
||||
— read on init, write on `setSelectedDeviceId`.
|
||||
- Restart stream on `selectedDeviceId` change (same pattern as `activeFacingMode`
|
||||
effect). Guard with a ref to skip the initial mount double-start.
|
||||
- `verificationPausedRef` contract unchanged — camera hook does not own pause logic.
|
||||
- Mirror existing test style in `test/lib/scanner-card-detection.test.js` (vitest,
|
||||
mocks for `navigator.mediaDevices`).
|
||||
|
||||
## Implementation shape (verified against current hook)
|
||||
|
||||
Current hook returns `facingMode`, `switchFacingMode` only — no `deviceId`.
|
||||
`startCamera` uses `facingMode: activeFacingModeRef.current` exclusively.
|
||||
|
||||
Add:
|
||||
|
||||
```js
|
||||
const [videoDevices, setVideoDevices] = useState([]);
|
||||
const [selectedDeviceId, setSelectedDeviceId] = useState(() => {
|
||||
try {
|
||||
return sessionStorage.getItem('scanner:last-camera-device-id') || '';
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
});
|
||||
const [devicePickerStatus, setDevicePickerStatus] = useState('loading');
|
||||
```
|
||||
|
||||
`refreshVideoDevices` async helper:
|
||||
|
||||
1. If `!navigator.mediaDevices?.enumerateDevices`, set status `error`.
|
||||
2. Map videoinputs; if length === 0 → `empty`.
|
||||
3. If `selectedDeviceId` not in list, fall back to first device or ''.
|
||||
4. On `NotAllowedError` from prior getUserMedia → `denied`.
|
||||
|
||||
Export `setSelectedDeviceId` wrapper that persists to sessionStorage.
|
||||
|
||||
**Do not** remove `switchFacingMode` — mobile Brief 3 camera chrome still uses it.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `enumerateDevices` populates `videoDevices` after stream start in tests (mocked)
|
||||
- [ ] `selectedDeviceId` switches `getUserMedia` constraints to `deviceId: { exact }`
|
||||
- [ ] `switchFacingMode` still toggles environment/user when no deviceId forced
|
||||
- [ ] `devicePickerStatus` + message cover loading, empty, denied, error per Design direction table
|
||||
- [ ] sessionStorage persist for last device id (read/write with try/catch)
|
||||
- [ ] tests added in `test/lib/use-camera-scanner.test.js`
|
||||
- [ ] no scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Desktop workstations need a real webcam picker (C4), not a relabeled facing-mode swap. Isolating device enumeration in the hook keeps `ScannerCamera` and `pages/scanner.js` thin. Mobile behavior stays untouched because deviceId is only consumed at the page/camera wiring layer in Brief 6.
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 2
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/scanner/ScannerTips.js
|
||||
- test/components/ScannerTips.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 6
|
||||
description: |
|
||||
Brief 6 mounts `<ScannerTips />` in the desktop page header row (md+ only)
|
||||
beside "Card Scanner" title. This brief ships the self-contained modal +
|
||||
trigger button; no page wiring here.
|
||||
---
|
||||
|
||||
# Brief 2: Scanner Tips modal
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Ship a desktop Scanner Tips control that opens a glass `<Modal>` with five convoy-authored tips.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `components/scanner/ScannerTips.js`
|
||||
- `test/components/ScannerTips.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- Use `Modal` + `Button` from `components/ui` — no custom scrim (`ui-and-theming.mdc`).
|
||||
- Glass panel recipe: `--glass-surface-low` via `GlassSurface` inside modal body if needed.
|
||||
- Copy locked (Design direction + IA):
|
||||
|
||||
| # | Tip |
|
||||
| --- | --- |
|
||||
| 1 | **Good lighting** — avoid glare on foil cards. |
|
||||
| 2 | **Fill the frame** with one card; keep corners visible. |
|
||||
| 3 | **Hold still** until Auto-detect locks the match. |
|
||||
| 4 | **Use Batch Scan** for a pile of photos from your gallery. |
|
||||
| 5 | **Switch camera** if the image is dark or mirrored. |
|
||||
|
||||
- Modal title: **Scanner Tips**. Trigger: ghost `Button` with lightbulb SVG + label **Scanner Tips** (visible text for 2.5.3 Label in Name).
|
||||
- Dismiss: close control, Esc, scrim click — standard `<Modal>` behavior.
|
||||
- No hex in `.js`; tokens only.
|
||||
- Test pattern: `test/components/ScannerCheckoutSheet.test.js` (vitest + jsdom + RTL).
|
||||
|
||||
## Implementation shape
|
||||
|
||||
```js
|
||||
export default function ScannerTips({ className = '' }) {
|
||||
const [open, setOpen] = useState(false);
|
||||
return (
|
||||
<>
|
||||
<Button variant="ghost" onClick={() => setOpen(true)} /* lightbulb + Scanner Tips */ />
|
||||
<Modal open={open} onClose={() => setOpen(false)} title="Scanner Tips" size="md">
|
||||
<ol className="space-y-4 text-sm" style={{ color: 'var(--text-secondary)' }}>
|
||||
{/* five <li> with <strong> lead + em dash body */}
|
||||
</ol>
|
||||
</Modal>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Component is self-contained — no props required v1.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Trigger shows lightbulb icon + **Scanner Tips** visible label
|
||||
- [ ] Modal lists exactly five tips with locked copy
|
||||
- [ ] Uses `<Modal>` primitive (no `fixed inset-0 bg-black` shell)
|
||||
- [ ] Opening/closing traps focus per existing Modal behavior
|
||||
- [ ] tests: trigger opens modal, all five tips visible, close dismisses
|
||||
- [ ] no scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Tips are a standalone surface (C3) with no queue or camera dependencies. Shipping the modal in isolation lets Brief 6 wire it into the header without blocking other parallel work. Five tips exceed popover length — Modal is Design-locked.
|
||||
|
|
@ -1,78 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 3
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/scanner/ScannerResultPanel.js
|
||||
- test/components/ScannerResultPanel.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 6
|
||||
description: |
|
||||
Brief 6 passes `focusedCard`, `queue`, `isIdentifying`, handlers
|
||||
(`onAddToOwned`, `onAddToList`, `onRescan`), and `commitError`. On
|
||||
successful add, Brief 6 advances `focusedCardId` to the next unprocessed
|
||||
entry and fires `ScannerToast` — this component calls `onAddToOwned` only.
|
||||
---
|
||||
|
||||
# Brief 3: Live match inspector rail
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Build the right-rail `ScannerResultPanel` that inspects the focused cart entry and commits one card via `VOCAB.ADD_TO_MY_COLLECTION`.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `components/scanner/ScannerResultPanel.js`
|
||||
- `test/components/ScannerResultPanel.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- Import `VOCAB` from `lib/collection-vocabulary.js` — never ship forbidden strings
|
||||
(`forbidden-stale-strings` CI).
|
||||
- Primitives: `GlassSurface`, `Button` from `components/ui`.
|
||||
- Duplicate minimally from `ReviewCardItem.js`: `CONDITION_OPTIONS`,
|
||||
`confidencePercent`, `confidenceRingColor` (do not edit `ReviewCardItem` in this brief).
|
||||
- Confidence captions (Design direction): ≥90% *Excellent match.* · ≥70% *Good match.*
|
||||
· <70% *Low confidence — verify before adding.*
|
||||
- Inspector thumbnail + tiles: solid `--bg-secondary` — **no `backdrop-filter`** on per-card elements.
|
||||
- Empty state: centered muted scan/camera SVG illustration + single line:
|
||||
*Point your camera at a card or upload an image to see a match.* — **no** Upload/Batch CTAs in rail.
|
||||
- Populated: thumbnail, name (`text-lg font-semibold`), set · rarity · collector #,
|
||||
condition `<select>` (`aria-label` includes card name), foil `role="switch"`,
|
||||
confidence % + horizontal bar (300ms width transition; `@media (prefers-reduced-motion: reduce)` → instant).
|
||||
- Actions: primary `VOCAB.ADD_TO_MY_COLLECTION` · ghost **Rescan** · ghost `VOCAB.ADD_TO_LIST`.
|
||||
- Primary `Button` uses `loading` when `isAdding` (from `queue.addingCardIds.has(card.id)`).
|
||||
- Commit errors: `role="alert"` div with `color-mix(in srgb, var(--color-error) …)` pattern from `pages/scanner.js`.
|
||||
- `isIdentifying` state: show *Identifying…* placeholder when true and no focused card yet.
|
||||
|
||||
## Props shape (for Brief 6 wiring)
|
||||
|
||||
```js
|
||||
export default function ScannerResultPanel({
|
||||
focusedCard = null,
|
||||
queue,
|
||||
isIdentifying = false,
|
||||
commitError = null,
|
||||
onAddToOwned,
|
||||
onAddToList,
|
||||
onRescan,
|
||||
}) {
|
||||
```
|
||||
|
||||
`onUpdateMetadata` via `queue.updateCardMetadata(focusedCard.id, patch)` inline.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Empty state: illustration + one line only (no duplicate Upload/Batch)
|
||||
- [ ] Populated state shows metadata, condition select, foil switch, confidence bar
|
||||
- [ ] Primary button label is `VOCAB.ADD_TO_MY_COLLECTION`
|
||||
- [ ] Secondary row: Rescan + `VOCAB.ADD_TO_LIST` (no wishlist)
|
||||
- [ ] `prefers-reduced-motion` disables confidence bar width animation
|
||||
- [ ] tests: empty state, populated card, add button disabled while adding
|
||||
- [ ] no scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
The inspector replaces the 360px cart side panel as the primary right-hand surface on desktop. Keeping it a dumb view lets Brief 6 own focus/advance/toast orchestration. Confidence and condition UX matches checkout patterns users already know from `ReviewCardItem`.
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 4
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/scanner/ScannerHistoryStrip.js
|
||||
- test/components/ScannerHistoryStrip.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 6
|
||||
description: |
|
||||
Brief 6 supplies `focusedCardId`, `onFocusCard`, `batchProgress`
|
||||
(`{ active, current, total, onCancel }`), bulk commit handlers, and
|
||||
`onClearAll`. Row click calls `onFocusCard(card.id)` — no auto-commit.
|
||||
---
|
||||
|
||||
# Brief 4: History / queue / duplicates strip
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Build the bottom `ScannerHistoryStrip` with Recent Scans, Scan Queue, and Duplicates tabs over the existing cart model.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `components/scanner/ScannerHistoryStrip.js`
|
||||
- `test/components/ScannerHistoryStrip.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- `GlassSurface` tint `mid` for strip container; chips use solid `--bg-secondary` fill — **no per-chip `backdrop-filter`**.
|
||||
- Tab labels: **Recent Scans**, **Scan Queue**, **Duplicates** with badge counts on Queue and Duplicates.
|
||||
- `role="tablist"` / `role="tab"` / `role="tabpanel"`; badges in `aria-label`
|
||||
(e.g. `Scan Queue, 3 unprocessed cards`).
|
||||
- Empty tab copy (UX §5): Recent → *No scans yet this session.* · Queue →
|
||||
*Scan queue is empty — matches appear here before you add them.* · Duplicates →
|
||||
*No duplicates detected.*
|
||||
- **Clear All** text link right-aligned; disabled while `batchProgress?.active`.
|
||||
- **View All Scans** ghost button at strip bottom scrolls chip row to end (v1 — no expanded modal).
|
||||
- Chip row: horizontal `overflow-x-auto`, min height 44px, ember rim on focused chip
|
||||
(`focusedCardId === card.id` → `--ember-rim-pronounced`).
|
||||
- Row click → `onFocusCard(card.id)` only — never auto-commit.
|
||||
- Batch progress UI (when `batchProgress.active`): inline banner in Scan Queue tabpanel —
|
||||
*Scanning {current} of {total}…* determinate bar, ghost **Cancel** calling `batchProgress.onCancel`.
|
||||
- Failed identify rows: `identifyFailed` flag on card (Brief 6 sets) → ember left border +
|
||||
**Identify failed** label + optional reason `text-sm`.
|
||||
|
||||
## Duplicate membership helper (export from this file)
|
||||
|
||||
```js
|
||||
export function getDuplicateCards(scannedCards, ownershipMap) {
|
||||
const sessionRepeatIds = new Set();
|
||||
const seen = new Map(); // key: name+set → first id
|
||||
for (const card of scannedCards) {
|
||||
const key = `${card.name}::${card.set}`;
|
||||
if (seen.has(key)) sessionRepeatIds.add(card.id);
|
||||
else seen.set(key, card.id);
|
||||
if ((card.quantity || 1) > 1) sessionRepeatIds.add(card.id);
|
||||
}
|
||||
return scannedCards.filter(
|
||||
(card) =>
|
||||
sessionRepeatIds.has(card.id) ||
|
||||
(card.databaseId && ownershipMap[card.databaseId])
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Recent Scans** tab: all `scannedCards` session history (processed + unprocessed), newest first.
|
||||
**Scan Queue** tab: `!card.processed` rows; badge = unprocessed count.
|
||||
**Duplicates** tab: `getDuplicateCards(...)`; badge = duplicate set length.
|
||||
|
||||
## Props shape
|
||||
|
||||
```js
|
||||
export default function ScannerHistoryStrip({
|
||||
scannedCards,
|
||||
ownershipMap,
|
||||
focusedCardId,
|
||||
onFocusCard,
|
||||
activeTab,
|
||||
onTabChange,
|
||||
batchProgress = null,
|
||||
onClearAll,
|
||||
onCommitSelectedToOwned,
|
||||
onOpenListPicker,
|
||||
isProcessing = false,
|
||||
}) {
|
||||
```
|
||||
|
||||
Bulk commit buttons in Queue tab footer: `VOCAB.ADD_TO_MY_COLLECTION` + `VOCAB.ADD_TO_LIST` calling parent handlers (Brief 6 wires `queue.commitSelectedToOwned`).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Three tabs with correct labels and badge counts
|
||||
- [ ] `getDuplicateCards` covers ownershipMap + session name/set repeats + quantity>1
|
||||
- [ ] Row click invokes `onFocusCard` without commit
|
||||
- [ ] Batch progress banner with Cancel when `batchProgress.active`
|
||||
- [ ] Clear All disabled during active batch
|
||||
- [ ] Chip focus ring matches `focusedCardId`
|
||||
- [ ] tests: tab switching, duplicate helper, empty states, batch banner
|
||||
- [ ] no scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
The strip is the second commit surface (C5) alongside the inspector. Centralizing duplicate logic in one exported helper keeps `pages/scanner.js` thin. Tab + chip UX is independent of camera device picker, so this brief parallelizes cleanly.
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 5
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/scanner-batch-identify.js
|
||||
- test/lib/scanner-batch-identify.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 6
|
||||
description: |
|
||||
Brief 6 calls `runSequentialGalleryIdentify(files, identifyFn, options)`
|
||||
from the Batch Scan multi-file picker. On per-file failure Brief 6 enqueues
|
||||
a queue row with `identifyFailed: true` and `identifyError` message; cancel
|
||||
via `cancelRef.current = true` keeps completed rows (IA-locked).
|
||||
---
|
||||
|
||||
# Brief 5: Sequential batch identify helper
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Add a small library helper that runs `identifyFromGalleryFile` sequentially over multiple files with progress, cancel, and per-file failure continuation.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `lib/scanner-batch-identify.js`
|
||||
- `test/lib/scanner-batch-identify.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- **No new API routes** — caller passes `identifyFn` (Brief 6 binds
|
||||
`identification.identifyFromGalleryFile`).
|
||||
- **Sequential only** — one `await identifyFn(file)` at a time; no `Promise.all`.
|
||||
- Respect identify rate limits implicitly (sequential pacing).
|
||||
- Pure JS module — no React.
|
||||
|
||||
## Implementation shape
|
||||
|
||||
```js
|
||||
/**
|
||||
* @typedef {{ current: number, total: number, file: File }} BatchProgress
|
||||
*/
|
||||
|
||||
export async function runSequentialGalleryIdentify(files, identifyFn, options = {}) {
|
||||
const {
|
||||
onProgress,
|
||||
onFileSuccess,
|
||||
onFileError,
|
||||
cancelRef = { current: false },
|
||||
} = options;
|
||||
|
||||
const list = Array.from(files || []);
|
||||
const total = list.length;
|
||||
const results = [];
|
||||
|
||||
for (let i = 0; i < list.length; i++) {
|
||||
if (cancelRef.current) break;
|
||||
const file = list[i];
|
||||
onProgress?.({ current: i + 1, total, file });
|
||||
|
||||
try {
|
||||
await identifyFn(file);
|
||||
results.push({ file, ok: true });
|
||||
onFileSuccess?.({ file, index: i });
|
||||
} catch (error) {
|
||||
results.push({ file, ok: false, error });
|
||||
onFileError?.({ file, index: i, error });
|
||||
// continue — IA forbids stopping the batch
|
||||
}
|
||||
}
|
||||
|
||||
return { results, cancelled: cancelRef.current };
|
||||
}
|
||||
```
|
||||
|
||||
`identifyFn` may not throw today — helper still catches for forward-compat.
|
||||
If `identifyFromGalleryFile` only reports via console, Brief 6 may wrap it to
|
||||
throw on hard failures.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Processes files one-at-a-time in order
|
||||
- [ ] `onProgress` fires before each file with `{ current, total, file }`
|
||||
- [ ] `cancelRef.current = true` stops remaining files but returns partial `results`
|
||||
- [ ] Per-file errors invoke `onFileError` and continue loop
|
||||
- [ ] tests cover success path, mid-batch cancel, and error continuation
|
||||
- [ ] no scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Batch Scan (C1) needs orchestration without touching `use-scanner-identification.js` identify logic. A 60-line pure helper is testable and keeps the page brief focused on UI wiring. Sequential execution avoids Gemini rate-limit storms explicitly forbidden in scope.
|
||||
|
|
@ -1,171 +0,0 @@
|
|||
---
|
||||
convoy: scanner-desktop-layout
|
||||
brief_number: 6
|
||||
depends_on: [1, 2, 3, 4, 5]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- pages/scanner.js
|
||||
- components/scanner/ScannerCamera.js
|
||||
- lib/use-scanner-identification.js
|
||||
- lib/use-scanner-queue.js
|
||||
- test/pages/scanner.test.js
|
||||
- test/components/ScannerCamera.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 1
|
||||
description: |
|
||||
Wires `camera.videoDevices`, `selectedDeviceId`, `setSelectedDeviceId`,
|
||||
and `devicePickerStatus` into the desk Camera `<select>` (md+ only).
|
||||
- brief: 2
|
||||
description: |
|
||||
Mounts `<ScannerTips />` in desktop page header (`hidden md:flex` row).
|
||||
- brief: 3
|
||||
description: |
|
||||
Mounts `<ScannerResultPanel />` with focus/advance/toast orchestration
|
||||
after `addSingleCardToOwned`.
|
||||
- brief: 4
|
||||
description: |
|
||||
Mounts `<ScannerHistoryStrip />` with `focusedCardId`, batch progress,
|
||||
and bulk commit handlers.
|
||||
- brief: 5
|
||||
description: |
|
||||
Batch Scan multi-file input calls `runSequentialGalleryIdentify` with
|
||||
`identification.identifyFromGalleryFile`.
|
||||
---
|
||||
|
||||
# Brief 6: Desktop workstation page wiring
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Wire `pages/scanner.js` into the md+ workstation grid (inspector + strip + desk controls) without regressing mobile immersive checkout.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `pages/scanner.js`
|
||||
- `components/scanner/ScannerCamera.js`
|
||||
- `lib/use-scanner-identification.js`
|
||||
- `lib/use-scanner-queue.js`
|
||||
- `test/pages/scanner.test.js`
|
||||
- `test/components/ScannerCamera.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- **Layout chrome (boot finding):** `chrome="immersive"` already shows sidebar +
|
||||
TopSearchBar at `md+` per `Layout.js` (`max-md:hidden` only on mobile nav).
|
||||
Use explicit viewport split for semantics:
|
||||
|
||||
```js
|
||||
const [isDesktop, setIsDesktop] = useState(false);
|
||||
useEffect(() => {
|
||||
const mq = window.matchMedia('(min-width: 768px)');
|
||||
const sync = () => setIsDesktop(mq.matches);
|
||||
sync();
|
||||
mq.addEventListener('change', sync);
|
||||
return () => mq.removeEventListener('change', sync);
|
||||
}, []);
|
||||
// <Layout chrome={isDesktop ? 'default' : 'immersive'} />
|
||||
```
|
||||
|
||||
Smallest change — no `Layout.js` edits.
|
||||
|
||||
- **Mobile zero regression:** keep `ScannerCheckoutSheet`, overlay camera chrome,
|
||||
`ScannerCountPill`, scan peek — all `md:hidden` or `max-md:` as today.
|
||||
- Remove desktop `ScannerReview` side panel (`hidden md:flex` block) — replaced by
|
||||
inspector + strip.
|
||||
- **Pause coordination (boot finding):** `useScannerIdentification` currently has:
|
||||
|
||||
```js
|
||||
useEffect(() => {
|
||||
if (verificationPausedRef) {
|
||||
verificationPausedRef.current = Boolean(disambiguation);
|
||||
}
|
||||
}, [disambiguation, verificationPausedRef]);
|
||||
```
|
||||
|
||||
**Delete this effect** — page owns composite pause:
|
||||
|
||||
```js
|
||||
verificationPausedRef.current =
|
||||
mobileCheckoutPauses ||
|
||||
isListPickerOpen ||
|
||||
isAutoDetectPaused ||
|
||||
Boolean(identification.disambiguation);
|
||||
```
|
||||
|
||||
Desktop Auto-detect toggle sets `isAutoDetectPaused` (OFF = paused).
|
||||
|
||||
- **Focused card state:** `focusedCardId` + derived `focusedCard`. On new scan,
|
||||
auto-focus latest unprocessed (`scannedCards.find(c => !c.processed)`).
|
||||
- **Inspector add success:** wrap `addSingleCardToOwned` — on success show
|
||||
`ScannerToast` (*Added to My Collection*), advance to next unprocessed or empty.
|
||||
Boot finding: current `addSingleCardToOwned` does not return boolean — check
|
||||
`markCardAsProcessed` by awaiting and verifying card.processed or catch errors;
|
||||
optionally extend queue method to `return true/false` in a follow-up if needed
|
||||
inside this brief only if `use-scanner-queue.js` is NOT in scope — use try/catch
|
||||
around API and inspect state after await.
|
||||
|
||||
**Note:** To return success reliably, add minimal change to
|
||||
`lib/use-scanner-queue.js` `addSingleCardToOwned` → `return true` on success,
|
||||
`return false` on error — **only if needed**; prefer not to expand files list.
|
||||
Alternative: duplicate add call in page using `addScannedCardToOwned` from
|
||||
`scanner-route-api.js` — **rejected**; instead add `return true/false` to
|
||||
`use-scanner-queue.js` is out of files — use `addingCardIds` clearing + no error
|
||||
log as success heuristic OR add `use-scanner-queue.js` to this brief's files.
|
||||
|
||||
**Architect lock:** add `lib/use-scanner-queue.js` to this brief for
|
||||
`addSingleCardToOwned` returning `boolean`.
|
||||
|
||||
- **List picker desktop:** `handleListPick` uses **focused card id** single selection
|
||||
(`queue.addSingleCardToCollection(focusedCard, collectionId)`), not bulk selected set.
|
||||
- **Leave modal:** keep existing; trigger on back + unprocessed queue.
|
||||
- **Batch Scan:** hidden `<input type="file" multiple accept="image/*" />` on desk bar;
|
||||
`runSequentialGalleryIdentify` with `cancelRef`; on `onFileError` enqueue synthetic
|
||||
failed row via `queue.handleCardScanned` with `identifyFailed: true` OR dedicated
|
||||
`enqueueFailedIdentify(file, error)` inline in page.
|
||||
- **Rescan:** clear identify fields on focused card (`updateCardMetadata`), set
|
||||
`processed: false`; if `scanImageUrl` present fetch blob and
|
||||
`identifyFromGalleryFile`; else toast *Rescan from camera*.
|
||||
- **ScannerCamera workstation:** add `variant="default" | "workstation"` (or `layoutMode`).
|
||||
|
||||
At `md+` with `variant="workstation"`:
|
||||
- Container: framed panel not `min-h-[100dvh]` full-bleed — use `md:rounded-xl`,
|
||||
`md:aspect-video`, `md:min-h-0`, outer `GlassSurface` + ember rim.
|
||||
- Hide overlay top bar + bottom bar (`max-md:` keep current).
|
||||
- Hide `ScannerScanPeek`, mobile LIVE badge, `ScannerCountPill` at `md+`.
|
||||
- Show **Auto-detect badge** top-left in frame (ON/OFF from `!verificationPausedRef`
|
||||
composite for auto-detect slice only — pass `autoDetectOn` prop).
|
||||
- Badge dot pulse when ON; `prefers-reduced-motion: reduce` → static dot.
|
||||
- Accept optional `deskControls` slot rendered **below** frame by page OR
|
||||
`deskControlBar` prop — page renders Upload/Batch/Auto-detect/Camera select below.
|
||||
|
||||
- **Desk control bar (page, md+):** Camera `<select>` + Upload Image + Batch Scan +
|
||||
Auto-detect switch per Design direction. Upload uses existing single-file input path.
|
||||
- **Tests:** `test/pages/scanner.test.js` — mock hooks; assert mobile checkout sheet
|
||||
present at narrow width; workstation elements (`ScannerResultPanel`, strip) at `md+`
|
||||
(use `window.matchMedia` mock). `test/components/ScannerCamera.test.js` — overlay
|
||||
chrome hidden at workstation variant.
|
||||
- **Visual-diff:** `/scanner` is **not** in `tests/visual/` (only `home.png`) — no
|
||||
baseline update required.
|
||||
|
||||
## `use-scanner-queue.js` changes
|
||||
|
||||
- `addSingleCardToOwned` returns `true` on success, `false` on error (after `try/catch`).
|
||||
- `addSingleCardToCollection` same boolean return for desktop list picker.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `md+` workstation grid: header + camera column + inspector + bottom strip
|
||||
- [ ] `max-md` immersive checkout sheet unchanged (regression test)
|
||||
- [ ] `chrome` default on desktop, immersive on mobile
|
||||
- [ ] Device picker + Batch Scan + Auto-detect on desk bar only at `md+`
|
||||
- [ ] `ScannerTips` in desktop header
|
||||
- [ ] Inspector advance + toast on successful add
|
||||
- [ ] Batch sequential with cancel + per-file failure flags
|
||||
- [ ] `verificationPausedRef` composite pause without identification hook overwrite
|
||||
- [ ] No forbidden copy strings
|
||||
- [ ] tests added; no visual-diff baseline change
|
||||
- [ ] no scope expansion beyond listed files
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Only one brief can own `pages/scanner.js` composition. Camera workstation variant and pause fix are tightly coupled to page wiring. Briefs 1–5 ship mountable units; this brief integrates them without blocking parallel implementers.
|
||||
|
|
@ -1,265 +0,0 @@
|
|||
---
|
||||
name: scanner-identify-upgrade
|
||||
classification: feature
|
||||
success_metric: |
|
||||
Of legitimate card scans (excluding not_a_card), ≥50% auto-match a
|
||||
catalog printing with no picker; Layer-1 escalate rate falls from 76.7%
|
||||
to ≤40%; median /api/scan/identify latency stays near today's 1.7s p50
|
||||
or improves. Measured on scan_attempts after Phase 1 ships.
|
||||
skip: []
|
||||
status: open
|
||||
created: 2026-08-14
|
||||
depends_on:
|
||||
- add-real-ocr-layer
|
||||
- server-side-scan-pipeline
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
|
||||
# Scanner identify upgrade — epic
|
||||
|
||||
Umbrella for making the camera scanner **faster and more accurate**
|
||||
without replacing the two-layer shape (cheap local path, then
|
||||
server-owned Gemini). Planning-only in this file. Each numbered
|
||||
sub-convoy is its own gated PR stream.
|
||||
|
||||
Worktree: `tcg-vault-worktrees/scanner-identify-upgrade` on
|
||||
`convoy/scanner-identify-upgrade` (branched from `main` @ `c6c1364`).
|
||||
Do **not** land these docs on `feat/scanner-mobile-checkout` — that
|
||||
convoy owns scanner chrome/cart and explicitly leaves identify out of
|
||||
scope.
|
||||
|
||||
## Why
|
||||
|
||||
`add-real-ocr-layer` (PR #38) targeted ≥70% of scans resolving at
|
||||
Layer-1 (Tesseract + `pg_trgm`) with zero Gemini calls. Live
|
||||
`scan_attempts` from the local Neon (2026-05-27 → 2026-08-12, n=224,
|
||||
1 user) shows that target was missed by a wide margin:
|
||||
|
||||
| Signal | Value | Target / note |
|
||||
| --- | --- | --- |
|
||||
| L1 auto-match (`result_kind=matched`) | **5.8% of L1** / 2.7% of all | ≥70% L1 resolve |
|
||||
| L1 escalate | **76.7% of L1** (79/103) | Should be the minority path |
|
||||
| L1 disambiguation | 17.5% of L1 (18/103) | Name-only matcher cannot pick printings |
|
||||
| End-to-end auto-match | **10.3%** (23/224) | User still picks or retries most cards |
|
||||
| L2 `not_a_card` | **44.6% of L2** (54/121) | Detector fires on non-cards |
|
||||
| L2 p50 / p90 latency | **1655 / 2349 ms** | Plus 3.5s hold-still *before* identify |
|
||||
| L1 p50 latency | **158 ms** | Fast, but almost never uniquely matches |
|
||||
| `card_submissions` | 27 pending, 0 reviewed | Catalog-gap queue is unread |
|
||||
|
||||
The six L1 "matches" include noisy Tesseract strips (`J ——`, `Rock
|
||||
Jockey ©`) at confidence 36–68. L1 is a cheap filter that rarely
|
||||
identifies a printing. Meanwhile every card waits
|
||||
`DETECTION_START_DELAY_MS` (1s) + `MIN_FIRST_SEEN_MS_FOR_VERIFY` (2.5s)
|
||||
before OCR starts, and L2 is capped at 5 Gemini calls / user / minute.
|
||||
|
||||
Users feel this as: hold still forever, then pick from a list, or get
|
||||
"not a card" / "saved for review."
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope (this epic)
|
||||
|
||||
1. **`tighten-scan-identify-hot-path`** — Phase 1. Cut the hold-still
|
||||
gate, OCR collector number on L1, structured Gemini JSON, optional
|
||||
`SCAN_VISION_MODEL` bump, stop the automatic second Gemini refine.
|
||||
2. **`improve-scan-card-detection`** — Phase 2. Replace the 320×240
|
||||
Sobel brute-force detector with a real card crop + perspective warp.
|
||||
This was queued in `add-real-ocr-layer` and never opened.
|
||||
3. **`scan-visual-catalog-search`** — Phase 3. Embed catalog
|
||||
`image_url`s; nearest-neighbor the warped crop. Gemini becomes
|
||||
fallback. This is the accuracy leap.
|
||||
|
||||
### Out of scope (this epic)
|
||||
|
||||
- Scanner chrome, cart, checkout (`scanner-mobile-checkout` /
|
||||
`scanner-rebuild`). Identify libs only.
|
||||
- Training a custom card CNN or standing up a Python/CUDA OCR service.
|
||||
- Swapping Tesseract for EasyOCR / PaddleOCR as the *primary* identifier.
|
||||
- Raising the L2 rate limit until Phase 1 hit-rate is re-measured.
|
||||
- Admin review of the 27 pending `card_submissions` (ops, not this epic).
|
||||
|
||||
## Baseline (do not re-query to "start" Phase 1)
|
||||
|
||||
Pulled 2026-08-14 from local `.env.local` → Neon `scan_attempts`.
|
||||
|
||||
```
|
||||
layer | result_kind | n | pct
|
||||
1 | escalate | 79 | 35.3
|
||||
1 | disambiguation | 18 | 8.0
|
||||
1 | matched | 6 | 2.7
|
||||
2 | not_a_card | 54 | 24.1
|
||||
2 | submitted | 26 | 11.6
|
||||
2 | disambiguation | 22 | 9.8
|
||||
2 | matched | 17 | 7.6
|
||||
2 | needs_input | 2 | 0.9
|
||||
```
|
||||
|
||||
L1 escalate text-length buckets (all had ≥3 chars — Tesseract is
|
||||
emitting text that `pg_trgm` cannot match): 3–7 chars n=28; 8–19 n=30;
|
||||
20+ n=21.
|
||||
|
||||
Re-measure with the same grouping after each sub-convoy ships.
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```
|
||||
[baseline pulled 2026-08-14]
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────┐
|
||||
│ 1. tighten-scan-identify-hot-path │
|
||||
│ gates, collector #, schema JSON│
|
||||
└───────────────┬───────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────┐
|
||||
│ 2. improve-scan-card-detection │
|
||||
│ detect + homography crop │
|
||||
└───────────────┬───────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────────────┐
|
||||
│ 3. scan-visual-catalog-search │
|
||||
│ embeddings + pgvector kNN │
|
||||
└───────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Strict-blockers:** #1 before #2 only if #2 would retune the same
|
||||
stability constants — otherwise #1 (identify files) and #2 (detection
|
||||
files) are file-disjoint and may run in parallel after Architect
|
||||
confirms. #3 needs a stable crop (#2) to be worth the embedding job;
|
||||
do not start #3 until #2 has a warped JPEG.
|
||||
|
||||
**Sibling:** `scanner-mobile-checkout` (other worktree / branch) must
|
||||
not edit `lib/ocr-worker.js`, `lib/scan-vision.js`,
|
||||
`lib/card-text-match.js`, `lib/scanner-card-identify.js`,
|
||||
`lib/scanner-card-detection.js`, or `/api/scan/identify`.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
Umbrella is planning-only. Each sub-convoy lists its own roles.
|
||||
Default for #1: Architect → Implementer → audit fan-out (reviewer +
|
||||
security-auditor). UX reviewer on #1 and #2. Skip IA and UI Designer
|
||||
on all three (no new routes or visual language).
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] Pull `scan_attempts` baseline (2026-08-14)
|
||||
- [x] Open worktree `scanner-identify-upgrade` from `main`
|
||||
- [x] Seed sub-convoys #1–#3
|
||||
- [x] Architect: pick up `tighten-scan-identify-hot-path` first
|
||||
- [x] Re-measure `scan_attempts` after all phases ship (2026-08-15 — see below)
|
||||
- [x] Architect: `improve-scan-card-detection`
|
||||
- [x] Architect: `scan-visual-catalog-search` after warped crops exist
|
||||
- [ ] Operator: finish embedding backfill (`npm run backfill-embeddings`) — **14.9%** done (9,865 / 66,211)
|
||||
- [ ] Re-measure after backfill + L0 traffic (`layer = 0` rows)
|
||||
|
||||
## Post-ship telemetry (2026-08-15)
|
||||
|
||||
Pulled from Neon `scan_attempts` + `cards.embedding` coverage. Single user
|
||||
(`user_id = 3`); treat post-ship windows as directional, not statistically
|
||||
significant.
|
||||
|
||||
### All-time (n=250, 2026-05-27 → 2026-08-15)
|
||||
|
||||
| Signal | Value | Baseline (2026-08-14) | Target |
|
||||
| --- | --- | --- | --- |
|
||||
| L1 auto-match | **5.4%** of L1 (6/111) | 5.8% | ≥25% |
|
||||
| L1 escalate | **78.4%** of L1 (87/111) | 76.7% | ≤40% |
|
||||
| L2 `not_a_card` | **43.9%** of L2 (61/139) | 44.6% | ≤15% |
|
||||
| End-to-end auto-match | **13.2%** excl. not_a_card (25/189) | 13.5% | ≥50% |
|
||||
| L1 p50 latency | **158 ms** | 158 ms | — |
|
||||
| L2 p50 / p90 | **1642 / 2297 ms** | 1655 / 2349 ms | ≤1800 p50 |
|
||||
| L0 attempts | **0** | — | (Phase 3 code live; index sparse) |
|
||||
| `card_submissions` pending | **31** | 27 | ops |
|
||||
|
||||
### Aug 15 post-deploy session (n=26)
|
||||
|
||||
First scan burst after #156–#158 merged (~06:23–07:43 UTC). No L0 rows yet
|
||||
(#160 landed same evening; backfill incomplete).
|
||||
|
||||
| Signal | Aug 15 (n=26) | Baseline |
|
||||
| --- | --- | --- |
|
||||
| L1 auto-match | **0%** (0/8 L1) | 5.8% |
|
||||
| L1 escalate | **100%** (8/8 L1) | 76.7% |
|
||||
| L2 `not_a_card` | **38.9%** (7/18 L2) | 44.6% |
|
||||
| End-to-end auto-match | **10.5%** excl. not_a_card (2/19) | 13.5% |
|
||||
|
||||
**Qualitative notes:** L1 OCR strips post-warp are *shorter* garbage (`"7"`,
|
||||
`"Tey"`, `"yr'"`) — collector-number path cannot help. L2 structured JSON
|
||||
(`isCard: false`) works. Two L2 auto-matches (Hunger Hawk, Hog-Monkey).
|
||||
Disambiguation still common (Seel printings).
|
||||
|
||||
### Phase verdict
|
||||
|
||||
| Phase | PR | Code | Success metrics |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 `tighten-scan-identify-hot-path` | #156 | **Shipped** | ❌ L1 match/escalate targets missed |
|
||||
| 2 `improve-scan-card-detection` | #158 | **Shipped** | ❌ not_a_card still ~44%; slight Aug 15 improvement |
|
||||
| 3 `scan-visual-catalog-search` | #160, #162 | **Shipped** | ⏳ Awaiting backfill + L0 traffic |
|
||||
|
||||
**Recommendation:** Finish catalog embedding backfill, scan 50+ cards on
|
||||
preview, then re-query `layer = 0` distribution before tuning thresholds.
|
||||
|
||||
### Embedding backfill status (2026-08-15)
|
||||
|
||||
| Metric | Value |
|
||||
| --- | --- |
|
||||
| Cards with `image_url` | 66,211 |
|
||||
| Rows with `embedding` | 9,865 (**14.9%**) |
|
||||
| pgvector on Neon | ✅ v0.8.0 |
|
||||
| Operator command | `npm run backfill-embeddings` |
|
||||
|
||||
## Worktree
|
||||
|
||||
| Checkout | Branch | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `tcg-vault-worktrees/scanner-identify-upgrade` | `convoy/scanner-identify-upgrade` | These convoy docs |
|
||||
| (later) Agents Window worktree per brief | `brief/scanner-identify-upgrade/<n>-<title>` | Implementer slices |
|
||||
|
||||
`scripts/wt.sh` is a deprecation stub. Create implementer worktrees from
|
||||
the Agents Window after Architect writes `slice_dependencies:`.
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
No implementer fan-out from this umbrella. After #1 Architect marks
|
||||
parallel-safe briefs (`depends_on: []` + disjoint `files:`):
|
||||
|
||||
```
|
||||
/multitask role-implementer briefs <ids>
|
||||
```
|
||||
|
||||
After each PR draft:
|
||||
|
||||
```
|
||||
/multitask role-reviewer + role-security-auditor
|
||||
```
|
||||
|
||||
Add design-system + a11y auditors only if the PR touches
|
||||
`components/` or `pages/scanner.js` (not expected in #1).
|
||||
|
||||
Group ids: `audit-tighten-scan-identify-hot-path-<pr>`,
|
||||
`audit-improve-scan-card-detection-<pr>`,
|
||||
`audit-scan-visual-catalog-search-<pr>`.
|
||||
|
|
@ -1,644 +0,0 @@
|
|||
---
|
||||
name: scanner-mobile-checkout
|
||||
classification: feature
|
||||
success_metric: |
|
||||
On a phone, opening /scanner goes straight into a full-bleed camera;
|
||||
each successful identify lands in a local cart (not the database);
|
||||
the user can open a checkout sheet, select cards, and commit them
|
||||
to My Collection or a List without leaving the session.
|
||||
skip: []
|
||||
status: shipped
|
||||
created: 2026-08-14
|
||||
depends_on:
|
||||
- scanner-rebuild
|
||||
- redesign-scanner-flow
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
design_direction:
|
||||
source: role-ui-designer
|
||||
skill: ui-ux-pro-max
|
||||
skill_version: "2.5.0"
|
||||
version: 1
|
||||
locked_at: 2026-08-14
|
||||
product_type: mobile camera scanner checkout cart trading cards glassmorphism
|
||||
pattern: Immersive camera overlay + bottom-sheet checkout
|
||||
style: Liquid Glass (repo canonical)
|
||||
stack: nextjs
|
||||
layout_reference: image-93781104-69e3-4f0b-b25f-df7c750ef046.png
|
||||
---
|
||||
|
||||
# Convoy: scanner-mobile-checkout
|
||||
|
||||
Turn the scanner into a mobile checkout: scan everything first, then
|
||||
commit the cart. Layout reference is the last attached mock (full-bleed
|
||||
camera, glass overlays, review as a bottom sheet).
|
||||
|
||||
## Why
|
||||
|
||||
The overnight `scanner-rebuild` got us a three-phase machine (Setup →
|
||||
Scanning → Review), but the phone experience is still chrome-heavy:
|
||||
Layout's sidebar, top search bar, and bottom nav compete with the
|
||||
viewfinder; a destination form blocks the camera; and `handleCardScanned`
|
||||
writes each match to the database immediately (rebuild D3). That fights
|
||||
the actual table-scan job — hold the phone, sweep cards, then check out
|
||||
once.
|
||||
|
||||
Users want supermarket-checkout semantics: open scanner → scan all the
|
||||
things → open the cart → add selected cards to My Collection or a List
|
||||
→ leave. No per-card "Add" tap. No setup screen in the way.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- **Immersive scan chrome (mobile).** Hide Layout sidebar, TopSearchBar,
|
||||
and MobileNavigation while the camera is live. Camera is full-bleed.
|
||||
Overlay only: back, title, optional gallery, detection brackets +
|
||||
status around the tracked card, bottom glass bar (flash, scan status,
|
||||
Review N).
|
||||
- **Cart, not auto-route.** Successful identifies enqueue locally.
|
||||
Nothing POSTs to `user_cards` / collections / decks until checkout.
|
||||
Reverse rebuild D3 for this flow.
|
||||
- **Scan peek.** After a match, a compact non-interactive preview slides
|
||||
up briefly (name + thumbnail + confidence) and auto-dismisses. Tapping
|
||||
it opens the cart. No condition / foil / Add buttons on the peek.
|
||||
- **Checkout sheet.** Bottom sheet over the still-live (but paused)
|
||||
camera. List of cart items with selection, qty, confidence, overflow
|
||||
menu (remove / condition / foil). Primary: add selected to My
|
||||
Collection. Secondary: add selected to a List (picker). Copy from
|
||||
`lib/collection-vocabulary.js` — never "binder" as a button label
|
||||
(mock says "Save to binder"; product vocab is List).
|
||||
- **Camera swap.** Front / rear toggle in the bottom bar. Flash stays
|
||||
rear-only and hides when `torch` is unsupported (iOS Safari).
|
||||
- **Desktop.** Same cart semantics. At `md+`, cart can be a persistent
|
||||
side panel instead of a sheet; do not hide the desktop sidebar.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Identify / OCR / Gemini pipeline (`lib/scanner-card-identify.js`,
|
||||
`pages/api/scan/identify.js`, OpenCV detection). Layer UI on the
|
||||
existing hooks.
|
||||
- Schema / new tables. Cart is client-side session state.
|
||||
- Deck Mode, game pre-filter, scan-history list on the setup screen
|
||||
(rebuild Setup). Revisit as a later convoy if needed.
|
||||
- Estimated total value row from the mock, unless identify payloads
|
||||
already include `market_price` with no extra fetch.
|
||||
- Deleting leftover `components/CameraScanner.js` /
|
||||
`ScannerPageView.js` (pre-rebuild). Separate cleanup.
|
||||
- Changing desktop visual-diff homepage baseline except as a
|
||||
side-effect of Layout's new immersive prop.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-ia-architect` — scan → peek → cart → commit flow; where
|
||||
destination choice lives now that Setup is gone.
|
||||
2. `role-ui-designer` — lock the mobile overlay + checkout sheet against
|
||||
the last mock, using Liquid Glass tokens (ui-ux-pro-max is installed).
|
||||
3. `role-ux-reviewer` — cart selection, low-confidence handling, back
|
||||
with unsaved cart, pause-vs-kill camera under the sheet.
|
||||
4. `role-architect` — briefs. Likely: (1) Layout immersive + camera
|
||||
chrome, (2) stop auto-route + cart model, (3) checkout sheet +
|
||||
destinations. `slice_dependencies` must mark what can run in parallel.
|
||||
5. `role-implementer` — per brief.
|
||||
6. Audit fan-out: reviewer + security-auditor + design-system-auditor +
|
||||
a11y-auditor.
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] IA: route/flow/screen inventory for immersive scan + checkout sheet
|
||||
- [x] UI Designer: lock overlay recipe (tokens, not hex) from last mock
|
||||
- [x] UX: cart selection, low-confidence, back-guard, camera pause
|
||||
- [x] Architect: briefs + whether Layout gets `chrome="immersive"`
|
||||
- [ ] Stop auto-route in `use-scanner-queue.js`; scans stay `processed: false` until checkout
|
||||
- [ ] Full-bleed camera; hide app chrome on small viewports
|
||||
- [ ] Bottom bar: flash, status, Review N; add facingMode swap
|
||||
- [ ] Non-interactive scan peek; checkout sheet with bulk + per-card commit
|
||||
- [ ] Pause identification while the sheet is open (`verificationPausedRef`)
|
||||
- [ ] Tests for cart enqueue (no network) and checkout commit paths
|
||||
- [ ] Visual-diff: scanner surfaces + Layout immersive; refresh baselines if chrome changes
|
||||
|
||||
## Predecessor
|
||||
|
||||
`scanner-rebuild` (2026-06-13, overnight) shipped the phase machine,
|
||||
flash hook, toasts, count pill, and review list. This convoy keeps those
|
||||
hooks and **replaces the UX contract**: skip Setup, immersive camera,
|
||||
cart-then-commit instead of auto-route.
|
||||
|
||||
## Conductor notes (build shape)
|
||||
|
||||
Likely file ownership for Architect to refine:
|
||||
|
||||
| Area | Files |
|
||||
| --- | --- |
|
||||
| Immersive shell | `pages/scanner.js`, `components/Layout.js`, `components/MobileNavigation.js` |
|
||||
| Camera chrome | `components/scanner/ScannerCamera.js`, `lib/use-camera-scanner.js`, `lib/use-scanner-flash.js` |
|
||||
| Cart model | `lib/use-scanner-queue.js`, `lib/scanner-session.js` |
|
||||
| Peek + sheet | new `ScannerScanPeek.js`, rewrite `ScannerReview.js` as a sheet; reuse `ScannerDisambiguation.js` |
|
||||
| Copy | `lib/collection-vocabulary.js` (`ADD_TO_MY_COLLECTION`, `ADD_TO_LIST`) |
|
||||
|
||||
Do not rewrite identification. `handleCardScanned` should enqueue only.
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
Planning is serial: IA → UI Designer → UX → Architect.
|
||||
|
||||
After architect: implementer fan-out only if briefs have `depends_on: []`
|
||||
and disjoint `files:`. Cart-model (stop auto-route) likely blocks the
|
||||
checkout sheet; immersive Layout may be parallel with cart-model if
|
||||
they do not both own `pages/scanner.js`.
|
||||
|
||||
After PR draft: `/multitask` audit fan-out
|
||||
`role-reviewer + role-security-auditor + role-design-system-auditor + role-a11y-auditor`
|
||||
(group id: `audit-scanner-mobile-checkout-<pr>`).
|
||||
|
||||
## IA
|
||||
|
||||
### Affected routes
|
||||
|
||||
- `[modified]` `/scanner` — sole scanner surface. Entry skips Setup and lands on full-bleed camera; cart and checkout live as in-page overlays/sheets on this route (no new URLs). Phase machine collapses from setup → scanning → review into scanning-first with optional cart sheet open/closed.
|
||||
- `[impacted]` `/login` — unauthenticated `/scanner` visits still redirect here (unchanged gate in `pages/scanner.js`). Post-login return target is TBD (see open questions).
|
||||
- `[impacted]` `/dashboard`, Layout sidebar, command palette — entry links to `/scanner` unchanged; users now arrive directly in camera instead of Setup.
|
||||
- `[impacted]` `/my-cards`, `/collections` — not part of the scan flow, but natural post-checkout destinations if the user navigates away after commit. No route or nav changes required.
|
||||
|
||||
No `[new]` routes. Destination choice (My Collection vs List) moves from pre-scan Setup into the checkout sheet on `/scanner` only — **no route changes**.
|
||||
|
||||
### User flow
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Open /scanner"] --> B["Live camera"]
|
||||
B --> C["Card identified"]
|
||||
C --> D["Scan peek"]
|
||||
D --> B
|
||||
B --> E["Review N"]
|
||||
E --> F["Checkout sheet"]
|
||||
F --> G["Add to My Collection / List"]
|
||||
G --> H["Exit scanner"]
|
||||
```
|
||||
|
||||
### Screen inventory
|
||||
|
||||
| Screen | Path | New/modified | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Scanner — live camera | `/scanner` | modified | Default view on open (mobile: immersive, no Layout chrome). Bottom glass bar: flash, status, camera swap, Review N. Detection brackets + status around tracked card. |
|
||||
| Scan peek | `/scanner` (overlay) | new | Brief non-interactive slide-up after identify (name, thumbnail, confidence). Auto-dismiss; tap opens checkout sheet. No per-card Add / condition / foil on peek. |
|
||||
| Checkout cart sheet | `/scanner` (overlay) | modified | Replaces full-page `ScannerReview` as primary cart UI on mobile. Camera stays mounted but paused under sheet. Selection, qty, confidence, overflow (remove / condition / foil). Primary: Add to My Collection; secondary: Add to List (picker). |
|
||||
| Disambiguation sheet | `/scanner` (overlay) | impacted | Existing `ScannerDisambiguation` stays in overlay stack above camera; blocks identify until resolved, then card enqueues to cart. |
|
||||
| Scanner Setup | `/scanner` (phase) | impacted | Removed from default entry path (out of scope to delete component). Game filter, deck mode, pre-scan destination, and scan history no longer gate camera start. |
|
||||
| Auth loading | `/scanner` | impacted | Spinner while `useAuth` resolves; immersive chrome applies once authenticated (see open question on loading shell). |
|
||||
|
||||
Desktop (`md+`): same `/scanner` route; cart may render as persistent side panel instead of sheet; Layout sidebar remains visible.
|
||||
|
||||
### Content / data model deltas
|
||||
|
||||
- **Copy (write / wire):** checkout CTAs from `lib/collection-vocabulary.js` — `ADD_TO_MY_COLLECTION`, `ADD_TO_LIST` / `ADD_TO_LISTS`; bottom-bar "Review N" (N = cart count); flash and camera-swap `aria-label`s; empty-cart and commit-success toasts. Never use "binder" or "Save to binder" as a button label.
|
||||
- **Copy (retire from entry path):** Setup destination picker, game pre-filter, deck-mode selector, and scan-history list as pre-scan gate copy (component may remain for later convoy).
|
||||
- **Client session state:** cart is in-memory queue on `/scanner` — cards stay `processed: false` until checkout commit. Reverses rebuild D3 auto-route; no persistence across refresh or navigation away.
|
||||
- **API calls (commit-time only, unchanged endpoints):** `POST /api/user-cards` (My Collection), `POST /api/collections/:id/cards` (List), existing `GET /api/collections` + `GET /api/decks` for destination lists. Optional `GET` batch-ownership during cart review. No schema / table changes.
|
||||
- **Immersive Layout:** new chrome mode (likely `chrome="immersive"` on `Layout`) affects how `/scanner` composes global nav — content delta only on this page, not a new route.
|
||||
|
||||
### Open IA questions
|
||||
|
||||
1. **Post-checkout exit:** Product intent says "then exit" — does the user return to the prior page (`router.back()`), land on `/my-cards` or `/collections`, or stay on `/scanner` with an empty cart and live camera?
|
||||
2. **Post-login deep link:** If an unauthenticated user hits `/scanner`, should login return them to `/scanner` (camera) or a safer default (`/dashboard`)?
|
||||
3. **Desktop Setup:** Is Setup skipped on `md+` as well, or only on mobile viewports?
|
||||
4. **Deck destination:** Deck mode and add-to-deck are out of scope — confirm deck is fully absent from checkout destinations (not just hidden behind Setup).
|
||||
5. **Gallery import:** Convoy mentions "optional gallery" in the top overlay — is this in-scope as a file-picker overlay on `/scanner`, or deferred?
|
||||
6. **Partial commit:** After adding a subset to My Collection / a List, does the user remain in the sheet with remaining items, or does any successful commit close the session?
|
||||
|
||||
## Decisions (post-IA)
|
||||
|
||||
Locked 2026-08-14 from product intent (parent session). UX / UI / Architect treat these as settled.
|
||||
|
||||
| # | Decision |
|
||||
| --- | --- |
|
||||
| D1 | **Stay on camera after commit.** Successful checkout removes committed rows from the cart. If the cart is empty, close the sheet and resume scanning. Back (header) is the only exit from `/scanner`. |
|
||||
| D2 | **Login returns to `/scanner`.** Keep the existing auth gate; after login, send the user back to the camera, not `/dashboard`. |
|
||||
| D3 | **Skip Setup on all viewports.** Desktop uses the same scanning-first entry; cart is a side panel at `md+`, not a return of the Setup form. |
|
||||
| D4 | **No deck destination in checkout.** My Collection and List only. Deck Mode stays out of this convoy. |
|
||||
| D5 | **Gallery is in-scope.** Top-right control opens a file picker; chosen image goes through the existing identify path and lands in the cart like a live scan. |
|
||||
| D6 | **Partial commit stays in the sheet.** Uncommitted rows remain. Sheet closes only when the cart is empty or the user dismisses it. |
|
||||
| D7 | **Persist cart in `sessionStorage`.** Survive refresh within the tab; do not persist across browser sessions. |
|
||||
|
||||
## Design direction
|
||||
|
||||
Locked v1 — 2026-08-14. Layout authority: last mock
|
||||
(`image-93781104-69e3-4f0b-b25f-df7c750ef046.png`). Generator query:
|
||||
*"mobile camera scanner checkout cart trading cards glassmorphism"*.
|
||||
|
||||
### Summary
|
||||
|
||||
Deck Hearth's mobile scanner should feel like a **supermarket checkout lane
|
||||
over a live viewfinder**: full-bleed camera, ember-bracketed detection,
|
||||
glass overlays that float above card art, a brief non-interactive peek after
|
||||
each match, and a bottom-sheet cart for bulk commit. Warm ember/flame accents
|
||||
cast light onto glass — never fill entire panels with brand orange.
|
||||
|
||||
### Pattern + style
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Product type | Mobile TCG collection scanner with session cart + checkout |
|
||||
| App pattern | **Immersive camera overlay + bottom-sheet checkout** (generator's "Bento Grid Showcase" rejected — marketing grid, not camera UX) |
|
||||
| UI style | **Liquid Glass** — repo canonical (`docs/DESIGN_TOKENS.md`). Generator's "Exaggerated Minimalism" / oversized typography rejected. |
|
||||
| Stack notes | Next.js Pages router, React 18, Tailwind + CSS variables. Next.js stack query returned 0 rows — follow existing scanner components + `components/ui/` primitives. |
|
||||
| Desktop (`md+`) | Same cart semantics; cart as persistent side panel; Layout sidebar stays visible. Immersive chrome is mobile-only. |
|
||||
|
||||
### Screen 1 — Live camera (mobile default)
|
||||
|
||||
Full-bleed `<video>` under all chrome. Layout sidebar, TopSearchBar, and
|
||||
MobileNavigation hidden via `chrome="immersive"` on `/scanner`.
|
||||
|
||||
| Zone | Composition | Tokens / notes |
|
||||
| --- | --- | --- |
|
||||
| **Top bar** | Back (←), title "Scan Cards", gallery (file picker, D5) | `--glass-surface-mid` + `blur(--glass-blur-mid)` + rim stack. Safe-area inset top. 44×44 tap targets. |
|
||||
| **Viewfinder brackets** | Four L-shaped corner brackets framing tracked card | Stroke `--accent-flame` / `--accent-ember`; no filled box. Animated scan line: horizontal ember gradient sweep (`--gradient-primary-*`), respect `prefers-reduced-motion`. |
|
||||
| **Scan status** | Centered label below brackets ("Scanning… Hold steady") | `--text-primary` on semi-opaque pill or direct over darkened letterbox — ensure 4.5:1. |
|
||||
| **Success toast** | Glass pill: check + "{Card name} added" + dismiss × | `--glass-surface-high` + rim; green check via success token (not emoji). Auto-dismiss ~2s. `role="status"`. |
|
||||
| **Scan peek** | Compact slide-up after identify (name, thumb, confidence ring) | `--glass-surface-mid`; **non-interactive** except tap-to-open-sheet. No Add / condition / foil controls. Auto-dismiss ~3s. |
|
||||
| **Bottom bar** | Three zones: Flash \| status \| **Review N** pill | Bar: `--glass-surface-mid` + blur mid + `--elevation-ambient`. Flash + camera-swap icons (rear-only torch; hide flash when unsupported). **Review N**: gradient pill `background: var(--gradient-primary-*)` + `--ember-rim-pronounced`; label `Review {N}` with chevron. Min 44px height. |
|
||||
|
||||
Camera overlays **may** use `backdrop-filter` (exception to per-card grid
|
||||
rule — overlays sit above the viewfinder, not on grid items).
|
||||
|
||||
### Screen 2 — Checkout sheet (mobile)
|
||||
|
||||
Bottom sheet over **paused** (not unmounted) camera. Scrim + sheet follow
|
||||
Modal primitive recipes.
|
||||
|
||||
| Zone | Composition | Tokens / notes |
|
||||
| --- | --- | --- |
|
||||
| **Scrim** | Dim live camera | `--modal-scrim` + `blur(--glass-blur-high)` |
|
||||
| **Sheet panel** | Rounded top (~16px), grab handle, scrollable list, sticky footer | Panel: `--glass-surface-low` inside scrim + blur mid + `--elevation-pronounced`. Handle: 36×4px `--border` pill, centered. |
|
||||
| **Header** | "{N} cards scanned" + low-confidence subline (orange dot) + Edit | Subline only when any row < threshold. Edit toggles bulk-select mode (UX brief). |
|
||||
| **Cart rows** | Checkbox, thumb, name/set/rarity, confidence ring, qty stepper (− N +), overflow ⋮ | Row surface: `--glass-surface-high` or solid `--bg-secondary` inner panel over sheet (legibility over busy thumbs). Confidence ring: green ≥85%, amber 70–84%, orange <70% using `--accent-ember` / success tokens — not hardcoded hex. |
|
||||
| **Row overflow** | Remove, condition, foil | Popover: `--glass-surface-high` recipe. |
|
||||
| **Footer CTAs** | Primary gradient + secondary text button | Primary: `VOCAB.ADD_TO_MY_COLLECTION` — full-width gradient button (`var(--gradient-primary-*)`, `--ember-rim-pronounced`). Secondary: `VOCAB.ADD_TO_LIST` — ghost / link style with list icon; opens picker. **Never** "Save to binder" / "Add all to collection" without vocab import. |
|
||||
| **Out of scope row** | "Total value (est.)" from mock | Omit unless identify payload already includes `market_price` (convoy scope). |
|
||||
|
||||
Partial commit (D6): committed rows leave the list; sheet stays open until
|
||||
cart empty or user dismisses. Empty cart → close sheet, resume scanning (D1).
|
||||
|
||||
### Colors
|
||||
|
||||
**Repo tokens win.** Generator palette (slate `#1E293B`, scan-blue `#2563EB`)
|
||||
is **not adopted**.
|
||||
|
||||
| Role | Token | Usage in this flow |
|
||||
| --- | --- | --- |
|
||||
| Primary accent | `--accent-ember` | Brackets, focus rings, low-confidence warnings, primary CTA gradient stop |
|
||||
| Secondary accent | `--accent-flame` | Scan line, gradient stops, Review N pill |
|
||||
| Gold (rare) | `--accent-gold` | Rarity badges only |
|
||||
| Glass fills | `--glass-surface-{low,mid,high}` | Sheet panel / top+bottom bars / toast / peek |
|
||||
| Blur | `--glass-blur-{low,mid,high}`, `--glass-saturate` | All glass overlays |
|
||||
| Rims | `--rim-light-{inner,outer}`, `--ember-rim-{subtle,pronounced}` | Interactive pills and primary buttons get pronounced ember rim |
|
||||
| Scrim | `--modal-scrim` | Sheet backdrop |
|
||||
| Text | `--text-primary`, `--text-secondary` | All copy on glass |
|
||||
| Background | `--bg-primary`, `--bg-secondary` | Row inner panels when glass-over-art fails contrast |
|
||||
|
||||
No hex in `.js` files. Use `var(--token)` or existing utility classes
|
||||
(`.glass-panel`, gradient vars in `globals.css`).
|
||||
|
||||
### Typography
|
||||
|
||||
| Role | Font | Notes |
|
||||
| --- | --- | --- |
|
||||
| Display / title | System / Inter (existing) | Top bar "Scan Cards" — `font-semibold`, ~17px. No generator "clamp(3rem…)" oversized type. |
|
||||
| Body | System / Inter | Row names `font-medium`; set/rarity `text-sm` `--text-secondary` |
|
||||
| CTA | System / Inter | Primary button `font-semibold`; secondary `font-medium` |
|
||||
|
||||
### Effects + motion
|
||||
|
||||
| Effect | Spec |
|
||||
| --- | --- |
|
||||
| Transitions | 150–300ms ease on toast, peek slide, sheet open/close |
|
||||
| Scan line | Looping horizontal sweep over brackets; disable loop when `prefers-reduced-motion: reduce` |
|
||||
| Sheet | Slide up from bottom; scrim fade in. Focus trap while open. |
|
||||
| Hover / focus | Primary controls: `--ember-rim-pronounced` on focus-visible; `cursor-pointer` on all clickables |
|
||||
| Bracket pulse | Subtle ember glow on active track — `--ember-rim-subtle`, not full-panel fill |
|
||||
|
||||
See `docs/MOTION_SYSTEM.md` for shared motion taxonomy when implementing.
|
||||
|
||||
### Copy (mandatory)
|
||||
|
||||
Import from `lib/collection-vocabulary.js`:
|
||||
|
||||
| UI surface | Constant |
|
||||
| --- | --- |
|
||||
| Primary checkout | `VOCAB.ADD_TO_MY_COLLECTION` |
|
||||
| Secondary checkout | `VOCAB.ADD_TO_LIST` |
|
||||
| Bottom bar | `Review {N}` (N = cart count) |
|
||||
| Toast | `{Card name} added` (success) |
|
||||
|
||||
Retired: "Save to binder", "Mark Owned", "Add all to collection" (use vocab
|
||||
or "Add selected to My Collection" when subset selected).
|
||||
|
||||
### Anti-patterns (do not ship)
|
||||
|
||||
- Generator's light slate background + blue CTA palette on scanner chrome
|
||||
- Opaque drawer replacing bottom sheet (see deprecated mock
|
||||
`image-be4e787b-…` — too many actions on peek)
|
||||
- Per-card Add / condition / foil on scan peek
|
||||
- `backdrop-filter` on cart **thumbnail grid items** (card grid perf budget)
|
||||
- Hardcoded hex in JSX; `--accent-blue` / `--accent-purple` legacy aliases
|
||||
- Emoji icons (toast check must be SVG or existing glyph pattern)
|
||||
- Filling overlay panels with solid ember orange (brand is rim/glow/gradient only)
|
||||
- Desktop dual-theme mock layout (`image-6654f196-…`) as mobile reference
|
||||
|
||||
### Pre-delivery checklist
|
||||
|
||||
- [ ] No emojis as icons (SVG: Lucide / Heroicons)
|
||||
- [ ] `cursor-pointer` on clickable elements
|
||||
- [ ] Hover/focus transitions 150–300ms
|
||||
- [ ] Text contrast ≥ 4.5:1 on all glass copy (use inner opaque panel if over card art)
|
||||
- [ ] Keyboard focus visible (`--accent-ember` ring)
|
||||
- [ ] `prefers-reduced-motion` respected (scan line, peek, sheet)
|
||||
- [ ] Responsive: 375 (immersive mobile), 768, 1024 (side panel), 1440
|
||||
- [ ] Flash hidden when `torch` unsupported; camera-swap `aria-label`s
|
||||
- [ ] Checkout copy from `collection-vocabulary.js` only
|
||||
|
||||
### Token overrides vs generator
|
||||
|
||||
| Generator output | Locked override |
|
||||
| --- | --- |
|
||||
| Pattern: Bento Grid Showcase | Immersive camera + bottom-sheet checkout |
|
||||
| Style: Exaggerated Minimalism | Liquid Glass (shipped) |
|
||||
| Primary `#1E293B`, accent `#2563EB` | `--accent-ember`, `--accent-flame`, `--gradient-primary-*` |
|
||||
| Background `#F8FAFC` | Full-bleed camera; glass overlays use `--glass-surface-*` |
|
||||
| Typography: massive display type | Existing body scale; scanner chrome stays compact |
|
||||
| Key effects: 10vw headings | Scan-line animation + sheet slide only |
|
||||
|
||||
### Conflict rule
|
||||
|
||||
**Repo design tokens win** when they disagree with generator output. This
|
||||
lock intentionally overrides ui-ux-pro-max palette/pattern for every
|
||||
scanner surface. File a convoy note + bump `design_direction.version` only
|
||||
if product approves a token change.
|
||||
|
||||
## UX
|
||||
|
||||
### Existing components to reuse
|
||||
|
||||
- `<GlassSurface>` (`components/ui/GlassSurface.js`) — top bar, bottom bar, scan peek, checkout sheet panel, row inner panels. Use `tint="mid"` for chrome bars, `tint="low"` for sheet body, `rim="ember-pronounced"` on Review N pill and primary CTA.
|
||||
- `<Modal>` (`components/ui/Modal.js`) — back-guard confirm ("Leave scanner?"), List picker (`size="md"`), nested above checkout sheet z-index stack. Do **not** roll a custom scrim for these dialogs.
|
||||
- `<Button>` (`components/ui/Button.js`) — footer primary (`variant="primary"`, `loading` during commit) and secondary (`variant="ghost"`) CTAs; back-guard actions.
|
||||
- `<Input>` (`components/ui/Input.js`) — optional filter field inside List picker when `collections.length > 8`.
|
||||
- `<ScannerDisambiguation>` (`components/scanner/ScannerDisambiguation.js`) — **canonical bottom-sheet shell** for checkout cart on mobile: same `fixed inset-0` scrim, `glass-panel-strong` panel, drag handle, `useFocusTrap`, Escape-to-dismiss. Checkout sheet copies this shell; do not invent a second sheet primitive.
|
||||
- `<ScannerToast>` (`components/scanner/ScannerToast.js`) — success feedback after identify (`role="status"`, `aria-live="polite"`). Replace emoji glyphs with SVG check per design-direction checklist; message shape: `{Card name} added`.
|
||||
- `<ScannerCountPill>` (`components/scanner/ScannerCountPill.js`) — evolve into bottom-bar **Review N** gradient pill (same `onReview` contract, `aria-label={`Review ${count} scanned cards`}`); retire the separate count row above the viewport.
|
||||
- `<ReviewCardItem>` (`components/scanner/ReviewCardItem.js`) — cart row body: thumbnail, name/set, qty stepper, condition/foil overflow. Extend with leading checkbox + confidence ring; drop inline destination picker (destinations move to footer CTAs only).
|
||||
- `<ScannerCamera>` (`components/scanner/ScannerCamera.js`) — viewfinder, bracket overlays, flash hook wiring, disambiguation mount point. Refactor chrome into top/bottom glass bars; keep `verificationPausedRef` plumbing.
|
||||
- `<Layout>` (`components/Layout.js`) — `chrome="immersive"` on `/scanner` for `<md` only; desktop keeps sidebar.
|
||||
- `useFocusTrap` / `useFocusTrapContainer` (`lib/use-focus-trap.js`) — every overlay sheet and confirm dialog; restore focus to Review N pill or back button on close.
|
||||
|
||||
**8 primitives** (+ 2 hooks, 1 page shell). New file `ScannerScanPeek.js` is the only net-new overlay component; it composes `<GlassSurface>` only.
|
||||
|
||||
### Design direction alignment
|
||||
|
||||
Locked `design_direction` maps directly to repo tokens — no conflicts deferred:
|
||||
|
||||
| Design-direction surface | Token / primitive |
|
||||
| --- | --- |
|
||||
| Top + bottom chrome bars | `--glass-surface-mid`, `--glass-blur-mid`, `--rim-light-*`, safe-area insets |
|
||||
| Ember brackets + scan line | `--accent-flame`, `--accent-ember`, `--gradient-primary-*`; scan-line loop disabled under `prefers-reduced-motion` |
|
||||
| Review N pill | `var(--gradient-primary-*)` + `--ember-rim-pronounced` on `<Button>` or styled `<GlassSurface as="button">` |
|
||||
| Checkout sheet scrim | `--modal-scrim` + `blur(--glass-blur-high)` — same recipe as `<Modal>` backdrop |
|
||||
| Confidence rings | green ≥85%, amber 70–84%, orange <70% via `--color-success` / `--accent-ember` tokens (not hex literals) |
|
||||
| Footer CTAs | `VOCAB.ADD_TO_MY_COLLECTION`, `VOCAB.ADD_TO_LIST` from `lib/collection-vocabulary.js` |
|
||||
| Peek + toast | `--glass-surface-mid` / `--glass-surface-high`; SVG icons only |
|
||||
|
||||
**UX override of design-direction "Edit toggles bulk-select mode":** reject Edit mode. Checkboxes are **always visible** with all rows selected by default — supermarket checkout does not hide selection behind a mode switch (Nielsen H6).
|
||||
|
||||
### Existing patterns to follow
|
||||
|
||||
- **Bottom-sheet overlay stack** — `ScannerDisambiguation.js` (scrim click dismisses only when safe; focus trap; `aria-labelledby`). Checkout sheet sits at `z-40`; disambiguation stays at `z-50` above it.
|
||||
- **Cart row editing** — `ReviewCardItem.js` qty stepper + condition select pattern; overflow ⋮ menu mirrors row remove button placement.
|
||||
- **Bulk selection semantics** — `useScannerQueue` `selectedCards` Set + `toggleCardSelection` / `handleBulkAction`; do not fork a parallel selection model.
|
||||
- **Pause identification** — `CameraScanner.js` + `pages/scanner.js` `verificationPausedRef` pattern: `useCameraScanner` early-returns when `verificationPausedRef.current === true`; `useScannerIdentification` already sets it during disambiguation — extend to checkout sheet + List picker open.
|
||||
- **Flash gating** — `useScannerFlash.js` `flashSupported` probe; conditionally render flash button (already in `ScannerCamera.js` L221–242). Flash is **rear camera only** — hide when `facingMode === 'user'`.
|
||||
- **Immersive page shell** — follow `components/ProtectedRoute.js` / `pages/scanner.js` auth gate; post-login return to `/scanner` (D2) via `router.query.returnUrl` or equivalent login redirect — do not invent a new auth wrapper.
|
||||
- **List display names** — `collectionDisplayName()` for picker rows; never render `'All My Cards'` literal.
|
||||
- **Motion** — `docs/MOTION_SYSTEM.md` duration tokens: peek/toast `quick` (150ms), sheet `slow` (400ms); sitewide `prefers-reduced-motion` collapse applies.
|
||||
- **Rules** — `.cursor/rules/ui-and-theming.mdc` (Modal primitive mandate, 44px targets, focus rings via `--accent-ember`).
|
||||
|
||||
### A11y constraints
|
||||
|
||||
Hand to `role-a11y-auditor`:
|
||||
|
||||
1. **WCAG 2.5.5 Target Size (AAA goal):** every tappable chrome control (back, gallery, flash, camera swap, Review N, peek tap target, row checkbox, qty ±, overflow ⋮, footer CTAs) ≥ 44×44 CSS px — use invisible padding if icon is smaller.
|
||||
2. **WCAG 1.4.3 Contrast (AA):** all text on glass ≥ 4.5:1; if card-art bleeds through a row thumb, use `--bg-secondary` inner panel behind text (design-direction row spec).
|
||||
3. **WCAG 2.4.3 Focus Order:** checkout sheet opens → focus moves to sheet panel (first focusable: header close/dismiss or first row checkbox via `useFocusTrap`); on close → restore to Review N pill.
|
||||
4. **WCAG 2.1.1 Keyboard:** sheet dismiss via Escape; peek opens sheet on Enter/Space when focused; back button triggers confirm modal before navigation.
|
||||
5. **WCAG 4.1.2 Name, Role, Value:** checkout sheet `role="dialog"` `aria-modal="true"` `aria-labelledby` → "{N} cards scanned"; List picker nested dialog gets its own label ("Choose a List").
|
||||
6. **`aria-label` required:** back → "Leave scanner"; gallery → "Choose image from gallery"; flash → "Turn on flash" / "Turn off flash" + `aria-pressed`; camera swap → "Switch to front camera" / "Switch to rear camera"; Review N → `Review ${N} scanned cards`; row checkbox → `Select ${card.name}`; qty buttons → `Decrease quantity for ${card.name}` / `Increase…`; overflow → `More actions for ${card.name}`.
|
||||
7. **WCAG 1.1.1 Non-text Content:** card thumbs `alt={card.name}`; decorative bracket corners `aria-hidden="true"`.
|
||||
8. **WCAG 4.1.3 Status Messages:** identify success toast + post-commit success toast use `role="status"` `aria-live="polite"`; do not steal focus.
|
||||
9. **WCAG 2.3.3 Animation from Interactions:** scan-line loop, peek slide, sheet slide respect `prefers-reduced-motion: reduce` (instant show/hide, no sweep).
|
||||
10. **Focus trap:** checkout sheet, disambiguation sheet, back-guard confirm, List picker — all trap Tab; disambiguation above checkout maintains trap when both mounted.
|
||||
11. **Confidence communicated without color alone:** ring color + text label on row (`aria-label` includes "confidence 62 percent") and header subline "{N} need review" when any row < 70%.
|
||||
12. **Gallery file input:** visually hidden `<input type="file" accept="image/*">` triggered by labeled button; `aria-label` on button, not bare input.
|
||||
13. **Disabled primary CTA:** when zero rows selected, `Add to My Collection` is `disabled` + `aria-disabled="true"` with visible helper "Select at least one card" (linked via `aria-describedby`).
|
||||
14. **Screen reader pause announcement:** when sheet opens, `aria-hidden="true"` on camera video element OR `inert` on viewfinder chrome beneath scrim so SR does not read live camera controls under the sheet.
|
||||
|
||||
### Interaction patterns
|
||||
|
||||
| Pattern | Spec | Nielsen |
|
||||
| --- | --- | --- |
|
||||
| **Cart selection — default all selected** *(required)* | On first sheet open, `selectedCards` = all unprocessed row IDs. New card enqueued while sheet open → auto-add its ID to selection. Deselecting is per-row checkbox. Primary CTA label stays `VOCAB.ADD_TO_MY_COLLECTION`; when subset selected, append count: "Add to My Collection (3)". No "Edit mode" toggle. | H6 Recognition rather than recall |
|
||||
| **Low-confidence vs disambiguation** *(required)* | **Pipeline `disambiguation` outcome → always block** via existing `ScannerDisambiguation` sheet; never enqueue until user picks. **Single-match `emit` outcome → enqueue silently** to cart regardless of confidence; surface confidence visually (ring + header subline for any row <70%). Do not re-prompt at scan time for low-confidence singles — checkout is the verification gate. | H5 Error prevention; H3 User control |
|
||||
| **Scan peek** *(required)* | Slide-up 3s auto-dismiss. Container `pointer-events-none`; single child button wrapper `pointer-events-auto` with `aria-label="Open cart to review {card name}"`. No condition/foil/Add on peek. Tap opens checkout sheet. | H4 Consistency; H8 Minimalist design |
|
||||
| **Checkout sheet open/close** *(required)* | Open via Review N pill or peek tap. Close via scrim tap, swipe-down on handle (nice-to-have), or header ×. On close with items remaining: resume camera (`verificationPausedRef = false`). Empty cart after commit → auto-close sheet (D1). | H1 Visibility of system status |
|
||||
| **Pause identification under sheet** *(required)* | `verificationPausedRef.current = true` when checkout sheet **or** List picker **or** disambiguation is open. Camera stream stays mounted; detection/verify loop does not run. Resume on sheet close. | H1 Visibility of system status |
|
||||
| **Back with unsaved cart** *(required)* | Header back with any unprocessed cart rows → `<Modal>` confirm: title "Leave scanner?", body "{N} scanned cards haven't been added yet.", primary "Keep scanning" (dismiss), secondary "Leave" (`router.back()` or `/dashboard`). No confirm when cart empty. | H3 User control and freedom |
|
||||
| **Partial commit** *(required)* | Commit removes only selected rows from cart; sheet stays open with remainder (D6). Success toast `role="status"`. Primary button shows loading via `<Button loading>`. | H9 Error recovery; H1 Feedback |
|
||||
| **sessionStorage cart persist** *(required)* | Serialize `scannedCards` + `selectedCards` to `sessionStorage` on change (D7); hydrate on `/scanner` mount. Tab refresh preserves cart; new tab starts empty. Clear on explicit "Leave" confirm. | H6 Recognition rather than recall |
|
||||
| **Flash + camera swap** *(required)* | Flash button rendered only when `flashSupported && facingMode === 'environment'`. Camera-swap toggles `facingMode`; turning to front auto-disables torch. Swap button always visible when streaming. | H2 Match between system and real world |
|
||||
| **Gallery import** *(required)* | Top-right gallery button → hidden file input; selected image runs existing identify path; on success same peek + cart enqueue as live scan. Show spinner on gallery button while identifying (`aria-busy`). | H4 Consistency |
|
||||
| **Empty states** *(required)* | Cart sheet with 0 rows: should not open (Review N hidden at N=0). If last item removed in sheet → auto-close + resume camera. | H9 Error recovery |
|
||||
| **Loading states** *(required)* | Camera starting: existing spinner + "Starting camera…". Commit in flight: footer CTA `loading`, row checkboxes disabled. List picker: skeleton or spinner while `collections` fetch. | H1 Visibility of system status |
|
||||
| **Error states** *(required)* | Commit API failure: inline banner in sheet footer (not alert()), rows stay selected, retry enabled. Identify error: existing toast/notice path; do not enqueue. | H9 Error recovery |
|
||||
| **Desktop side panel** *(required)* | `md+`: cart is persistent right panel (not bottom sheet); no immersive Layout chrome; same selection + CTA semantics; no `verificationPausedRef` pause required (user can see camera + panel simultaneously) — **optional:** still pause on mobile only. | H4 Consistency |
|
||||
| **Optimistic commit** *(nice-to-have)* | Defer — show loading on CTA until API confirms; no optimistic removal (batch failures are painful). | H9 |
|
||||
|
||||
### Anti-patterns to avoid
|
||||
|
||||
- **Separate "Edit" mode hiding checkboxes** — violates supermarket-checkout mental model (H6).
|
||||
- **Silent enqueue on `disambiguation` / `needsUserSelection`** — must block on picker (H5).
|
||||
- **Per-card Add / condition / foil on scan peek** — design-direction anti-pattern; peek is read-only + tap-to-cart (H8).
|
||||
- **Unmounting camera when sheet opens** — causes slow re-start and flash re-permission; pause via `verificationPausedRef` only (H1).
|
||||
- **Auto-routing to DB on identify** — rebuild D3 reversed; enqueue only (H3).
|
||||
- **"binder" / "Save to binder" / "Mark Owned" button copy** — use `VOCAB` constants; CI forbidden-strings (H4).
|
||||
- **Hardcoded hex / `rgba(0,0,0,0.55)` in new chrome** — use glass tokens; migrate existing `ScannerCamera` literals in same brief (H4).
|
||||
- **Emoji toast glyphs** — SVG only per design-direction checklist (H4).
|
||||
- **`backdrop-filter` on cart thumbnail elements** — GPU budget; glass on row container only (H8).
|
||||
- **Deck destination in checkout** — D4; no deck picker (H4).
|
||||
- **Navigating away on commit** — D1 stay on camera (H3).
|
||||
- **Confirm dialog via `window.confirm`** — use `<Modal>` for back-guard; matches focus-trap contract (H7 Flexibility).
|
||||
- **Interactive peek controls stealing taps from viewfinder** — peek must not block scanning except its single open-cart hit target (H8).
|
||||
- **localStorage for cart** — D7 specifies `sessionStorage`; do not use existing `SCANNER_SESSION_STORAGE_KEY` localStorage for cart rows (H6).
|
||||
|
||||
### Mobile / responsive notes
|
||||
|
||||
- **<768px (mobile):** `Layout` `chrome="immersive"` — hide sidebar, `TopSearchBar`, `MobileNavigation`. Camera `100dvh` full-bleed (`min-h-0` flex child). Top bar respects `env(safe-area-inset-top)`; bottom bar `env(safe-area-inset-bottom)`. Checkout = bottom sheet (max-height ~85dvh, scrollable list, sticky footer). Peek sits above bottom bar, below brackets.
|
||||
- **≥768px (tablet/desktop):** Layout sidebar visible. Camera in main column; cart as **persistent right panel** (~360px) not sheet. Review N pill still opens/focuses panel if collapsed. No immersive chrome.
|
||||
- **375px floor:** verify footer CTAs stack (primary full-width, secondary below) without clipping qty steppers; row thumb stays 40×56.
|
||||
- **Landscape phone:** sheet max-height may need `max-h-[70dvh]` so viewfinder remains partially visible — architect to decide in brief; UX prefers partial camera peek above sheet scrim (H1).
|
||||
- **Touch:** swipe-down on sheet handle to dismiss (nice-to-have); scrim tap dismisses (required). 8px minimum gap between adjacent 44px targets in bottom bar.
|
||||
|
||||
## Architecture
|
||||
|
||||
Locked 2026-08-14. Layout gets `chrome="immersive"` (Brief 1). Four implementer briefs; no new API routes or schema changes.
|
||||
|
||||
### File plan
|
||||
|
||||
| File | Action | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `components/Layout.js` | modified | `chrome="immersive"` prop — hide `MobileNavigation` + `TopSearchBar` below `md` |
|
||||
| `test/components/Layout.test.js` | modified | Regression-lock immersive chrome |
|
||||
| `lib/use-scanner-queue.js` | modified | Enqueue-only `handleCardScanned`; checkout commit helpers; remove auto-route |
|
||||
| `lib/scanner-session.js` | modified | `SCANNER_CART_STORAGE_KEY` + load/save/clear cart in `sessionStorage` (D7) |
|
||||
| `test/lib/scanner-session.test.js` | modified | Cart persistence helpers |
|
||||
| `test/lib/use-scanner-queue.test.js` | new | No-network enqueue + bulk commit mocks |
|
||||
| `lib/use-camera-scanner.js` | modified | `facingMode` state + `switchFacingMode` (restart stream) |
|
||||
| `lib/use-scanner-identification.js` | modified | `identifyFromGalleryFile` adapter only (calls existing `tryLayer1TextIdentify`) |
|
||||
| `components/scanner/ScannerCamera.js` | modified | Full-bleed glass top/bottom bars; flash/swap/gallery; peek mount point |
|
||||
| `components/scanner/ScannerCountPill.js` | modified | Gradient Review {N} pill |
|
||||
| `components/scanner/ScannerScanPeek.js` | new | Non-interactive 3s peek; tap opens checkout |
|
||||
| `components/scanner/ScannerToast.js` | modified | SVG icons (no Unicode glyphs) |
|
||||
| `components/scanner/ScannerCheckoutSheet.js` | new | Mobile bottom-sheet cart (shell from `ScannerDisambiguation`) |
|
||||
| `components/scanner/ScannerReview.js` | modified | Desktop `md+` persistent side panel variant |
|
||||
| `components/scanner/ReviewCardItem.js` | modified | Checkbox + confidence ring; drop row destination picker |
|
||||
| `pages/scanner.js` | modified | Scanning-first orchestration; sheet state; pause ref; immersive Layout |
|
||||
| `pages/login.js` | modified | Honor `returnUrl` query after login (D2) |
|
||||
| `test/components/ScannerCheckoutSheet.test.js` | new | Sheet a11y + vocab + selection-disabled CTA |
|
||||
|
||||
**Not touched:** `pages/api/**`, `migrations/**`, `lib/scanner-card-identify.js` (identify pipeline), `components/scanner/ScannerDisambiguation.js` (reuse pattern only), `components/scanner/ScannerSetup.js` (dead path, not deleted).
|
||||
|
||||
### API surface
|
||||
|
||||
No new or modified API routes. Commit-time calls (unchanged):
|
||||
|
||||
| Method | Path | Request | Response | Auth | Rate limit |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| POST | `/api/user-cards` | `buildScannerCardPayload(card)` | 2xx / error JSON | Bearer JWT | none (existing) |
|
||||
| POST | `/api/collections/:id/cards` | `buildScannerCardPayload(card)` | 2xx / error JSON | Bearer JWT | none |
|
||||
| GET | `/api/collections` | — | collection[] | Bearer JWT | none |
|
||||
| POST | `/api/cards/batch-ownership` | `{ cardIds: number[] }` | `{ ownership }` | Bearer JWT | none |
|
||||
|
||||
Helpers live in `lib/scanner-route-api.js` (`addScannedCardToOwned`, `addScannedCardToCollection`, `fetchScannerCollections`, `fetchBatchOwnership`).
|
||||
|
||||
### Schema diff
|
||||
|
||||
None. Cart is client-side `sessionStorage` only (`SCANNER_CART_STORAGE_KEY`).
|
||||
|
||||
### Test plan
|
||||
|
||||
| Area | File | What to assert |
|
||||
| --- | --- | --- |
|
||||
| Cart merge defaults | `test/lib/scanner-session.test.js` (existing) | `processed: false` on new entries — keep green |
|
||||
| Cart persistence | `test/lib/scanner-session.test.js` | `saveScannerCart` / `loadScannerCart` round-trip |
|
||||
| No auto-route | `test/lib/use-scanner-queue.test.js` (new) | `handleCardScanned` never calls `routeScannedCardToDestination`; mock `fetch` |
|
||||
| Bulk commit | `test/lib/use-scanner-queue.test.js` | `handleBulkAction('owned')` invokes `addScannedCardToOwned` per selected id |
|
||||
| Layout immersive | `test/components/Layout.test.js` | Mobile nav hidden when `chrome="immersive"` |
|
||||
| Checkout sheet | `test/components/ScannerCheckoutSheet.test.js` | Dialog labels, `VOCAB` CTAs, disabled primary when selection empty |
|
||||
| Auth/Layout regressions | `test/lib/permission-middleware.test.js`, `test/components/Layout.test.js` | Do not weaken existing assertions |
|
||||
|
||||
Smoke (manual / post-merge): authenticated `/scanner` on 375px viewport — camera full-bleed, Review N opens sheet, commit to My Collection. Visual-diff may need baseline refresh if Layout chrome changes bleed to homepage (unlikely — scanner-only prop).
|
||||
|
||||
### Risk list
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| `pages/scanner.js` was shared by all three conductor guesses | Serialized: only Brief 4 touches `scanner.js` |
|
||||
| Gallery has no existing file-picker hook (boot finding) | Brief 3 adds `identifyFromGalleryFile` calling `tryLayer1TextIdentify` — no API change |
|
||||
| `facingMode` swap requires stream restart | Brief 3 `stopCamera` + `startCamera` on toggle; flash forced off on front |
|
||||
| `Set` not JSON-serializable | Brief 2 persists `selectedCardIds: number[]` |
|
||||
| Login lacks `returnUrl` today | Brief 4 adds query param + login handler; validate path starts with `/` |
|
||||
| `handleBulkAction` currently marks `processed: true` | Brief 2 removes committed rows from queue instead |
|
||||
| Layout visual-diff sensitivity | Narrow prop; immersive mobile-only; no sidebar restyle |
|
||||
| `verificationPausedRef` shared by disambiguation + sheet | Brief 4 `useEffect` ORs sheet/list-picker/disambiguation on mobile |
|
||||
| Deck code paths remain in queue hook | UI omits deck (D4); dead `deck` branch in `handleBulkAction` harmless until cleanup convoy |
|
||||
| iOS Safari no `torch` | Existing `flashSupported` probe; hide flash button |
|
||||
|
||||
### Decomposition
|
||||
|
||||
| Brief # | Title | Files | Depends on | Est. PR size |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Layout immersive chrome | `Layout.js`, `test/components/Layout.test.js` | — | ~80 LOC |
|
||||
| 2 | Cart model + sessionStorage | `use-scanner-queue.js`, `scanner-session.js`, tests | — | ~200 LOC |
|
||||
| 3 | Camera chrome + facing + peek | `ScannerCamera.js`, `use-camera-scanner.js`, `ScannerCountPill.js`, `ScannerScanPeek.js`, `ScannerToast.js`, `use-scanner-identification.js` | 2 | ~350 LOC |
|
||||
| 4 | Page orchestration + checkout sheet | `pages/scanner.js`, `pages/login.js`, `ScannerCheckoutSheet.js`, `ScannerReview.js`, `ReviewCardItem.js`, test | 1, 2, 3 | ~380 LOC |
|
||||
|
||||
### Slice dependencies (multitask-ready)
|
||||
|
||||
```yaml
|
||||
slice_dependencies:
|
||||
- brief: 1
|
||||
depends_on: []
|
||||
files:
|
||||
- components/Layout.js
|
||||
- test/components/Layout.test.js
|
||||
- brief: 2
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/use-scanner-queue.js
|
||||
- lib/scanner-session.js
|
||||
- test/lib/scanner-session.test.js
|
||||
- test/lib/use-scanner-queue.test.js
|
||||
- brief: 3
|
||||
depends_on: [2]
|
||||
files:
|
||||
- components/scanner/ScannerCamera.js
|
||||
- components/scanner/ScannerCountPill.js
|
||||
- components/scanner/ScannerScanPeek.js
|
||||
- components/scanner/ScannerToast.js
|
||||
- lib/use-camera-scanner.js
|
||||
- lib/use-scanner-identification.js
|
||||
- brief: 4
|
||||
depends_on: [1, 2, 3]
|
||||
files:
|
||||
- pages/scanner.js
|
||||
- pages/login.js
|
||||
- components/scanner/ScannerCheckoutSheet.js
|
||||
- components/scanner/ScannerReview.js
|
||||
- components/scanner/ReviewCardItem.js
|
||||
- test/components/ScannerCheckoutSheet.test.js
|
||||
```
|
||||
|
||||
**Parallelism:** Brief **1** and **2** can run in parallel (`depends_on: []`, disjoint files). Brief **3** starts after **2**. Brief **4** is serial after **1 + 2 + 3**. Do not dispatch Brief 3 until Brief 2 merges (cart API contract). Maximum fan-out: 2 implementers (Brief 1 ∥ Brief 2), then 1, then 1.
|
||||
|
||||
### Boot-the-brief check (2026-08-14)
|
||||
|
||||
| Check | Finding | Brief fix |
|
||||
| --- | --- | --- |
|
||||
| Auto-route still live | `handleCardScanned` L148–168 calls `routeScannedCardToDestination` | Brief 2 deletes block |
|
||||
| No `chrome` on Layout | `Layout({ children, user, showSearch })` only | Brief 1 adds prop |
|
||||
| `facingMode` hardcoded | `getUserMedia` uses `'environment'` only | Brief 3 adds toggle + restart |
|
||||
| No gallery entry point | Grep found zero file-picker wiring | Brief 3 `identifyFromGalleryFile` via `tryLayer1TextIdentify` |
|
||||
| Login no `returnUrl` | `login.js` always pushes `/dashboard` | Brief 4 adds safe return path |
|
||||
| Cart persistence | IA said in-memory; D7 overrides to `sessionStorage` | Brief 2 separate key from `localStorage` session prefs |
|
||||
| `ScannerToast` Unicode | `ICON_MAP` uses `✓` / `✗` | Brief 3 SVG replacement |
|
||||
| Cross-brief props | `ScannerCamera` needs sheet orchestration | Declared in Brief 3 ↔ 4 `cross_brief_commitments` |
|
||||
|
||||
No new npm packages. No peer-dep conflicts. `tryLayer1TextIdentify` and `resolveIdentifyOutcome` confirmed exported from `lib/scanner-card-identify.js`.
|
||||
|
|
@ -1,146 +0,0 @@
|
|||
# A11y audit — scanner-mobile-checkout
|
||||
|
||||
**Reviewer:** role-a11y-auditor
|
||||
**Convoy:** `scanner-mobile-checkout`
|
||||
**Surface:** uncommitted UI diff vs `origin/main` (+ untracked) — no GitHub PR
|
||||
**Date:** 2026-08-14
|
||||
**Model:** cursor-grok-4.5-high (`model_tier=audit`)
|
||||
**Skill note:** `.cursor/skills/accessibility-audit/SKILL.md` was not present in-repo; audit follows role + convoy UX § A11y constraints (14 items) + WCAG 2.2 AA (AAA target size where convoy requires).
|
||||
|
||||
## Diff scope (UI)
|
||||
|
||||
| Path | Status |
|
||||
| --- | --- |
|
||||
| `components/Layout.js` | modified (`chrome="immersive"`) |
|
||||
| `components/scanner/ScannerCamera.js` | modified |
|
||||
| `components/scanner/ScannerCountPill.js` | modified |
|
||||
| `components/scanner/ScannerToast.js` | modified |
|
||||
| `components/scanner/ReviewCardItem.js` | modified |
|
||||
| `components/scanner/ScannerReview.js` | modified |
|
||||
| `components/scanner/ScannerCheckoutSheet.js` | **new** |
|
||||
| `components/scanner/ScannerScanPeek.js` | **new** |
|
||||
| `pages/scanner.js` | modified |
|
||||
| `test/components/ScannerCheckoutSheet.test.js` | new (a11y-adjacent) |
|
||||
|
||||
Non-UI (session/hooks/login/tests) excluded from findings.
|
||||
|
||||
## Executive summary
|
||||
|
||||
- Chrome controls (flash / swap / gallery / back / Review N), peek tap target, toast live region, checkout `role="dialog"` + Escape + `useFocusTrap`, and sitewide `prefers-reduced-motion` collapse are largely in good shape.
|
||||
- **One severity-3 finding:** nested List-picker `<Modal>` over open checkout sheet leaves **two Escape handlers and two focus traps** active — Escape dismisses both layers (and Tab can fight). Convoy constraint 10.
|
||||
- Several severity-2 gaps vs promised constraints: missing sheet close control, no `aria-describedby` helper on disabled commit CTA, camera chrome not `inert`/`aria-hidden` under sheet, native checkbox hit target unreliable at 44×44.
|
||||
- **Recommendation:** request-changes until nested-overlay Escape/trap is fixed; ship sev-2 before merge if possible.
|
||||
|
||||
**Counts:** 7 findings (sev ≥ 3: **1**, sev < 3: **6**). Constraint checklist: **9 pass / 3 partial / 2 fail**.
|
||||
|
||||
## Convoy constraint checklist
|
||||
|
||||
| # | Constraint | Result | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | 44×44 targets (2.5.5) | **Partial** | ChromeIconButton, Review N, qty ±, overflow use `minWidth/Height: 44`. Native checkbox is `w-5 h-5` with style mins — hit box often stays ~20px. |
|
||||
| 2 | Contrast on glass (1.4.3) | **Pass*** | Token text colors; no instrumented contrast measure (*static review). |
|
||||
| 3 | Focus order open/close (2.4.3) | **Partial** | Trap focuses first focusable in panel; restore via `useFocusTrap`. No header ×; restore may miss if opener was auto-dismissed peek. |
|
||||
| 4 | Keyboard Escape / peek Enter (2.1.1) | **Partial** | Escape + button peek OK; nested Escape conflict (see A1). |
|
||||
| 5 | Dialog name/role (4.1.2) | **Pass** | Checkout: `role="dialog"` `aria-modal` `aria-labelledby` → "{N} cards scanned". List picker Modal title "Choose a List". |
|
||||
| 6 | Required `aria-label`s | **Pass** | Leave / gallery / flash+`aria-pressed` / swap / Review N / checkbox / qty / overflow present. |
|
||||
| 7 | Non-text (1.1.1) | **Pass** | Row thumbs `alt={card.name}`; peek thumb `alt=""` under named button; decorative SVGs `aria-hidden`. |
|
||||
| 8 | Status messages (4.1.3) | **Pass** | Toast `role="status"` `aria-live="polite"`; scan status `aria-live="polite"`. Peek is interactive, not a second live region (toast covers identify). |
|
||||
| 9 | Reduced motion (2.3.3) | **Pass** | Peek/sheet/toast transitions + spinners covered by `styles/globals.css` `@media (prefers-reduced-motion: reduce)`. |
|
||||
| 10 | Focus trap all overlays | **Fail** | Sheet traps; Modal traps; both stay active when List picker opens over checkout. |
|
||||
| 11 | Confidence not color-only (1.4.1) | **Partial** | Visible `{pct}% match` + ring; checkbox `aria-label` adds confidence only when <85%; header says "Some matches…" not "{N} need review". |
|
||||
| 12 | Gallery file input | **Pass** | `sr-only` input + labeled button; `aria-busy` while identifying. |
|
||||
| 13 | Disabled CTA + describedby | **Fail** | `disabled` only; no helper text / `aria-describedby` / `aria-disabled`. |
|
||||
| 14 | Hide camera under sheet | **Fail** | `isCheckoutOpen` only changes status copy; video + chrome not `aria-hidden`/`inert`. |
|
||||
|
||||
## Findings
|
||||
|
||||
| Sev | Layer | WCAG | Surface | Issue | Fix |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **3** | Keyboard / Focus | 2.1.1, 2.4.3 | `pages/scanner.js` + `ScannerCheckoutSheet.js` | Nested List picker Modal while checkout sheet open: both register document `Escape` + Tab traps. Escape closes **picker and sheet**. | Deactivate checkout trap + Escape while `isListPickerOpen`; or close sheet Escape only when picker closed (`if (e.key === 'Escape' && !isListPickerOpen)`). Prefer `useFocusTrap(active && !nestedOpen)`. |
|
||||
| **2** | Name / Instructions | 3.3.2, 4.1.2 | `ScannerCheckoutSheet.js` `CheckoutFooter` ~L40–51 | Zero selection: primary disabled with no visible "Select at least one card" / `aria-describedby`. | Add helper `<p id="checkout-select-hint">…</p>`; `aria-describedby={selectedCount === 0 ? 'checkout-select-hint' : undefined}`; optional `aria-disabled` mirroring `disabled`. |
|
||||
| **2** | Structure / AT | 1.3.2, 4.1.2 | `ScannerCamera.js` + `pages/scanner.js` | Sheet open does not set `aria-hidden`/`inert` on viewfinder chrome (constraint 14). | When `isCheckoutOpen` (mobile), set `inert` on camera root (or `aria-hidden` on `<video>` + `tabIndex={-1}` / hide chrome from AT). |
|
||||
| **2** | Target size | 2.5.5 | `ReviewCardItem.js` ~L72–79 | Checkbox visual/control ~20×20 despite `minWidth/Height: 44` on `<input type="checkbox">` (unreliable). | Wrap in `<label className="… min-w-[44px] min-h-[44px] flex items-center justify-center">` or custom hit pad. |
|
||||
| **2** | Keyboard / Operable | 2.1.1, 2.4.3 | `ScannerCheckoutSheet.js` ~L211–217 | No header dismiss × (convoy: close via × / Escape / scrim). Keyboard-only users depend solely on Escape. | Add `aria-label="Close cart"` button in sheet header; include in focus order as first focusable. |
|
||||
| **1** | Understandable | 3.3.1 / UX | `pages/scanner.js` Leave Modal ~L152–166 | Copy uses "Stay" not "Keep scanning"; description omits `{N}` count. | `description={\`${unprocessedCount} scanned cards haven't been added yet.\`}`; primary label "Keep scanning". |
|
||||
| **1** | Sensory | 1.4.1 | `ScannerCheckoutSheet.js` ~L127–130 | Low-confidence subline lacks count; checkbox confidence in name only when <85%. | Subline: `{n} need review`; include confidence in checkbox `aria-label` whenever `confidencePct != null`. |
|
||||
|
||||
### Severity ≥ 3 detail
|
||||
|
||||
#### A1 — Nested Escape / dual focus trap (sev 3)
|
||||
|
||||
**Scenario:** User opens checkout sheet → taps **Add to List** → List picker Modal opens. Presses **Escape** intending to close only the picker.
|
||||
|
||||
**Observed behavior (static):**
|
||||
|
||||
1. `ScannerCheckoutSheet` always calls `useFocusTrap(true)` and adds a document `keydown` Escape → `onClose` while mounted (`ScannerCheckoutSheet.js` L171–188).
|
||||
2. `<Modal open={isListPickerOpen}>` independently traps focus and listens for Escape → its `onClose` (`Modal.js` L28–37; `pages/scanner.js` L168–173).
|
||||
3. Checkout stays mounted (`pages/scanner.js` L131–137) while picker is open — neither trap is suspended.
|
||||
|
||||
Both Escape listeners fire on one keypress → picker closes **and** cart sheet closes. Tab handlers from both traps remain registered → unpredictable focus cycling (constraint 10).
|
||||
|
||||
**Suggested fix (minimal):**
|
||||
|
||||
```js
|
||||
// ScannerCheckoutSheet — accept activeTrap prop
|
||||
const sheetRef = useFocusTrap(trapActive !== false);
|
||||
|
||||
useEffect(() => {
|
||||
if (!trapActive) return undefined;
|
||||
// … Escape handler only when trapActive
|
||||
}, [onClose, sheetRef, trapActive]);
|
||||
```
|
||||
|
||||
```js
|
||||
// pages/scanner.js
|
||||
<ScannerCheckoutSheet
|
||||
trapActive={!isListPickerOpen}
|
||||
…
|
||||
/>
|
||||
```
|
||||
|
||||
Or close List picker with Escape via Modal only, and in checkout Escape handler: `if (document.querySelector('[data-list-picker-open]')) return`.
|
||||
|
||||
## Layer walk (5 layers, summary)
|
||||
|
||||
| Layer | Verdict |
|
||||
| --- | --- |
|
||||
| **1 Perceivable** | Toast/status live regions OK; confidence has text+ring; peek/toast SVG icons OK; reduced-motion via global CSS OK. |
|
||||
| **2 Operable** | 44px chrome generally OK; nested Escape/trap is the blocker; missing sheet ×; checkbox target weak. |
|
||||
| **3 Understandable** | Labels strong on chrome; leave-modal / empty-CTA / low-confidence copy incomplete vs convoy. |
|
||||
| **4 Robust** | Dialog semantics present; dual `aria-modal` when nested; camera not inert under sheet. |
|
||||
| **5 Consistency** | Matches `ScannerDisambiguation` sheet shell pattern (good); nested Modal over sheet needs same trap suspension pattern as disambiguation-above-checkout (z-50 vs z-40) — disambiguation currently unlikely while checkout open because verify pauses, but List picker is the live path. |
|
||||
|
||||
## Suggested diffs (priority)
|
||||
|
||||
1. **P0** — Suspend checkout Escape + `useFocusTrap` while List picker (or any nested Modal) is open.
|
||||
2. **P1** — Disabled CTA helper + `aria-describedby`.
|
||||
3. **P1** — `inert` / `aria-hidden` on camera when mobile checkout open.
|
||||
4. **P1** — 44×44 checkbox hit area via label wrapper.
|
||||
5. **P2** — Sheet close button; leave-modal copy + count; "{N} need review".
|
||||
|
||||
## Patterns to lift
|
||||
|
||||
- `ChromeIconButton` — good reusable 44px + `aria-label` / `aria-pressed` / `aria-busy` pattern (`ScannerCamera.js`).
|
||||
- `ScannerDisambiguation` + `useFocusTrap` — correct shell to copy; extend with **`active` gated by nested overlays**.
|
||||
- `ScannerToast` SVG + `role="status"` — keep; do not add a competing live region on peek.
|
||||
|
||||
## Automated checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| axe-core / CI a11y job | Not run (static role audit) |
|
||||
| Manual SR | Recommend VoiceOver pass: open cart → Add to List → Escape once |
|
||||
|
||||
## Approval recommendation
|
||||
|
||||
- [ ] approve
|
||||
- [x] **request-changes** — sev ≥ 3 open (nested Escape/trap)
|
||||
- [ ] comment-only
|
||||
|
||||
Fix A1 before merge. Sev-2 items should land in the same PR or an immediate follow-up brief tagged a11y.
|
||||
|
||||
## Hand-off
|
||||
|
||||
A11y audit complete. **7 findings** (sev ≥ 3: **1**, sev < 3: **6**).
|
||||
Report: `.convoys/scanner-mobile-checkout/audits/a11y-20260814.md`.
|
||||
Recommend fixing sev ≥ 3 before merge.
|
||||
|
|
@ -1,153 +0,0 @@
|
|||
# Design-System Audit — scanner-mobile-checkout
|
||||
|
||||
**Role:** `role-design-system-auditor`
|
||||
**Surface:** uncommitted `feat/scanner-mobile-checkout` UI (`git diff origin/main` + untracked scanner UI)
|
||||
**Convoy:** `.convoys/scanner-mobile-checkout.md`
|
||||
**Date:** 2026-08-14
|
||||
**Scope:** UI / DS only — read-only; no code changes
|
||||
|
||||
**Inputs reviewed**
|
||||
|
||||
| Source | Notes |
|
||||
| --- | --- |
|
||||
| Diff UI | `Layout.js`, `ScannerCamera.js`, `ScannerCountPill.js`, `ScannerToast.js`, `ReviewCardItem.js`, `ScannerReview.js`, `pages/scanner.js` |
|
||||
| Untracked | `ScannerCheckoutSheet.js`, `ScannerScanPeek.js` |
|
||||
| Direction lock | `design_direction` v1 + `## Design direction` in convoy |
|
||||
| Tokens | `docs/DESIGN_TOKENS.md`, `styles/globals.css` |
|
||||
| Primitives | `components/ui/{GlassSurface,Button,Modal,Input}.js` |
|
||||
| Skill | `.cursor/skills/design-systems/SKILL.md` **not installed** in this repo; audit follows role file + prior Liquid Glass audit shape + `docs/DESIGN_TOKENS.md` |
|
||||
|
||||
---
|
||||
|
||||
## Audit summary
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Direction lock (Liquid Glass + immersive camera + sheet) | ⚠️ Partial | Chrome bars + VOCAB CTAs + Modal reuse land; **L-brackets / scan-line missing**; sheet tint recipe drifts |
|
||||
| Hex in JSX | ❌ | 1 literal `#ffffff` in `ReviewCardItem.js` |
|
||||
| Binder / stale vocab | ✅ | No `binder` / `Mark Owned` / `Save to binder` in scoped UI |
|
||||
| `backdrop-filter` on cart **thumbnails** | ✅ | Thumbs are solid image/`--bg-tertiary`; no filter on `<img>` |
|
||||
| GlassSurface / Button / Modal reuse | ⚠️ Mixed | Camera chrome + peek: GlassSurface; checkout sheet/toast/rows: `glass-panel*` / hand-rolled |
|
||||
| Sev ≥ 3 findings | **2** | Hex literal; missing bracket + scan-line direction lock |
|
||||
|
||||
---
|
||||
|
||||
## Maturity scoring (repo DS + this surface)
|
||||
|
||||
Scores 0–4. Evidence cites paths/counts.
|
||||
|
||||
| Axis | Score | Evidence |
|
||||
| --- | --- | --- |
|
||||
| **Tokens (T)** | **3** | Documented 3-tier glass surface / blur / rim / elevation / scrim in `docs/DESIGN_TOKENS.md` + `styles/globals.css`. Diff mostly consumes `var(--*)`. Residual: `.glass-panel` still hardcodes `blur(12px) saturate(180%)` (not `--glass-blur-*` / `--glass-saturate`); toast uses literal `blur(12px)`. |
|
||||
| **Components (C)** | **3** | Kit under `components/ui/`: GlassSurface, Modal, Button, Input, SearchBar, StatCard (+ chrome). Scanner adopts GlassSurface on camera bars/icons/peek (9 call sites in `ScannerCamera.js`); Modal×2 + Button in `pages/scanner.js` / checkout footer. Gaps: toast + sheet panel + cart rows skip GlassSurface. |
|
||||
| **Patterns (P)** | **2** | Locked pattern “immersive camera + bottom-sheet checkout” partially shipped (immersive Layout, sheet shell mirroring Disambiguation, peek non-interactive). **Detection chrome still filled rectangles** (info/success), not ember L-brackets + scan-line. Confidence mid-band maps to gold, not direction’s amber/ember table. |
|
||||
| **Governance (G)** | **3** | Convoy `design_direction` locked 2026-08-14; `ui-and-theming.mdc` + vocab CI; `forbidden-hex-in-jsx` / forbidden stale strings. No design-systems skill package in-repo (template path missing). |
|
||||
| **Adoption (A)** | **2** | This surface: GlassSurface on live chrome/peek ✅; checkout sheet + toast + rows use utility classes / ad-hoc styles ❌; Review N pill is raw `<button>` with gradient (OK shape) but skips ember-rim + dead GlassSurface import. Vocab CTAs ✅. |
|
||||
|
||||
**Composite:** T3 / C3 / P2 / G3 / A2
|
||||
|
||||
**Top leverage:** **Patterns (P)** — implement Screen 1 bracket + scan-line recipe and align checkout sheet to `GlassSurface tint="low"` + toast to GlassSurface/`--glass-surface-high` so the locked Liquid Glass pattern reads as one system, not chrome-good / body-utility.
|
||||
|
||||
---
|
||||
|
||||
## Direction lock
|
||||
|
||||
Locked fields enforced: Liquid Glass; immersive overlay + bottom sheet; ember/flame accents as rim/glow/gradient only; VOCAB CTAs; no binder; no hex; no per-card Add on peek; no `backdrop-filter` on cart thumbs; reuse GlassSurface / Modal / Button.
|
||||
|
||||
| Locked requirement | Diff status |
|
||||
| --- | --- |
|
||||
| Immersive `chrome="immersive"` mobile | ✅ `Layout.js` + `pages/scanner.js` |
|
||||
| Top/bottom glass bars (`--glass-surface-mid`) | ✅ `GlassSurface tint="mid"` in `ScannerCamera.js` |
|
||||
| L-brackets `--accent-flame` / `--accent-ember` + scan-line | ❌ Filled `border` boxes + `--color-info` / `--color-success` overlays; **no** scan-line / `prefers-reduced-motion` gate |
|
||||
| Scan peek glass, tap-to-cart only | ✅ `ScannerScanPeek.js` |
|
||||
| Toast glass-high + SVG check | ⚠️ SVG ✅; surface is `rgba(--bg-secondary-rgb)` + literal blur, not GlassSurface / `--glass-surface-high` |
|
||||
| Review N gradient + `--ember-rim-pronounced` | ⚠️ Gradient ✅; **no** ember rim; unused `GlassSurface` import |
|
||||
| Sheet scrim `--modal-scrim` + blur-high | ✅ `ScannerCheckoutSheet.js` styled-jsx |
|
||||
| Sheet panel `--glass-surface-low` via GlassSurface | ❌ `glass-panel-strong` → surface-**high** recipe |
|
||||
| Footer VOCAB + Button primary/ghost | ⚠️ VOCAB ✅; secondary uses `variant="secondary"` not `ghost` |
|
||||
| Confidence rings tokenized (green / amber / orange) | ⚠️ Tokens used; mid=`--accent-gold`, low=`--color-warning` vs lock’s ember/amber table |
|
||||
| No hex / no binder | ❌ one `#ffffff`; binder clear |
|
||||
| Modal for leave + list picker | ✅ |
|
||||
| No backdrop on thumbnails | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Token audit (3-tier)
|
||||
|
||||
| Tier | Expectation | Diff notes |
|
||||
| --- | --- | --- |
|
||||
| Primitives | Palette / RGB triples in CSS only | No new hex in CSS from this diff. JSX `#ffffff` violates consumer rule. |
|
||||
| Aliases | `--glass-surface-*`, `--glass-blur-*`, rims, scrim | Camera/scrim/peek mostly correct. Toast blur literal `12px` should be `var(--glass-blur-low)`. `.glass-panel` utility (row list) still non-token blur/saturate (pre-existing; amplified by N cart rows). |
|
||||
| Components | GlassSurface / Button / Modal compose aliases | Sheet + toast + rows compose utilities/hand styles instead of primitives. |
|
||||
|
||||
---
|
||||
|
||||
## Component / adoption audit (scoped surface)
|
||||
|
||||
| Element | Expected | Actual | Rate |
|
||||
| --- | --- | --- | --- |
|
||||
| Glass chrome bars | `<GlassSurface>` | Yes (`ScannerCamera`) | High |
|
||||
| Scan peek | `<GlassSurface>` | Yes | High |
|
||||
| Toast | `<GlassSurface tint="high">` or equivalent | Hand-rolled | Low |
|
||||
| Checkout sheet panel | `<GlassSurface tint="low">` | `glass-panel-strong` | Low |
|
||||
| Cart rows | GlassSurface high **or** solid `--bg-secondary` | `.glass-panel` (blur per row) | Medium — OK container glass; GPU stack risk |
|
||||
| Footer CTAs | `<Button>` | Yes | High |
|
||||
| Leave / List dialogs | `<Modal>` | Yes | High |
|
||||
| Review N | Button or GlassSurface + ember rim | Raw `<button>` + gradient | Medium |
|
||||
|
||||
**Missing primitive usage (not missing primitives):** toast + sheet should compose existing GlassSurface rather than inventing parallel glass.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
Severity 0–4. Cap prioritized; sev ≥ 3 blocks merge recommendation for DS gate.
|
||||
|
||||
| ID | Sev | Finding | Evidence | Fix |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| DS-1 | **3** | Hardcoded hex in JSX | `ReviewCardItem.js` qty `+` button `color: '#ffffff'` | Use theme-safe token (e.g. dark-theme `--text-primary` on ember fill, or shared on-accent pattern used by `<Button variant="primary">`) |
|
||||
| DS-2 | **3** | Direction lock: detection chrome ≠ L-brackets + scan-line | `ScannerCamera.js` filled rect overlays via `overlayBorderColor` (`--color-info` / `--color-success`); no bracket SVG/corners; no ember scan-line / reduced-motion | Ship Screen 1 bracket recipe (`--accent-ember` / `--accent-flame`) + gradient scan-line; disable loop under `prefers-reduced-motion` |
|
||||
| DS-3 | **2** | Toast bypasses glass recipe | `ScannerToast.js`: `rgba(var(--bg-secondary-rgb), 0.9)` + `backdropFilter: 'blur(12px)'` | Wrap with `<GlassSurface tint="high" blur="low|mid" rim="subtle">`; drop literal blur px |
|
||||
| DS-4 | **2** | Checkout sheet panel wrong surface tier + no GlassSurface | `ScannerCheckoutSheet.js` `glass-panel-strong` (high) for panel + sticky footer | Panel: GlassSurface `tint="low"` inside scrim; footer sticky on same recipe or solid inner; match Modal panel docs |
|
||||
| DS-5 | **2** | Review N missing ember-pronounced rim; dead import | `ScannerCountPill.js` imports GlassSurface unused; no `--ember-rim-pronounced`; `text-white` utility | Apply rim via GlassSurface `as="button"` `rim="ember-pronounced"` or box-shadow token; remove dead import; avoid raw white |
|
||||
| DS-6 | **2** | Confidence band colors drift from lock | `confidenceRingColor`: <70 `--color-warning`, 70–84 `--accent-gold`, else success | Align to lock: <70 `--accent-ember`, 70–84 amber/warning token, ≥85 `--color-success` |
|
||||
| DS-7 | **1** | Secondary CTA variant | Checkout footer `Button variant="secondary"` | Prefer `variant="ghost"` per design direction |
|
||||
| DS-8 | **1** | Leave-modal dismiss copy | `pages/scanner.js` label `"Stay"` | Direction: primary dismiss **"Keep scanning"** |
|
||||
| DS-9 | **1** | Hardcoded vocab fallback | `ReviewCardItem.js` `'My Collection'` string | `VOCAB.MY_COLLECTION` |
|
||||
| DS-10 | **1** | Stacked row `backdrop-filter` via `.glass-panel` | Each cart row blurs (`blur(12px)` in utility) | Prefer solid `--bg-secondary` (or GlassSurface without stacking N blurs) for row inners over thumbs — thumbs themselves are clean |
|
||||
|
||||
### Passes (not findings)
|
||||
|
||||
- No `"binder"` / `"Save to binder"` / `"Mark Owned"` in scoped UI.
|
||||
- Checkout CTAs import `VOCAB.ADD_TO_MY_COLLECTION` / `VOCAB.ADD_TO_LIST`.
|
||||
- List picker uses `collectionDisplayName`.
|
||||
- Peek has no Add / condition / foil; single open-cart control.
|
||||
- Toast icons are SVG (no emoji glyphs).
|
||||
- Scrim uses `--modal-scrim` + `var(--glass-blur-high)`.
|
||||
- Cart thumbnails: no `backdrop-filter`.
|
||||
- Leave + List picker use `<Modal>`; commit CTAs use `<Button>`.
|
||||
|
||||
---
|
||||
|
||||
## Governance notes
|
||||
|
||||
- Contribution path for glass: `docs/DESIGN_TOKENS.md` + `ui-and-theming.mdc` (“reach for `components/ui/` first”).
|
||||
- CI: hex-in-JSX + stale vocab gates apply — **DS-1 will fail / should fail `forbidden-hex-in-jsx`**.
|
||||
- Design-systems skill/templates not present under `.cursor/skills/design-systems/` — maturity G capped partly by missing shared audit tooling in-repo.
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Do not treat DS as merge-clean until DS-1 and DS-2 are fixed.** DS-3–DS-6 are the follow-up pass that makes checkout/toast/pill match the same Liquid Glass composition as the camera chrome.
|
||||
|
||||
**Child tasks (sev ≥ 3):**
|
||||
|
||||
1. Replace `#ffffff` in `ReviewCardItem.js` (and any sibling `text-white` on detection badges if hex-gate/token policy treats them as on-accent debt).
|
||||
2. Implement ember/flame L-brackets + reduced-motion-aware scan-line on the viewfinder per locked Screen 1.
|
||||
|
||||
---
|
||||
|
||||
## Hand-off
|
||||
|
||||
DS audit complete. Maturity: **T3/C3/P2/G3/A2**. Top leverage: invest in **Patterns** (brackets/scan-line + sheet/toast GlassSurface alignment). Sev ≥ 3 findings: **2**. Report: `.convoys/scanner-mobile-checkout/audits/design-system-20260814.md`.
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
## Reviewer Report
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Scope match | ✅ | All app changes map to briefs 1–4 `files:`; no unauthorized expansion. Convoy docs/metrics only extras. |
|
||||
| Conventions | ✅ | Vocab via `VOCAB`; CSS tokens / GlassSurface; Modal for leave + list picker; login `returnUrl` hardened (`/` only, blocks `//` and `://`). |
|
||||
| Security | ✅ | Shallow L1–L2: no new API routes; client cart in `sessionStorage`; returnUrl open-redirect guarded. Defer depth to security-auditor when PR exists. |
|
||||
| Regression risk | medium | Scanner page rewritten (phase machine removed); auto-route deleted (intentional); Layout immersive gated by prop but TopSearchBar/MobileNavigation paths change for `/scanner`. |
|
||||
| Test coverage | ⚠️ | Brief-required suites green (27/27). Commit success/error detection untested and currently wrong (see Critical). |
|
||||
| Documentation | ✅ | No AGENTS.md / schema updates required for this convoy. |
|
||||
|
||||
### Findings
|
||||
|
||||
- 🔴 **Critical** (must fix before merge): Stale React state used to detect commit failure in `ScannerCheckoutContent.handleCommitOwned` and `pages/scanner.js` `handleListPick`. After `await queue.commitSelectedToOwned()` / `commitSelectedToCollection()`, `queue.scannedCards` is still the pre-commit render snapshot, so a successful commit looks like “all remaining” → false error banner; list picker never closes on success (`setIsListPickerOpen(false)` skipped). Fix: have commit helpers return `successfulIds` (or a boolean), and branch on that — do not re-read hook state immediately after `await`.
|
||||
- 🟡 **Suggestion** (consider): `ReviewCardItem` still mounts the per-row destination `<select>` when `!showCheckbox`. Checkout path is fine (`showCheckbox`), but Brief 4 asked to remove inline destination pickers; dead path adds confusion and retains pre-existing `#ffffff` on that control.
|
||||
- 🟡 **Suggestion** (consider): Add a focused test that commit success returns/propagates success without relying on immediate `queue.scannedCards` re-read (locks the Critical fix). Optional: login `returnUrl` honor + reject open redirect.
|
||||
- 🟢 **Nice to have** (optional): Convoy markdown todos still unchecked despite implemented work — conductor/doc-writer hygiene, not a merge blocker.
|
||||
|
||||
### Approval recommendation
|
||||
- request-changes
|
||||
|
||||
### AC evidence (briefs 1–4)
|
||||
|
||||
| Brief | AC | Evidence |
|
||||
| --- | --- | --- |
|
||||
| 1 | Immersive hides mobile nav / TopSearchBar below md | `Layout.js` `!isImmersive` MobileNav; TopSearchBar `max-md:hidden`; tests added |
|
||||
| 1 | Default chrome unchanged | `chrome = 'default'`; regression tests |
|
||||
| 2 | No fetch in `handleCardScanned` | Auto-route block removed; queue test asserts no route helpers |
|
||||
| 2 | sessionStorage cart | `SCANNER_CART_STORAGE_KEY` + load/save/clear + tests |
|
||||
| 2 | Commit removes rows | `successfulIds` filter in `handleBulkAction` |
|
||||
| 3 | Facing swap + flash rear-only | `switchFacingMode`; `showFlash` env-only; torch off on `user` |
|
||||
| 3 | Peek 3s / toast SVG / gallery adapter | `ScannerScanPeek`, SVG `ToastIcon`, `identifyFromGalleryFile` |
|
||||
| 4 | No Setup; returnUrl; sheet + pause; leave Modal | `pages/scanner.js` + hardened `login.js` |
|
||||
| 4 | Desktop side panel | `ScannerReview` `variant="side-panel"` |
|
||||
| 4 | Checkout sheet tests | header count, disabled primary, vocab labels |
|
||||
|
||||
### Test run
|
||||
|
||||
`npm run test:run -- test/components/Layout.test.js test/lib/scanner-session.test.js test/lib/use-scanner-queue.test.js test/components/ScannerCheckoutSheet.test.js` → **27/27 passed**.
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
---
|
||||
convoy: scanner-mobile-checkout
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/Layout.js
|
||||
- test/components/Layout.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 4
|
||||
description: |
|
||||
Brief 4 passes `chrome="immersive"` on `<Layout>` from `pages/scanner.js`
|
||||
for authenticated scanner sessions. This brief only adds the prop and
|
||||
mobile-only hiding behavior; Brief 4 owns when it is set.
|
||||
---
|
||||
|
||||
# Brief 1: Layout immersive chrome
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Add a narrow `chrome="immersive"` prop to `Layout` that hides global app chrome on viewports `< md` without restyling the desktop sidebar.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `components/Layout.js`
|
||||
- `test/components/Layout.test.js`
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- Extend the existing `Layout` signature: `export default function Layout({ children, user = null, showSearch = false })` → add `chrome = 'default'`.
|
||||
- Immersive is **mobile-only** (`md:hidden` / `max-md:` patterns). At `md+`, immersive behaves like `default` (sidebar + TopSearchBar unchanged per D3 desktop note).
|
||||
- Hide when `chrome === 'immersive'` on `< md`:
|
||||
- `<MobileNavigation />` (line ~674)
|
||||
- `<TopSearchBar />` (line ~986)
|
||||
- Desktop `<aside>` sidebar is already `hidden md:flex` — no change needed at `md+`; on mobile the drawer + bottom nav are the chrome to suppress.
|
||||
- Main column: remove `pb-16` bottom padding when immersive (no bottom nav). Use `max-md:pb-0` on the main wrapper (`flex-1 flex flex-col pb-16 md:pb-0`).
|
||||
- Outer shell: optional `max-md:p-0` when immersive so camera can be true full-bleed.
|
||||
- Do **not** change sidebar styles, nav items, or command palette behavior.
|
||||
- Use CSS tokens only — no new hex in JSX.
|
||||
|
||||
## Implementation shape (verified against `Layout.js`)
|
||||
|
||||
```js
|
||||
export default function Layout({
|
||||
children,
|
||||
user = null,
|
||||
showSearch = false,
|
||||
chrome = 'default',
|
||||
}) {
|
||||
const isImmersive = chrome === 'immersive';
|
||||
// ...
|
||||
// MobileNavigation: {!isImmersive && <MobileNavigation ... />}
|
||||
// TopSearchBar: {user && !isImmersive && <TopSearchBar ... />}
|
||||
// Main wrapper className: include isImmersive && 'max-md:pb-0'
|
||||
}
|
||||
```
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `chrome="immersive"` hides `MobileNavigation` and `TopSearchBar` below `md` breakpoint
|
||||
- [ ] `chrome="immersive"` at `md+` renders identical chrome to `chrome="default"` (sidebar + TopSearchBar visible)
|
||||
- [ ] `chrome="default"` (or omitted) is unchanged from current behavior
|
||||
- [ ] `test/components/Layout.test.js` adds regression tests: immersive hides mobile nav landmark; default still renders Sign-in CTA when `user={null}` (existing 5 assertions preserved)
|
||||
- [ ] No scope expansion (do not edit files outside `files:` above)
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Immersive chrome is isolated to `Layout.js` so visual-diff-sensitive sidebar code stays untouched. Mobile-only gating matches design-direction desktop exception. Brief 4 wires the prop from `/scanner` without further Layout changes.
|
||||
|
|
@ -1,99 +0,0 @@
|
|||
---
|
||||
convoy: scanner-mobile-checkout
|
||||
brief_number: 2
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/use-scanner-queue.js
|
||||
- lib/scanner-session.js
|
||||
- test/lib/scanner-session.test.js
|
||||
- test/lib/use-scanner-queue.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 4
|
||||
description: |
|
||||
Export `clearScannerCartStorage()` from `scanner-session.js`. Brief 4
|
||||
calls it when the user confirms "Leave" on the back-guard modal (D1/D7).
|
||||
Queue hook exposes `hydrateFromStorage` on mount — Brief 4 does not
|
||||
reimplement hydration.
|
||||
---
|
||||
|
||||
# Brief 2: Cart model — stop auto-route + sessionStorage
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Reverse rebuild D3 auto-route: identifies enqueue locally only, auto-select new rows, and persist cart + selection in `sessionStorage` (D7).
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `lib/use-scanner-queue.js`
|
||||
- `lib/scanner-session.js`
|
||||
- `test/lib/scanner-session.test.js`
|
||||
- `test/lib/use-scanner-queue.test.js` (new)
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- **No new API routes.** Commit paths stay `addScannedCardToOwned` / `addScannedCardToCollection` from `lib/scanner-route-api.js` (already verified).
|
||||
- **Do not use** `SCANNER_SESSION_STORAGE_KEY` / `localStorage` for cart rows (UX anti-pattern). Add a separate key in `scanner-session.js`:
|
||||
|
||||
```js
|
||||
export const SCANNER_CART_STORAGE_KEY = 'deckhearth:scanner-cart';
|
||||
```
|
||||
|
||||
- Serialize `selectedCards` as `number[]` (Set is not JSON-safe).
|
||||
- Keep `mergeScannedCardEntry` unchanged — cart entry shape already includes `processed: false` and `confidence` from `buildScannedCardPayload`.
|
||||
- `sessionDestination` param may remain on the hook signature for backward compat but **must not** trigger network I/O in `handleCardScanned`.
|
||||
|
||||
## Implementation shape (verified against `use-scanner-queue.js`)
|
||||
|
||||
**Remove auto-route** — delete the block after `setScannedCards(nextQueue)`:
|
||||
|
||||
```js
|
||||
// DELETE lines ~148-168 (sessionDestination guard + routeScannedCardToDestination)
|
||||
```
|
||||
|
||||
**Replace `handleCardScanned` with enqueue-only:**
|
||||
|
||||
```js
|
||||
const handleCardScanned = (cardData) => {
|
||||
setAutoRouteError(null);
|
||||
const { cardEntry, scannedCards: nextQueue } = mergeScannedCardEntry(
|
||||
scannedCards,
|
||||
cardData,
|
||||
scanDefaults
|
||||
);
|
||||
setScannedCards(nextQueue);
|
||||
setSelectedCards((prev) => new Set([...prev, cardEntry.id]));
|
||||
persistCart(nextQueue, new Set([...selectedCards, cardEntry.id]));
|
||||
};
|
||||
```
|
||||
|
||||
Add `loadScannerCart()` / `saveScannerCart({ scannedCards, selectedCardIds })` / `clearScannerCartStorage()` in `scanner-session.js`.
|
||||
|
||||
Hydrate on mount in `useScannerQueue` via `useState` initializer + `useEffect` debounced save on `[scannedCards, selectedCards]` changes.
|
||||
|
||||
**Checkout helpers** (used by Brief 4 footer CTAs):
|
||||
|
||||
```js
|
||||
const commitSelectedToOwned = async () => handleBulkAction('owned');
|
||||
const commitSelectedToCollection = async (collectionId) =>
|
||||
handleBulkAction('collection', collectionId);
|
||||
```
|
||||
|
||||
Export these plus `unprocessedCount` derived helper: `scannedCards.filter(c => !c.processed).length`.
|
||||
|
||||
After successful `handleBulkAction`, remove committed rows from `scannedCards` entirely (not `processed: true`) per D1/D6 — cart holds only uncommitted items.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `handleCardScanned` performs zero `fetch` calls (no `routeScannedCardToDestination`)
|
||||
- [ ] New enqueue auto-adds card `id` to `selectedCards`
|
||||
- [ ] Cart + selection survive `sessionStorage` round-trip within a tab (`test/lib/scanner-session.test.js`)
|
||||
- [ ] `test/lib/use-scanner-queue.test.js`: mock `scanner-route-api` and assert `handleCardScanned` never calls route helpers; assert `handleBulkAction('owned')` calls `addScannedCardToOwned` once per selected card
|
||||
- [ ] `clearScannerCartStorage()` clears persisted state
|
||||
- [ ] Existing `test/lib/scanner-session.test.js` cases still pass
|
||||
- [ ] No scope expansion
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Cart semantics are pure client state and can land before any UI work. Separating sessionStorage from the existing `localStorage` destination prefs avoids D7/localStorage anti-pattern. Removing committed rows instead of flipping `processed` simplifies the checkout sheet list.
|
||||
|
|
@ -1,124 +0,0 @@
|
|||
---
|
||||
convoy: scanner-mobile-checkout
|
||||
brief_number: 3
|
||||
depends_on: [2]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- components/scanner/ScannerCamera.js
|
||||
- components/scanner/ScannerCountPill.js
|
||||
- components/scanner/ScannerScanPeek.js
|
||||
- components/scanner/ScannerToast.js
|
||||
- lib/use-camera-scanner.js
|
||||
- lib/use-scanner-identification.js
|
||||
cross_brief_commitments:
|
||||
- brief: 4
|
||||
description: |
|
||||
`ScannerCamera` accepts orchestration props wired by Brief 4:
|
||||
`onBack`, `onOpenCheckout`, `onGalleryIdentify`, `latestPeekCard`,
|
||||
`cartCount`, `isCheckoutOpen`, `verificationPausedRef`. Defaults/no-ops
|
||||
keep the component renderable before Brief 4 lands. Brief 4 owns sheet
|
||||
open state and back-guard modal.
|
||||
- brief: 4
|
||||
description: |
|
||||
`useScannerIdentification` exports `identifyFromGalleryFile(file)` —
|
||||
thin adapter only; does not modify `pages/api/scan/identify.js` or
|
||||
`lib/scanner-card-identify.js` server contract.
|
||||
---
|
||||
|
||||
# Brief 3: Camera chrome, facing mode, scan peek, gallery adapter
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Refactor `ScannerCamera` into full-bleed immersive glass chrome (top/bottom bars, flash, camera swap, Review N pill, scan peek, gallery) and add rear/front `facingMode` support in `useCameraScanner`.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `components/scanner/ScannerCamera.js`
|
||||
- `components/scanner/ScannerCountPill.js`
|
||||
- `components/scanner/ScannerScanPeek.js` (new)
|
||||
- `components/scanner/ScannerToast.js`
|
||||
- `lib/use-camera-scanner.js`
|
||||
- `lib/use-scanner-identification.js` (gallery adapter + pause contract only)
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- Glass surfaces: `<GlassSurface tint="mid">` per UX brief; migrate hardcoded `rgba(0,0,0,0.55)` in `ScannerCamera` to tokens.
|
||||
- `ScannerToast`: replace `ICON_MAP` Unicode glyphs with inline SVG check/error (design-direction checklist).
|
||||
- `ScannerCountPill`: evolve to gradient **Review {N}** pill; keep `aria-label={`Review ${count} scanned cards`}`.
|
||||
- Flash: `flash.flashSupported && facingMode === 'environment'` (UX spec). Hide on front camera; turning to front must call `toggleFlash` off if torch was on.
|
||||
- Peek: new `ScannerScanPeek.js` — 3s auto-dismiss, `pointer-events-none` wrapper, single child button `pointer-events-auto`, tap calls `onOpenCheckout`.
|
||||
- Copy: toast message `"{card.name} added"` with `role="status"`.
|
||||
- Do **not** mount checkout sheet here — call `onOpenCheckout` only.
|
||||
- Identification pipeline files (`scanner-card-identify.js`, API routes) are out of scope.
|
||||
|
||||
## `useCameraScanner` shape (verified)
|
||||
|
||||
Current `startCamera` hardcodes `facingMode: 'environment'` (line ~119). Extend:
|
||||
|
||||
```js
|
||||
export function useCameraScanner({ onError, onVerifyCard, verificationPausedRef, facingMode = 'environment' }) {
|
||||
const [activeFacingMode, setActiveFacingMode] = useState(facingMode);
|
||||
// startCamera uses activeFacingMode in getUserMedia constraints
|
||||
const switchFacingMode = useCallback(() => {
|
||||
setActiveFacingMode((prev) => (prev === 'environment' ? 'user' : 'environment'));
|
||||
}, []);
|
||||
// useEffect: when activeFacingMode changes and stream exists, stopCamera + startCamera
|
||||
return { /* existing */, facingMode: activeFacingMode, switchFacingMode };
|
||||
}
|
||||
```
|
||||
|
||||
`verificationPausedRef` early-return already exists at line ~91 in the tracking interval — no change needed.
|
||||
|
||||
## Gallery adapter (verified — no existing file-picker path)
|
||||
|
||||
Add to `useScannerIdentification` return object:
|
||||
|
||||
```js
|
||||
const identifyFromGalleryFile = async (file) => {
|
||||
if (!file || verificationPausedRef?.current) return;
|
||||
const imageData = await readFileToImageData(file); // canvas draw; local helper in same file
|
||||
const authHeaders = getScanAuthHeaders();
|
||||
const result = await tryLayer1TextIdentify(imageData, authHeaders);
|
||||
const outcome = resolveIdentifyOutcome(result);
|
||||
const syntheticTracker = { id: `gallery-${Date.now()}`, status: 'verifying' };
|
||||
await applyIdentifyOutcome(syntheticTracker, imageData, outcome);
|
||||
};
|
||||
```
|
||||
|
||||
Import `tryLayer1TextIdentify`, `resolveIdentifyOutcome` from `./scanner-card-identify.js` (already exported — verified).
|
||||
|
||||
## `ScannerCamera` props contract (for Brief 4)
|
||||
|
||||
```js
|
||||
export default function ScannerCamera({
|
||||
queue,
|
||||
camera,
|
||||
identification,
|
||||
onBack,
|
||||
onOpenCheckout,
|
||||
onGalleryIdentify, // (file) => identification.identifyFromGalleryFile(file)
|
||||
latestPeekCard, // most recent unprocessed queue entry or null
|
||||
cartCount,
|
||||
isCheckoutOpen,
|
||||
verificationPausedRef,
|
||||
}) { /* ... */ }
|
||||
```
|
||||
|
||||
Remove: `deckMode`, `sessionDestination`, `onStopSession`, phase-based stop button. Back button calls `onBack` (Brief 4 shows leave modal).
|
||||
|
||||
Layout: viewport `min-h-[100dvh] max-md:rounded-none max-md:min-h-[100dvh]`; top bar with back / "Scan Cards" / gallery file input; bottom bar flash | status | Review N.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `switchFacingMode` restarts stream with toggled `facingMode`; flash hidden on `user`
|
||||
- [ ] `ScannerScanPeek` auto-dismisses ~3s; tap invokes `onOpenCheckout`
|
||||
- [ ] `ScannerToast` uses SVG icons, not Unicode glyphs
|
||||
- [ ] `identifyFromGalleryFile` calls existing `tryLayer1TextIdentify` — no API route changes
|
||||
- [ ] `ScannerCountPill` hidden when `count <= 0`; shows gradient Review pill when `count > 0`
|
||||
- [ ] No hex literals added in edited `.js` files
|
||||
- [ ] No scope expansion
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Camera chrome files are disjoint from `pages/scanner.js`, so this brief can land after the cart model without file conflicts. Gallery needs a thin hook adapter because no file-picker path exists today (boot-the-brief finding). Brief 4 wires props and pause ref when the sheet opens.
|
||||
|
|
@ -1,159 +0,0 @@
|
|||
---
|
||||
convoy: scanner-mobile-checkout
|
||||
brief_number: 4
|
||||
depends_on: [1, 2, 3]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- pages/scanner.js
|
||||
- pages/login.js
|
||||
- components/scanner/ScannerCheckoutSheet.js
|
||||
- components/scanner/ScannerReview.js
|
||||
- components/scanner/ReviewCardItem.js
|
||||
- test/components/ScannerCheckoutSheet.test.js
|
||||
cross_brief_commitments:
|
||||
- brief: 1
|
||||
description: |
|
||||
Passes `chrome="immersive"` to `<Layout>` on authenticated `/scanner`
|
||||
(mobile immersive; desktop uses default chrome per D3).
|
||||
- brief: 2
|
||||
description: |
|
||||
Calls `clearScannerCartStorage()` on confirmed leave. Uses
|
||||
`commitSelectedToOwned` / `commitSelectedToCollection` from queue hook.
|
||||
Does not reimplement sessionStorage persistence.
|
||||
- brief: 3
|
||||
description: |
|
||||
Wires `ScannerCamera` props (`onBack`, `onOpenCheckout`, `latestPeekCard`,
|
||||
`onGalleryIdentify`, `cartCount`, `isCheckoutOpen`, `verificationPausedRef`).
|
||||
Sets `verificationPausedRef.current = true` when checkout sheet or List
|
||||
picker modal is open (mobile); desktop side panel does not pause (UX spec).
|
||||
deletes: []
|
||||
---
|
||||
|
||||
# Brief 4: Page orchestration + checkout sheet
|
||||
|
||||
## Goal (1 sentence)
|
||||
|
||||
Collapse `/scanner` to scanning-first immersive flow, wire checkout sheet (mobile) / side panel (desktop), auth return URL (D2), and commit CTAs using vocab constants.
|
||||
|
||||
## Files in scope (do not edit anything else)
|
||||
|
||||
- `pages/scanner.js`
|
||||
- `pages/login.js`
|
||||
- `components/scanner/ScannerCheckoutSheet.js` (new)
|
||||
- `components/scanner/ScannerReview.js` (desktop `md+` side panel only)
|
||||
- `components/scanner/ReviewCardItem.js`
|
||||
- `test/components/ScannerCheckoutSheet.test.js` (new)
|
||||
|
||||
## Conventions to follow
|
||||
|
||||
- **Vocab:** `import { VOCAB } from '../lib/collection-vocabulary.js'` — primary `VOCAB.ADD_TO_MY_COLLECTION`, secondary `VOCAB.ADD_TO_LIST`. Never "Save to binder" / "Mark Owned".
|
||||
- **Sheet shell:** copy `ScannerDisambiguation.js` pattern (`fixed inset-0`, `glass-panel-strong`, `useFocusTrap`, Escape dismiss, `z-40` — disambiguation stays `z-50`).
|
||||
- **Modal primitive:** back-guard and List picker use `<Modal>` from `components/ui/Modal.js` (not `window.confirm`).
|
||||
- **Selection:** checkboxes always visible; all unprocessed IDs selected on first sheet open; new enqueue while open auto-selects (Brief 2 + local effect).
|
||||
- **Pause:** `verificationPausedRef.current = isCheckoutOpen || isListPickerOpen || identification.disambiguation` on mobile only.
|
||||
- **Auth:** `getUserFromRequest` not needed (page is client-only). Login redirect:
|
||||
|
||||
```js
|
||||
// pages/scanner.js — replace router.push('/login')
|
||||
router.push(`/login?returnUrl=${encodeURIComponent('/scanner')}`);
|
||||
|
||||
// pages/login.js — after successful login, before role redirect:
|
||||
const returnUrl = typeof router.query.returnUrl === 'string' ? router.query.returnUrl : null;
|
||||
if (returnUrl && returnUrl.startsWith('/')) {
|
||||
router.push(returnUrl);
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
- **D1:** after commit, stay on camera; empty cart closes sheet and resumes scanning.
|
||||
- **D4:** no deck destination in checkout UI.
|
||||
- **D6:** partial commit keeps sheet open with remaining rows.
|
||||
|
||||
## `pages/scanner.js` shape (verified — replace phase machine)
|
||||
|
||||
Remove `phase` state (`setup` / `scanning` / `review`). Default: camera always mounted when authenticated.
|
||||
|
||||
```js
|
||||
export default function Scanner() {
|
||||
const [isCheckoutOpen, setIsCheckoutOpen] = useState(false);
|
||||
const [isListPickerOpen, setIsListPickerOpen] = useState(false);
|
||||
const [showLeaveModal, setShowLeaveModal] = useState(false);
|
||||
const verificationPausedRef = useRef(false);
|
||||
// useScannerSession: keep scanDefaults only; drop Setup UI (D3)
|
||||
const queue = useScannerQueue({ user, scanDefaults, deckMode: null });
|
||||
// ...
|
||||
return (
|
||||
<Layout user={user} chrome="immersive">
|
||||
<div className="relative flex flex-col md:flex-row h-full min-h-0 max-md:fixed max-md:inset-0">
|
||||
<ScannerCamera
|
||||
queue={queue}
|
||||
camera={camera}
|
||||
identification={identification}
|
||||
onBack={() => unprocessedCount > 0 ? setShowLeaveModal(true) : router.back()}
|
||||
onOpenCheckout={() => setIsCheckoutOpen(true)}
|
||||
onGalleryIdentify={(file) => identification.identifyFromGalleryFile(file)}
|
||||
latestPeekCard={queue.scannedCards[0] ?? null}
|
||||
cartCount={unprocessedCount}
|
||||
isCheckoutOpen={isCheckoutOpen}
|
||||
verificationPausedRef={verificationPausedRef}
|
||||
/>
|
||||
{/* Mobile sheet */}
|
||||
<div className="md:hidden">
|
||||
{isCheckoutOpen && (
|
||||
<ScannerCheckoutSheet
|
||||
queue={queue}
|
||||
collections={queue.collections}
|
||||
onClose={() => setIsCheckoutOpen(false)}
|
||||
onOpenListPicker={() => setIsListPickerOpen(true)}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
{/* Desktop side panel */}
|
||||
<div className="hidden md:flex md:w-[360px] md:flex-shrink-0 md:border-l" style={{ borderColor: 'var(--border)' }}>
|
||||
<ScannerReview queue={queue} collections={queue.collections} variant="side-panel" />
|
||||
</div>
|
||||
<Modal open={showLeaveModal} /* ... */ />
|
||||
<Modal open={isListPickerOpen} title="Choose a List" /* ... */ />
|
||||
</div>
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Sync `verificationPausedRef` in `useEffect` when `isCheckoutOpen || isListPickerOpen || identification.disambiguation` (mobile: checkout open; desktop: only list picker + disambiguation per UX).
|
||||
|
||||
## `ScannerCheckoutSheet` responsibilities
|
||||
|
||||
- Header: `{N} cards scanned` + low-confidence subline when any row `confidence < 70`
|
||||
- Rows: `ReviewCardItem` with checkbox, confidence ring, qty stepper, overflow menu (remove / condition / foil)
|
||||
- Footer: primary `VOCAB.ADD_TO_MY_COLLECTION` with `(N)` when subset selected; secondary `VOCAB.ADD_TO_LIST`
|
||||
- Commit error: inline banner in footer, rows stay selected
|
||||
- `role="dialog"` `aria-modal="true"` `aria-labelledby`
|
||||
- On last item removed → `onClose()` + resume camera
|
||||
|
||||
## `ReviewCardItem` changes
|
||||
|
||||
- Add optional `selected`, `onToggleSelect`, `showCheckbox`, `confidence` ring props
|
||||
- Remove inline destination picker from row (destinations in sheet footer only)
|
||||
- `aria-label` on checkbox: `Select ${card.name}`; confidence in `aria-label` when `< 85`
|
||||
|
||||
## `ScannerReview` changes
|
||||
|
||||
- Support `variant="side-panel"` for desktop persistent panel (same row/footer semantics as sheet, no scrim)
|
||||
- Remove full-page empty state / "New Session" / deck progress from default path
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Opening `/scanner` authenticated shows camera immediately — no Setup phase (D3)
|
||||
- [ ] Unauthenticated redirect includes `returnUrl=/scanner`; login honors it (D2)
|
||||
- [ ] Mobile checkout sheet opens from Review N and peek; pauses identification under sheet
|
||||
- [ ] `commitSelectedToOwned` / List commit work; committed rows leave cart; camera resumes when empty (D1/D6)
|
||||
- [ ] Back with unprocessed cart shows `<Modal>` leave confirm; confirm calls `clearScannerCartStorage()` + `router.back()`
|
||||
- [ ] Desktop `md+` shows side panel with same CTA semantics; Layout sidebar visible
|
||||
- [ ] `test/components/ScannerCheckoutSheet.test.js`: renders header count, disabled primary when nothing selected, vocab labels present
|
||||
- [ ] No scope expansion
|
||||
|
||||
## Rationale (≤3 sentences)
|
||||
|
||||
Integration brief owns the sole `pages/scanner.js` writer after Layout and camera contracts exist. Login `returnUrl` is a two-line change required by D2 and verified absent today. Checkout sheet and desktop panel share row components but split shells to stay under 400 LOC.
|
||||
|
|
@ -47,11 +47,6 @@ PR #18; P1 #12 via `pick-a-name` PR #21) and **P1 #11.5 `fix-lint-baseline`**
|
|||
(PRs #61–#63, 2026-06-02), the P1 lane is complete. Lint is **0 problems**;
|
||||
CI `lint` is blocking (no `|| true` / `continue-on-error`).
|
||||
|
||||
**Post-hoc note (2026-08-15):** `reconcile-historical-add-scripts` implementer
|
||||
briefs B1–B6 closed the fresh-env onboarding gap in June 2026 (PRs #148–#153);
|
||||
Brief 7 (docs + verification runbook) landed two months later. The P1 lane was
|
||||
already complete when B1–B6 merged — this closure is documentation-only.
|
||||
|
||||
## P0 — ship-blockers (security)
|
||||
|
||||
These MUST land before any anonymous traffic touches the production URL.
|
||||
|
|
@ -420,7 +415,6 @@ Total: ~14 convoys to get from current state to public-launch-ready. Estimate 4-
|
|||
|
||||
Follow-ups surfaced mid-convoy or mid-PR that didn't fit the original launch sequence but need to land before public traffic. Listed in priority order; not all will be P0/P1 — most are CI / DX / hygiene polish.
|
||||
|
||||
- **`scanner-identify-upgrade`** (priority: P1 scanner accuracy; opened 2026-08-14). Umbrella after measuring `scan_attempts` (n=224, 2026-05-27–2026-08-12): L1 auto-match 5.8% of L1 vs the `add-real-ocr-layer` ≥70% target; L1 escalate 76.7%; L2 `not_a_card` 44.6% of Gemini calls; end-to-end auto-match 10.3%. Sub-convoys: `tighten-scan-identify-hot-path` → `improve-scan-card-detection` (queued since PR #38, never opened) → `scan-visual-catalog-search`. Worktree `tcg-vault-worktrees/scanner-identify-upgrade` on `convoy/scanner-identify-upgrade`. File-disjoint from `scanner-mobile-checkout` (chrome/cart). See `.convoys/scanner-identify-upgrade.md`.
|
||||
- **`rotate-default-admin`** — **RESOLVED 2026-06-13** by PR #141 (`scripts/rotate-admin-password.js`). The convoy chose option B from the architect's three-option menu (close as no-op / build script / build forced-rotation flow): a parameterized one-shot rotation script that's safer than "manually change via app" (audit-trail-preserving via `updated_at`) and lighter than building a first-login forced-rotation flow in the app (that heavier option is the deferred `force-admin-password-reset-flow` convoy). Script reads `POSTGRES_URL` + `ADMIN_NEW_PASSWORD` env vars, validates target row exists + has `role='admin'`, refuses to rotate non-admin rows, verifies the new hash matches the supplied plaintext via `bcrypt.compare` post-update, never echoes the password. AGENTS.md Gotcha #4 documents the rotation workflow. Sibling test users (alice/bob in `scripts/create-test-users.js`) intentionally NOT rotated (dev fixtures, not real auth surfaces).
|
||||
- **`delete-dead-lorcana-import`** — **RESOLVED 2026-06-02** by PR #59 (`8262fec`). Deleted `pages/api/cards/import-lorcana.js` and `scripts/import-lorcana.js`; no dedicated convoy file (cleanup tracked here only). Entry kept for audit trail.
|
||||
- **`tighten-visual-diff-path-filter`** — **RESOLVED 2026-05-26** by `tighten-visual-diff-path-filter` convoy, squash commit `ba95462` (PR #26). Single-edit `paths:` filter change in `.github/workflows/visual-diff.yml`: inserted `'!pages/api/**'` immediately after `'pages/**'` (order-sensitive per GitHub Actions' minimatch path-filter semantics — exclusions only fire after a prior include matches). Verified the YAML deserialization order at gate time (`['pages/**', '!pages/api/**', 'components/**', 'styles/**', 'tailwind.config.js', 'postcss.config.js']`). `preview-smoke.yml` left untouched (no `paths:` filter; intentionally fires on every PR). Diff: 2 files, +279 / -0 (1 YAML entry + inline comment block + the planning convoy file). **Post-merge verification still pending** — the only true verification is that the next API-only PR after this merges does NOT trigger `Screenshot diff`. PR #30 (`single-sql-client`, squash `c403ea4`) was the **first API-only PR post-merge** and its CI Checks tab showed `Screenshot diff: not triggered` — empirical confirmation that the `!pages/api/**` exclusion fires correctly. The next-API-only-PR success line was originally specified in the convoy file's § Verification plan as the deferred-to-post-merge gate; this is that confirmation. Entry kept (not removed) to preserve the audit trail. See `.convoys/tighten-visual-diff-path-filter.md` § As-shipped.
|
||||
|
|
@ -477,12 +471,10 @@ Follow-ups surfaced mid-convoy or mid-PR that didn't fit the original launch seq
|
|||
- **`purge-quick-login-from-loginpage`** — **RESOLVED 2026-05-29** by PR #56 (`e0218e4`). Quick Login removed from `pages/login.js`. See `.convoys/purge-quick-login-from-loginpage.md` § As-shipped.
|
||||
- **`purge-neondatabase-serverless-fully`** — **RESOLVED 2026-06-02** by PR #57 (`5115683`). `@neondatabase/serverless` removed from `package.json`; operational scripts use `@vercel/postgres`. Historical `scripts/add-*` / `fix-*` / `seed-*` graveyard unchanged per no-go-zones. Entry kept for audit trail.
|
||||
- **`wire-migrate-into-ci`** (priority: P2 CI infra). Surfaced 2026-05-26 by `migration-tool` (PR #32) — D6 deferral. Add a CI job that runs `npm run migrate up` against a test DB (either a dedicated Neon branch + `MIGRATE_TEST_DATABASE_URL` secret with branch-reset logic, or a Postgres service container with a ~30s container-start tax). Catches syntactically-invalid migrations + most logical errors at PR time. Currently, the first signal that a new migration is broken is the developer's local `npm run migrate up` against their dev branch (or post-deploy on Vercel). Documented in `.convoys/migration-tool.md` § R3.
|
||||
- **`reconcile-historical-add-scripts`** — **RESOLVED 2026-06-14** (B1–B6 via PRs #148–#153; B7 docs closure 2026-08-15). Six reconciliation migrations capture historical add-script DDL so fresh Neon branches onboard via `npm install` → `npm run setup-db` alone. Operator verification runbook at `docs/MIGRATION_VERIFICATION_RUNBOOK.md`. See `.convoys/reconcile-historical-add-scripts.md` § As-shipped. Entry kept for audit trail.
|
||||
- **`retire-graveyard-scripts-after-audit`** (priority: P3 polish; **UNBLOCKED 2026-08-15** by `reconcile-historical-add-scripts` § As-shipped). Surfaced 2026-05-26 by `migration-tool` (PR #32). Once the migration history captures all historical effects, the legacy `scripts/add-*.js` / `fix-*.js` / `seed-*.js` files can be deleted (or moved to `scripts/historical/`). They remain no-go-zones until that cleanup convoy lands. Documented in `.convoys/migration-tool.md` § Follow-ups.
|
||||
- **`reconcile-historical-add-scripts`** (priority: P1 quality — needed for fresh-env onboarding). Surfaced 2026-05-26 by `migration-tool` (PR #32). Fold the effects of the 27 historical `scripts/add-*.js` / `fix-*.js` / `seed-*.js` jobs into the migration history so a brand-new Neon branch can be onboarded by `npm install` → `npm run setup-db` alone (without manually replaying the historical scripts). Multi-PR; ideally one migration per logical change, generated by reading the scripts' SQL and re-shaping into idempotent `pgm.sql(...)` blocks (with `IF NOT EXISTS` / `IF EXISTS` guards so re-application is safe). Documented in `.convoys/migration-tool.md` § R1.
|
||||
- **`retire-graveyard-scripts-after-audit`** (priority: P3 polish; **blocked on `reconcile-historical-add-scripts`**). Surfaced 2026-05-26 by `migration-tool` (PR #32). Once the migration history captures all historical effects, the legacy `scripts/add-*.js` / `fix-*.js` / `seed-*.js` files can be deleted (or moved to `scripts/historical/`). They remain no-go-zones until that cleanup convoy lands. Documented in `.convoys/migration-tool.md` § Follow-ups.
|
||||
- **`audit-node-pg-migrate-transitive-deps`** (priority: P3 hygiene). Surfaced 2026-05-26 by `migration-tool` (PR #32) — R5 in the convoy file. `npm audit` reports 11 vulnerabilities (6 moderate, 5 high) coming from `node-pg-migrate@8.0.4`'s `glob@~11.1.0` + `yargs@~17.7.0` transitive deps (older `brace-expansion`, `minimatch`, `picomatch` versions with known advisories). All in dev-only paths; the migration tool runs in scripts/CI, never in the deployed Next.js bundle, and the affected APIs (glob's shell-injection CLI; brace-expansion's ReDoS) are not exercised by node-pg-migrate's call sites. Surface only if a security audit specifically flags this surface, or if `node-pg-migrate` ships a v9 that updates the transitive tree.
|
||||
- **`add-migration-template`** (priority: P3 DX). Surfaced 2026-05-26 by `migration-tool` (PR #32). Add a custom template via `--template-file-name` so generated migrations include the project's preferred docstring shape + a reminder about `docs/SCHEMA_MAP.md` updates. Surface if migration authoring proves inconsistent.
|
||||
- **`unify-user-avatar-column`** (priority: P3 polish). Surfaced 2026-06-14 by `reconcile-historical-add-scripts` architect Finding 2. `users` table has two avatar columns: `profile_image_url` (from `add-user-profile-columns.js`) and `avatar_url` (from `add-user-profile-fields.js`). Both are added by B5's migration for fresh-env parity; runtime may read either. Cleanup: audit which column each caller reads, pick one canonical column, migrate + drop the other.
|
||||
- **`drop-dead-cards-columns`** (priority: P3 polish). Surfaced 2026-06-14 by `reconcile-historical-add-scripts` architect Finding 3. `cards.quantity` and `cards.favorited` are dead columns per `docs/SCHEMA_MAP.md` § Smells #3; still added by B1's migration for fresh-env parity. Cleanup: query-trace audit to confirm zero reads/writes, then a `DROP COLUMN` migration.
|
||||
|
||||
### Scanner audit portfolio (2026-05-27)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,340 +0,0 @@
|
|||
---
|
||||
name: tighten-scan-identify-hot-path
|
||||
classification: feature
|
||||
success_metric: |
|
||||
After ship, a new scan_attempts window shows L1 escalate ≤40% of L1
|
||||
(was 76.7%), L1 matched ≥25% of L1 (was 5.8%), and first identify
|
||||
attempt starts in ≤1.2s of tracking (was 3.5s). L2 p50 stays ≤1.8s.
|
||||
skip:
|
||||
- ia
|
||||
- ui-design
|
||||
- visual
|
||||
- flag
|
||||
status: shipped
|
||||
created: 2026-08-14
|
||||
depends_on:
|
||||
- add-real-ocr-layer
|
||||
umbrella: scanner-identify-upgrade
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
|
||||
# Convoy: tighten-scan-identify-hot-path
|
||||
|
||||
Phase 1 of `scanner-identify-upgrade`. Make the **existing** two-layer
|
||||
pipeline faster and more unique-match capable. No new vendors, no
|
||||
detection rewrite, no embeddings.
|
||||
|
||||
## Why
|
||||
|
||||
Live telemetry (see umbrella) says Layer-1 is fast (p50 158ms) and
|
||||
almost useless as an identifier (5.8% auto-match, 76.7% escalate). The
|
||||
user still waits 3.5s of hold-still before that cheap path runs. L2
|
||||
Gemini is 1.7s p50 and spends a second token on every disambiguation
|
||||
refine. Collector number — the unique printing key L2 already uses —
|
||||
is never read on L1.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- **Hold-still constants** in `lib/scanner-card-detection.js`:
|
||||
`MIN_FIRST_SEEN_MS_FOR_VERIFY` 2500 → ~800;
|
||||
`MIN_STABLE_COUNT_FOR_VERIFY` 6 → 3. Keep tests in
|
||||
`test/lib/scanner-card-detection.test.js` in lockstep.
|
||||
- **Name-strip OCR mode:** Tesseract PSM 7 (single line), JPEG quality
|
||||
0.92 on the crop used for OCR (`lib/ocr-worker.js`,
|
||||
`captureCardRegionFromVideo` quality if shared).
|
||||
- **Collector-number strip:** second crop of the bottom ~18% of the
|
||||
card; pass number (+ optional set hint) into `matchTextInCatalog`.
|
||||
When name + number uniquely match a `cards` row, auto-match even if
|
||||
many printings share the name.
|
||||
- **Structured Gemini output** in `lib/scan-vision.js`:
|
||||
`response_format` JSON schema (or Gateway equivalent). Delete the
|
||||
confidence-30 regex fallback as the success path; keep a hard parse
|
||||
error → `needs_input`.
|
||||
- **Model A/B:** default stays `google/gemini-2.5-flash-lite`. Document
|
||||
and allow `SCAN_VISION_MODEL=google/gemini-3.1-flash-lite` (GA on
|
||||
Vercel AI Gateway, ~2.5× input price). Do not flip prod default in
|
||||
this convoy unless Architect + a short identify bake-off say so.
|
||||
- **Stop automatic L2 refine** in `use-scanner-identification.js` when
|
||||
L1 already returned a printing list. User picks; Gemini refine is
|
||||
opt-in or only when L1 had no set/number hint.
|
||||
- **`docs/SCHEMA_MAP.md`:** `scan_attempts.layer` is 1 = Tesseract
|
||||
(shipped), not "Tesseract future".
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Detector / OpenCV / YOLO / perspective warp →
|
||||
`improve-scan-card-detection`.
|
||||
- pgvector / CLIP / catalog embeddings →
|
||||
`scan-visual-catalog-search`.
|
||||
- Changing `checkScanRateLimit` (5/min). Revisit after re-measure.
|
||||
- Scanner chrome, cart, checkout (`scanner-mobile-checkout`).
|
||||
- Replacing `tesseract.js`.
|
||||
|
||||
## Roles invoked
|
||||
|
||||
1. `role-ux-reviewer` — hold-still feel; when the picker still appears;
|
||||
no new screens.
|
||||
2. `role-architect` — ratify constant values, L1 match rules when a
|
||||
collector number is present, JSON schema shape, whether the model
|
||||
default flips. Write briefs + `slice_dependencies`.
|
||||
3. `role-implementer` — per brief.
|
||||
4. Audit: `role-reviewer` + `role-security-auditor`. Skip design-system
|
||||
+ a11y unless a brief unexpectedly touches `components/`.
|
||||
|
||||
## Todos
|
||||
|
||||
- [x] UX: confirm 800ms / 3-frame gate does not cause double-scans
|
||||
- [x] Architect: briefs + match-rule when number is present
|
||||
- [x] Brief A — detection constants + tests
|
||||
- [x] Brief B — OCR strips (name PSM 7 + collector number) +
|
||||
`card-text-match.js` / `identify-by-text`
|
||||
- [x] Brief C — `scan-vision.js` JSON schema + optional model id
|
||||
- [x] Brief D — skip automatic disambiguation Gemini refine
|
||||
- [x] SCHEMA_MAP layer-1 wording
|
||||
- [x] Re-query `scan_attempts` after preview traffic (2026-08-15 — metrics unvalidated; see umbrella § Post-ship telemetry)
|
||||
|
||||
## Post-ship (PR #156, 2026-08-14)
|
||||
|
||||
**Shipped:** faster verify gates, collector-number L1, structured Gemini JSON,
|
||||
skip L1 disambiguation refine.
|
||||
|
||||
**Telemetry (n=250 all-time):** L1 matched 5.4% (target ≥25%); L1 escalate
|
||||
78.4% (target ≤40%). Gate latency goal met (~158 ms L1 p50). Aug 15 session
|
||||
(n=26) showed 0% L1 match — OCR strips got noisier post-warp, not better.
|
||||
|
||||
**Verdict:** Machinery shipped; L1 text path remains insufficient for the
|
||||
umbrella 50% auto-match goal. Phase 3 visual kNN is the intended fix.
|
||||
|
||||
## Likely file ownership (Architect will lock)
|
||||
|
||||
| Area | Files |
|
||||
| --- | --- |
|
||||
| Gates | `lib/scanner-card-detection.js`, `test/lib/scanner-card-detection.test.js` |
|
||||
| OCR | `lib/ocr-worker.js` |
|
||||
| L1 match | `lib/card-text-match.js`, `pages/api/cards/identify-by-text.js` |
|
||||
| L2 vision | `lib/scan-vision.js`, `pages/api/scan/identify.js` |
|
||||
| Refine | `lib/use-scanner-identification.js`, `lib/scanner-card-identify.js` |
|
||||
| Docs | `docs/SCHEMA_MAP.md` |
|
||||
|
||||
Briefs A and C are file-disjoint and can run in parallel. B depends on
|
||||
nothing if it does not retouch detection constants. D depends on B
|
||||
(needs L1 payload shape).
|
||||
|
||||
## Multitask dispatch
|
||||
|
||||
Planning: UX → Architect (serial).
|
||||
|
||||
After Architect, if `slice_dependencies` marks A+C `depends_on: []`:
|
||||
|
||||
```
|
||||
/multitask role-implementer briefs A, C
|
||||
```
|
||||
|
||||
Then B, then D.
|
||||
|
||||
Audit group id: `audit-tighten-scan-identify-hot-path-<pr>`.
|
||||
|
||||
## CI impact
|
||||
|
||||
| Workflow / job | Behavior |
|
||||
| --- | --- |
|
||||
| `ci.yml` test | Fires — detection + identify unit tests change |
|
||||
| `visual-diff.yml` | Should **not** fire if `components/` / `pages/` / `styles/` untouched |
|
||||
| `preview-smoke.yml` | Fires |
|
||||
| `forbidden-client-side-llm-keys` | Must stay green — no client Gemini URLs |
|
||||
|
||||
## Operator action
|
||||
|
||||
Optional: set `SCAN_VISION_MODEL=google/gemini-3.1-flash-lite` on a
|
||||
preview to bake off against 2.5 Flash Lite. Leave prod on 2.5 until
|
||||
the bake-off.
|
||||
|
||||
## Conductor notes
|
||||
|
||||
Do not treat Tesseract replacement as in-scope if L1 escalate stays
|
||||
high after collector-number matching — that is a crop/detection
|
||||
problem (#2) or a visual-search problem (#3), not an OCR-engine
|
||||
problem. The six historical L1 matches already show Tesseract can
|
||||
read a name when the crop is clean; it cannot pick a printing.
|
||||
|
||||
## UX
|
||||
|
||||
No new routes or screens. Changes are timing + fewer automatic Gemini
|
||||
calls during disambiguation.
|
||||
|
||||
### Existing components to reuse
|
||||
|
||||
- `ScannerDisambiguation` (`components/scanner/ScannerDisambiguation.js`) —
|
||||
printing picker when L1/L2 cannot unique-match.
|
||||
- `ScannerToast` / status copy around tracked card (`components/scanner/ScannerCamera.js`)
|
||||
— continue showing detecting → verifying → found without new chrome.
|
||||
- `ScanDisambiguationDialog` pattern if still referenced — do not fork a
|
||||
second picker.
|
||||
|
||||
### Design direction alignment
|
||||
|
||||
Liquid Glass tokens unchanged. No new overlays. Faster identify should
|
||||
feel like the camera "wakes up" sooner (H1 visibility of system status).
|
||||
|
||||
### Patterns to follow
|
||||
|
||||
- Disambiguation stays a bottom sheet / modal pause (`verificationPausedRef`
|
||||
already wired in `use-scanner-identification.js`).
|
||||
- Error toasts debounced via `reportScannerError` (4s gap) — keep that
|
||||
when tightening gates so double-failures do not spam.
|
||||
|
||||
### A11y constraints
|
||||
|
||||
- No new interactive controls in this convoy.
|
||||
- Existing disambiguation list must remain keyboard-selectable (hand off
|
||||
unchanged to a11y auditor if Brief D touches the sheet).
|
||||
|
||||
### Interaction patterns
|
||||
|
||||
| Pattern | Requirement | Heuristic |
|
||||
| --- | --- | --- |
|
||||
| Hold-still gate | **required** — 800ms + 3 stable frames; user sees brackets sooner | H1 feedback |
|
||||
| Auto-match | **required** — collector number should skip picker for multi-printing names | H6 recognition vs recall |
|
||||
| Disambiguation refine | **required** — stop silent second Gemini call when L1 already opened picker; user tap only | H3 user control |
|
||||
| Rate-limit toast | **required** — unchanged copy when L2 throttled | H9 error recovery |
|
||||
| Loading during verify | **nice-to-have** — optional subtle "Reading…" on card status if trivial | H1 |
|
||||
|
||||
### Anti-patterns
|
||||
|
||||
- Adding a setup screen or settings toggle for gate timing (H4 consistency).
|
||||
- Auto-picking a printing without number evidence when multiple exact-name
|
||||
rows exist (H6).
|
||||
- Blocking the camera on L1 OCR worker load (H1 — worker stays async).
|
||||
|
||||
### Mobile / responsive
|
||||
|
||||
Gate timing applies equally on phone and desktop; no viewport-specific
|
||||
branches in this convoy.
|
||||
|
||||
## Architecture
|
||||
|
||||
### File plan
|
||||
|
||||
| File | Action | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `lib/scanner-card-detection.js` | modified | 800ms / 3-frame verify gates |
|
||||
| `test/lib/scanner-card-detection.test.js` | modified | Lock new constants |
|
||||
| `lib/ocr-worker.js` | modified | PSM 7 name strip + bottom collector strip |
|
||||
| `lib/card-text-match.js` | modified | Name + collector number unique match |
|
||||
| `pages/api/cards/identify-by-text.js` | modified | Accept `cardNumber` body field |
|
||||
| `test/lib/card-text-match.test.js` | new | Unit tests for number path (mock-free helpers) |
|
||||
| `lib/scanner-card-identify.js` | modified | Pass number to L1; JPEG 0.92; `fromLayer1` flag |
|
||||
| `lib/scan-vision.js` | modified | JSON schema response; stricter parse |
|
||||
| `pages/api/scan/identify.js` | modified | Handle vision parse failures → needs_input |
|
||||
| `lib/use-scanner-identification.js` | modified | Skip auto Gemini refine when `fromLayer1` |
|
||||
| `docs/SCHEMA_MAP.md` | modified | Layer 1 = Tesseract (shipped) |
|
||||
|
||||
### API surface
|
||||
|
||||
**POST `/api/cards/identify-by-text`** (modified)
|
||||
|
||||
- Auth: `getUserFromRequest` → 401
|
||||
- Body: `{ ocrText, ocrConfidence?, cardNumber?, game? }`
|
||||
- Response: unchanged envelope + optional `cardNumber` echo in `ocr` meta
|
||||
- Rate limit: none (unchanged)
|
||||
|
||||
**POST `/api/scan/identify`** (modified behavior only)
|
||||
|
||||
- On vision JSON parse failure: 200 with `needsUserInput: true` instead of
|
||||
silent regex fallback at confidence 30
|
||||
|
||||
### Schema diff
|
||||
|
||||
No migration. `scan_attempts.layer` semantics documented only.
|
||||
|
||||
### Test plan
|
||||
|
||||
- Update `scanner-card-detection.test.js` thresholds (800ms, stable 3).
|
||||
- New `card-text-match.test.js` for `extractCollectorNumberCandidate` and
|
||||
collector-aware disambiguation resolution (pure functions exported for test).
|
||||
- Extend `scanner-card-identify.test.js` for `fromLayer1` disambiguation
|
||||
payload if added to pure helpers.
|
||||
- Run `npm run test:run` + `npm run lint`.
|
||||
|
||||
### Risks
|
||||
|
||||
| Risk | Mitigation |
|
||||
| --- | --- |
|
||||
| Faster gate double-scans same card | `scanAttempts < 1` + tracker negative state unchanged |
|
||||
| OCR number strip reads set symbol garbage | Normalize with `extractCollectorNumberCandidate`; fall back to name-only |
|
||||
| Gateway rejects `response_format` | Catch 400, log once, fall back to prose prompt (Architect: implementer may feature-detect) |
|
||||
| L1 skip-refine hides catalog-gap auto-submit | Refine still runs for L2 disambiguation only |
|
||||
|
||||
### Decomposition
|
||||
|
||||
| Brief # | Title | Files | Depends on | Size |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | Faster verify gates | detection + test | — | S |
|
||||
| 2 | Collector number L1 | ocr-worker, card-text-match, identify-by-text, scanner-card-identify, test | — | M |
|
||||
| 3 | Structured vision JSON | scan-vision, identify API | — | S |
|
||||
| 4 | Skip L1 disambiguation refine | use-scanner-identification, SCHEMA_MAP | 2 | S |
|
||||
|
||||
### Slice dependencies
|
||||
|
||||
```yaml
|
||||
slice_dependencies:
|
||||
- brief: 1
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/scanner-card-detection.js
|
||||
- test/lib/scanner-card-detection.test.js
|
||||
- brief: 2
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/ocr-worker.js
|
||||
- lib/card-text-match.js
|
||||
- pages/api/cards/identify-by-text.js
|
||||
- lib/scanner-card-identify.js
|
||||
- test/lib/card-text-match.test.js
|
||||
- brief: 3
|
||||
depends_on: []
|
||||
files:
|
||||
- lib/scan-vision.js
|
||||
- pages/api/scan/identify.js
|
||||
- brief: 4
|
||||
depends_on: [2]
|
||||
files:
|
||||
- lib/use-scanner-identification.js
|
||||
- docs/SCHEMA_MAP.md
|
||||
```
|
||||
|
||||
### Decisions (post-UX)
|
||||
|
||||
| # | Decision |
|
||||
| --- | --- |
|
||||
| D1 | Gate values: `MIN_FIRST_SEEN_MS_FOR_VERIFY = 800`, `MIN_STABLE_COUNT_FOR_VERIFY = 3`. |
|
||||
| D2 | Collector strip: bottom 18% of crop; PSM 7 for both strips. |
|
||||
| D3 | When exact-name multiple printings AND parsed collector number matches exactly one row → auto-match. |
|
||||
| D4 | `SCAN_VISION_MODEL` default stays `google/gemini-2.5-flash-lite`; structured JSON either way. |
|
||||
| D5 | Auto Gemini refine skipped when disambiguation opened from L1 (`result.layer === 1`). |
|
||||
|
||||
Human gate 1: **approved** (operator requested full pipeline run 2026-08-14).
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
convoy: tighten-scan-identify-hot-path
|
||||
brief_number: 1
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/scanner-card-detection.js
|
||||
- test/lib/scanner-card-detection.test.js
|
||||
---
|
||||
|
||||
# Brief 1: Faster verify gates
|
||||
|
||||
## Goal
|
||||
|
||||
Cut hold-still wait from 3.5s to ~1.4s by lowering verify gate constants.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `MIN_FIRST_SEEN_MS_FOR_VERIFY = 800`
|
||||
- [ ] `MIN_STABLE_COUNT_FOR_VERIFY = 3`
|
||||
- [ ] Tests updated and green
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
convoy: tighten-scan-identify-hot-path
|
||||
brief_number: 2
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/ocr-worker.js
|
||||
- lib/card-text-match.js
|
||||
- pages/api/cards/identify-by-text.js
|
||||
- lib/scanner-card-identify.js
|
||||
- test/lib/card-text-match.test.js
|
||||
---
|
||||
|
||||
# Brief 2: Collector number on Layer 1
|
||||
|
||||
## Goal
|
||||
|
||||
OCR name + collector number strips; unique-match printings when number resolves one row.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] PSM 7 on name strip; bottom 18% number strip
|
||||
- [ ] `matchTextInCatalog` accepts `cardNumber`
|
||||
- [ ] identify-by-text passes `cardNumber`
|
||||
- [ ] JPEG capture quality 0.92 for OCR path
|
||||
- [ ] Unit tests for number extraction helper
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
convoy: tighten-scan-identify-hot-path
|
||||
brief_number: 3
|
||||
depends_on: []
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/scan-vision.js
|
||||
- pages/api/scan/identify.js
|
||||
---
|
||||
|
||||
# Brief 3: Structured Gemini JSON
|
||||
|
||||
## Goal
|
||||
|
||||
Request JSON schema from AI Gateway; fail loud on parse errors.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `response_format` json_schema on gateway call
|
||||
- [ ] No confidence-30 regex success path
|
||||
- [ ] identify route returns needsUserInput on parse failure
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
convoy: tighten-scan-identify-hot-path
|
||||
brief_number: 4
|
||||
depends_on: [2]
|
||||
recommended_model: composer-2.5-fast
|
||||
model_tier: fast
|
||||
files:
|
||||
- lib/use-scanner-identification.js
|
||||
- docs/SCHEMA_MAP.md
|
||||
---
|
||||
|
||||
# Brief 4: Skip L1 disambiguation refine
|
||||
|
||||
## Goal
|
||||
|
||||
Do not auto-call Gemini when L1 already opened the printing picker.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `fromLayer1` on disambiguation state when `result.layer === 1`
|
||||
- [ ] useEffect refine skipped when `fromLayer1`
|
||||
- [ ] SCHEMA_MAP documents layer 1 = Tesseract
|
||||
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
name: role-a11y-auditor
|
||||
description: >-
|
||||
Accessibility audit on a UI diff against WCAG 2.2 (Level AA). Read-only.
|
||||
Runs `[skills/accessibility-audit](../../../accessibility-audit/SKILL.md)`
|
||||
for the rubric + report template. Use after the implementer's PR draft on
|
||||
PRs that touch UI files. Safe to run in parallel with role-reviewer +
|
||||
role-security-auditor + role-design-system-auditor via Cursor 3.2 /multitask.
|
||||
Accessibility audit on a UI diff. Checks for missing labels, keyboard
|
||||
navigation, focus management, color contrast, semantic HTML, and ARIA
|
||||
correctness. Read-only. Use after the implementer's PR draft on PRs that
|
||||
touch UI files. Does not require a browser MCP — works from the diff +
|
||||
static analysis. Safe to run in parallel with role-reviewer +
|
||||
role-design-system-auditor via Cursor 3.2 /multitask.
|
||||
multitask: audit-fanout
|
||||
model: cursor-grok-4.5-high
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -20,59 +20,86 @@ After `role-design-system-auditor` on UI-touching PRs. Skip when convoy frontmat
|
|||
## Inputs
|
||||
|
||||
- The PR diff (UI files only).
|
||||
- The convoy's UX section (a11y constraints listed there — verify each one).
|
||||
- Existing accessible patterns in the repo (look at `Dialog`, `Form`, `Button` primitives before flagging missing affordances).
|
||||
- `[skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md)` — the audit rubric, severity scale, and 5-layer framework.
|
||||
- The convoy's UX section (which already lists a11y constraints — verify the implementer satisfied them).
|
||||
- Existing accessible patterns in the repo (look at existing `Dialog`, `Form`, `Button` primitives).
|
||||
|
||||
## Outputs
|
||||
|
||||
A structured audit report following the template at `skills/accessibility-audit/templates/audit-report.md`. Posted as:
|
||||
A structured comment for the PR Health rollup:
|
||||
|
||||
- A PR comment when GitHub is the surface, OR
|
||||
- An Echodo `document` (Phase 2b: `create_task_from_template({template: "a11y-audit", ...})`) when MCP is reachable.
|
||||
```markdown
|
||||
## A11y Audit
|
||||
|
||||
Per `[skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md)` step 7 — both paths produce the same shape.
|
||||
| Check | Status | Count |
|
||||
| --- | --- | --- |
|
||||
| Labels | ✅ / ❌ | <N> |
|
||||
| Keyboard nav | ✅ / ❌ | <N> |
|
||||
| Focus management | ✅ / ❌ | <N> |
|
||||
| Color contrast | ✅ / ⚠️ | <N> |
|
||||
| Semantic HTML | ✅ / ❌ | <N> |
|
||||
| ARIA correctness | ✅ / ⚠️ | <N> |
|
||||
| UX constraint match | ✅ / ❌ | <N> |
|
||||
|
||||
### Critical (must fix)
|
||||
- <file:line> — <issue> — <fix>
|
||||
...
|
||||
|
||||
### Warnings (recommended)
|
||||
- <file:line> — <issue> — <fix>
|
||||
...
|
||||
|
||||
### Notes
|
||||
- ...
|
||||
```
|
||||
|
||||
## Checklist (apply per file)
|
||||
|
||||
1. **Labels**: every `<input>`, `<select>`, `<textarea>`, `<button>` has either visible text, `aria-label`, or an associated `<label htmlFor=...>`.
|
||||
2. **Icon-only buttons**: have `aria-label` or visually-hidden text.
|
||||
3. **Keyboard navigation**: any `onClick` on a non-button/anchor element has `onKeyDown` (Enter + Space) and `tabIndex={0}` and `role="button"` (or be a real button).
|
||||
4. **Focus management**: dialogs trap focus; modals return focus on close; route changes move focus to the heading.
|
||||
5. **Color contrast**: text on backgrounds meets 4.5:1 (large text 3:1). Hardcoded colors that we can't measure → ⚠️.
|
||||
6. **Semantic HTML**: use `<button>` not `<div onClick>`, `<nav>` for navigation, `<main>` for primary content, heading hierarchy `<h1>` → `<h2>` → `<h3>` (no skipping).
|
||||
7. **ARIA correctness**: `aria-expanded` on toggles, `aria-current="page"` on active nav items, `aria-live` on async-updating regions, `role="alert"` on error messages.
|
||||
8. **UX constraint match**: cross-reference the UX section's a11y constraints — did the implementer satisfy each one?
|
||||
|
||||
## Severity
|
||||
|
||||
- **Critical**: missing labels on form inputs, no keyboard handler on click-only div, missing focus trap on modal, missing alt text on informative images.
|
||||
- **Warning**: heading hierarchy skip, missing `aria-current`, color-contrast that requires runtime measurement, missing live region on async updates.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Get UI diff (`git diff --name-only` filtered to UI extensions).
|
||||
1. Get UI diff.
|
||||
2. Read the convoy's UX section once to know what was promised.
|
||||
3. **Read `[skills/accessibility-audit/SKILL.md](../../../accessibility-audit/SKILL.md)`** if not already in context. Walk the 5 layers in order for each touched surface.
|
||||
4. Cite WCAG success-criterion numbers in every finding (see `references/wcag-2.2-checklist.md`).
|
||||
5. Assign severity 0-4 per the skill's rubric. Severity ≥ 3 spawns a child task in Phase 2b.
|
||||
6. Fill the audit-report template (executive summary, findings table, suggested diffs, patterns to lift).
|
||||
7. Post the report. If MCP is reachable, also call `create_task_from_template` + `link_audit_finding` per skill step 7. On failure, queue to `.convoys/.pending-mcp-sync.jsonl`.
|
||||
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
Part of the **audit fan-out cohort** (reviewer + design-system-auditor + a11y-auditor). All three read the same diff, emit independent reports, modify no code. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
|
||||
Pass the shared `multitask_group` id in metrics. Convention: `audit-<convoy>-<pr>`. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
3. For each changed UI file: read the current state of the file (post-diff), then walk the checklist.
|
||||
4. Build the comment. Cap at 8 critical + 8 warnings.
|
||||
5. If clean: ✅ across the board with a one-line note.
|
||||
|
||||
## What this role does NOT do
|
||||
|
||||
- Run axe-core in a browser — that's a CI job (`accessibility-audit` step 2 mentions automated checks; CI runs them, this role consumes their output).
|
||||
- Test screen readers manually — out of scope for static analysis. Recommend in findings if needed.
|
||||
- Run axe-core in a browser (that's a CI job, see `.github/workflows/preview-smoke.yml` if present).
|
||||
- Test screen readers manually — beyond static analysis scope.
|
||||
- Audit non-UI changes — server / API / config diffs are out of scope.
|
||||
- Replicate the rubric inline — the rubric lives in the skill. This role orchestrates; it does not carry the checklist.
|
||||
|
||||
## Hand-off
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
Message: *"A11y audit complete. N findings (sev ≥ 3: M, sev < 3: K). Report: `<path>` or `<echodo-url>`. Recommend fixing sev ≥ 3 before merge."*
|
||||
Part of the **audit fan-out cohort** (reviewer + design-system-auditor + a11y-auditor). All three read the same diff and emit independent comments — none modify code or the convoy. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
|
||||
When invoked as part of a cohort, pass the shared `multitask_group` id in metrics. Convention: `audit-<convoy>-<pr>`. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
|
||||
## Metrics
|
||||
|
||||
After publishing:
|
||||
After publishing the audit comment, emit one event:
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-a11y-auditor convoy=<slug> duration_s=<seconds> model=cursor-grok-4.5-high model_tier=fast [multitask_group=audit-<convoy>-<pr>]
|
||||
bash scripts/log-convoy-event.sh role=role-a11y-auditor convoy=<slug> duration_s=<seconds> [multitask_group=audit-<convoy>-<pr>]
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Demanding ARIA on already-semantic HTML (e.g. `aria-label` on `<button>` with visible text) → wrong, redundant. See skill anti-patterns.
|
||||
- Demanding ARIA on already-semantic HTML (e.g. `aria-label` on a `<button>` that has visible text) → wrong, that's redundant.
|
||||
- Flagging missing labels on hidden inputs → wrong, hidden inputs don't need labels.
|
||||
- Vague feedback ("improve a11y") → wrong. Every finding cites a WCAG criterion + a file:line + a fix.
|
||||
- Carrying the rubric inline in this role file → wrong. Read the skill.
|
||||
- Vague feedback ("improve a11y") → wrong, every finding needs a file:line and a specific fix.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ description: >-
|
|||
Must run sequentially — decomposition output enables downstream
|
||||
implementer fan-out via Cursor 3.2 /multitask.
|
||||
multitask: single
|
||||
model: composer-2.5
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -61,8 +60,6 @@ Then create one **implementer brief** per row of the decomposition, as a separat
|
|||
convoy: <slug>
|
||||
brief_number: <N>
|
||||
depends_on: [<other brief numbers>]
|
||||
recommended_model: composer-2.5
|
||||
model_tier: standard
|
||||
files:
|
||||
- <path/to/file1>
|
||||
- <path/to/file2>
|
||||
|
|
@ -185,7 +182,7 @@ If the convoy's plan needs to change after `role-architect` has run (e.g. a user
|
|||
After writing the brief files, emit one event. Shell access is restricted to this single command.
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-architect convoy=<slug> duration_s=<seconds> model=composer-2.5 model_tier=standard
|
||||
bash scripts/log-convoy-event.sh role=role-architect convoy=<slug> duration_s=<seconds>
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ description: >-
|
|||
for downstream roles, and hands off to the next role. Use when a new feature,
|
||||
bug fix, or epic is being kicked off and the work has not yet been scoped.
|
||||
multitask: single
|
||||
model: composer-2.5-fast
|
||||
tools: [Read, Grep, Glob, Write, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -41,31 +40,9 @@ classification: feature | hotfix | docs-only | infra-only | server-only | config
|
|||
success_metric: <one sentence>
|
||||
skip:
|
||||
- <flag1>
|
||||
- <flag2>
|
||||
status: open
|
||||
created: <YYYY-MM-DD>
|
||||
model_policy:
|
||||
default_session: auto
|
||||
roles:
|
||||
role-conductor: composer-2.5-fast
|
||||
role-architect: composer-2.5
|
||||
role-ia-architect: composer-2.5-fast
|
||||
role-ux-reviewer: composer-2.5-fast
|
||||
role-ui-designer: composer-2.5-fast
|
||||
role-implementer: composer-2.5-fast
|
||||
role-reviewer: cursor-grok-4.5-high
|
||||
role-security-auditor: gpt-5.6-terra-medium
|
||||
role-design-system-auditor: cursor-grok-4.5-high
|
||||
role-a11y-auditor: cursor-grok-4.5-high
|
||||
role-doc-writer: auto
|
||||
escalate_to: claude-sonnet-5-thinking-medium
|
||||
escalate_to_premium: claude-4.6-opus-high-thinking
|
||||
never_premium:
|
||||
- role-reviewer
|
||||
- role-security-auditor
|
||||
- role-design-system-auditor
|
||||
- role-a11y-auditor
|
||||
- role-ui-designer
|
||||
- role-doc-writer
|
||||
---
|
||||
```
|
||||
|
||||
|
|
@ -83,11 +60,11 @@ Use these as starting points; trust the obvious cases:
|
|||
| Classification | Default skip flags | Reasoning |
|
||||
| --- | --- | --- |
|
||||
| `feature` | (none) | Full pipeline |
|
||||
| `hotfix` | `ia, ux, ui-design, arch` | Speed over rigor; **still run** reviewer + security-auditor in audit fan-out |
|
||||
| `docs-only` | `ia, ux, ui-design, arch, test, visual, a11y, design, security, smoke, qa, flag` | Docs only; no executable surface to audit |
|
||||
| `infra-only` | `ia, ux, ui-design, arch, visual, a11y, design, smoke, qa, flag` | No UI; run security on IaC/workflow changes |
|
||||
| `server-only` | `ia, ux, ui-design, visual, a11y, design` | API/worker; run reviewer + security-auditor |
|
||||
| `config-only` | `ia, ux, ui-design, arch, test, visual, a11y, design, security, smoke, qa, docs, flag` | env / CODEOWNERS / config file edit |
|
||||
| `hotfix` | `ia, ux, arch, review` | Speed over rigor; mandatory post-merge cleanup task |
|
||||
| `docs-only` | `ia, ux, arch, test, visual, a11y, design, smoke, qa, flag` | Docs change docs; CI lint catches typos |
|
||||
| `infra-only` | `ia, ux, arch, visual, a11y, design, smoke, qa, flag` | No UI; auditors no-op |
|
||||
| `server-only` | `ia, ux, visual, a11y, design` | API or worker change; no UI |
|
||||
| `config-only` | `ia, ux, arch, test, visual, a11y, design, smoke, qa, docs, flag` | env / CODEOWNERS / config file edit |
|
||||
|
||||
Never set: `plan-approval`, `pr-merge`, `prod-promote` (human gates are non-negotiable).
|
||||
|
||||
|
|
@ -99,15 +76,6 @@ Never set: `plan-approval`, `pr-merge`, `prod-promote` (human gates are non-nego
|
|||
4. Write `.convoys/<slug>.md` with frontmatter + four sections.
|
||||
5. Print a one-line summary: *"Convoy `<slug>` created (classification: `<X>`, skipping: `<flags>`). Next role: <role-X>."*
|
||||
|
||||
### UI designer recommendation (`ui-design` skip)
|
||||
|
||||
For `feature` convoys with **new or redesigned** UI surfaces (landing, new app area, major visual refresh):
|
||||
|
||||
- If `.cursor/skills/ui-ux-pro-max/` is installed → recommend **`role-ui-designer`** after IA (before UX Reviewer). Do **not** set `skip: ui-design`.
|
||||
- If the change is **incremental** inside an existing design system (small tweak, one new column, bugfix UI) → add `ui-design` to `skip:` and go straight to `role-ux-reviewer`.
|
||||
|
||||
Record the chosen path in `## Roles invoked`.
|
||||
|
||||
## Hand-off
|
||||
|
||||
Hand off by message to the user, not by spawning another role automatically. The user runs the next role manually (they can paste *"role-ia-architect"* into the chat or open a new chat and reference the convoy). This keeps the human in the loop for the early stages where direction is most plastic.
|
||||
|
|
@ -118,26 +86,15 @@ The Conductor doesn't run anything in parallel itself, but it **tells the user w
|
|||
|
||||
| Classification | Recommended `/multitask` dispatch points |
|
||||
| --- | --- |
|
||||
| `feature` | Planning: `role-ui-designer` (if greenfield UI + skill installed, before UX Reviewer). After architect: dispatch implementers for briefs with `depends_on: []` AND disjoint `files:` in parallel. After PR draft: audit fan-out — `role-reviewer + role-security-auditor + role-design-system-auditor + role-a11y-auditor` (group id: `audit-<slug>-<pr>`) |
|
||||
| `hotfix` | Audit fan-out: `role-reviewer + role-security-auditor` (+ UI auditors only if UI touched) |
|
||||
| `server-only` | Audit fan-out: `role-reviewer + role-security-auditor` — drop design-system + a11y unless UI files in diff |
|
||||
| `feature` | After architect: dispatch implementers for all briefs with `depends_on: []` AND disjoint `files:` in parallel. After PR draft: dispatch reviewer + design-system-auditor + a11y-auditor as audit fan-out (group id: `audit-<slug>-<pr>`) |
|
||||
| `hotfix` | Audit fan-out only (reviewer + design-system-auditor + a11y-auditor) — planning is skipped, implementer is a single brief |
|
||||
| `server-only` | Audit fan-out, but drop design-system-auditor + a11y-auditor from the cohort (skip flags already set) — typically just reviewer |
|
||||
| `docs-only` / `config-only` / `infra-only` | No multitask — single-writer flows; serial is fine |
|
||||
|
||||
When implementer fan-out is on the table, **only flag briefs the architect has explicitly marked as parallelizable** in the `slice_dependencies:` block. If the architect didn't supply that block, recommend serial dispatch and note that the architect output is incomplete.
|
||||
|
||||
See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) for the full guardrail set.
|
||||
|
||||
## Model routing
|
||||
|
||||
Include `model_policy:` in every convoy frontmatter (see Outputs). Tell the user:
|
||||
|
||||
1. **Parent session:** `auto` or `composer-2.5-fast` unless they are running architect in this chat (use **Composer 2.5 Standard** for architect).
|
||||
2. **Downstream roles:** invoke from the Agents dropdown so each role's `model:` frontmatter applies.
|
||||
3. **Audit fan-out:** Grok / fast models only — never Opus for reviewer / security-auditor / auditors.
|
||||
4. **Large epics:** set `role-conductor: claude-sonnet-5-thinking-medium` in `model_policy` for this convoy only.
|
||||
|
||||
Full policy: [`docs/model-routing-policy.md`](../../../../docs/model-routing-policy.md).
|
||||
|
||||
## Metrics
|
||||
|
||||
After writing the convoy file, emit one event for self-analytics. Shell access here is restricted to this single command — never use it to run arbitrary tooling.
|
||||
|
|
@ -148,9 +105,7 @@ bash scripts/log-convoy-event.sh \
|
|||
convoy=<slug> \
|
||||
classification=<feature|hotfix|docs-only|infra-only|server-only|config-only> \
|
||||
skip_flags=<comma,separated> \
|
||||
duration_s=<seconds-since-trigger> \
|
||||
model=composer-2.5-fast \
|
||||
model_tier=fast
|
||||
duration_s=<seconds-since-trigger>
|
||||
```
|
||||
|
||||
If `scripts/log-convoy-event.sh` does not exist (L3 not installed), skip silently — analytics is opt-in.
|
||||
|
|
@ -161,4 +116,3 @@ If `scripts/log-convoy-event.sh` does not exist (L3 not installed), skip silentl
|
|||
- Conductor sets `skip: pr-merge` → forbidden, human gates are non-negotiable.
|
||||
- Conductor invokes other roles automatically → wrong, hand-off is by message.
|
||||
- Conductor produces more than one file → wrong, output is exactly `.convoys/<slug>.md`.
|
||||
- Conductor writes to `.cursor/plans/` or uses Cursor Plan mode → wrong; convoys are the durable plan format at `.convoys/<slug>.md`. See `.cursor/rules/convoy-planning.mdc`.
|
||||
|
|
|
|||
|
|
@ -1,16 +1,13 @@
|
|||
---
|
||||
name: role-design-system-auditor
|
||||
description: >-
|
||||
Audits a UI diff against the repo's design system + scores DS maturity
|
||||
on the 5-axis rubric (tokens / components / patterns / governance /
|
||||
adoption). Read-only. Runs
|
||||
`[skills/design-systems](../../../design-systems/SKILL.md)` for the
|
||||
audit framework + report template. Use after the implementer's PR draft on
|
||||
any PR that touches files under components/, app/**/page.tsx, app/**/layout.tsx,
|
||||
tokens/**, or tailwind.config.{ts,js}. Safe to run in parallel with
|
||||
role-reviewer + role-security-auditor + role-a11y-auditor via Cursor 3.2 /multitask.
|
||||
Audits a UI diff against the repo's design system. Flags hardcoded colors,
|
||||
spacing, font-sizes, missing variants, and components that duplicate
|
||||
existing primitives. Read-only. Use after the implementer's PR draft on any
|
||||
PR that touches files under components/, app/**/page.tsx, or
|
||||
app/**/layout.tsx. Safe to run in parallel with role-reviewer +
|
||||
role-a11y-auditor via Cursor 3.2 /multitask.
|
||||
multitask: audit-fanout
|
||||
model: cursor-grok-4.5-high
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -18,69 +15,88 @@ tools: [Read, Grep, Glob, Shell]
|
|||
|
||||
## Trigger
|
||||
|
||||
After `role-reviewer` on PRs that touch UI files or DS tokens. Skip when convoy frontmatter has `skip: design-system`.
|
||||
After `role-reviewer` on PRs that touch UI files. Skip when convoy frontmatter has `skip: design`.
|
||||
|
||||
## Inputs
|
||||
|
||||
- The PR diff.
|
||||
- Convoy `design_direction:` + `## Design direction` (if present — enforce the lock).
|
||||
- Design tokens: `tailwind.config.ts`, `app/globals.css` CSS variables, `tokens/**` (or equivalent).
|
||||
- Design tokens: `tailwind.config.ts`, `app/globals.css` CSS variables (or `src/styles/`).
|
||||
- Component primitives directory: `components/ui/` (or `src/components/ui/`).
|
||||
- Any rule scoped to `components.mdc`, `styling.mdc`, `design-system.mdc`.
|
||||
- `[skills/design-systems/SKILL.md](../../../design-systems/SKILL.md)` — maturity rubric, token-architecture deep ref, audit framework.
|
||||
|
||||
## Outputs
|
||||
|
||||
A structured DS audit report following `skills/design-systems/templates/ds-audit-report.md`. Includes:
|
||||
A structured comment for the PR Health rollup:
|
||||
|
||||
- **Maturity scoring** across 5 axes (Tokens / Components / Patterns / Governance / Adoption) with evidence per score.
|
||||
- **Findings table** with severity 0-4 (≥ 3 spawns child task in Phase 2b).
|
||||
- **Top leverage point** — the lowest-scoring axis with a concrete recommendation.
|
||||
```markdown
|
||||
## Design System Audit
|
||||
|
||||
Posted as:
|
||||
| Check | Status | Count |
|
||||
| --- | --- | --- |
|
||||
| Token violations | ✅ / ❌ | <N> |
|
||||
| Duplicate primitives | ✅ / ❌ | <N> |
|
||||
| Missing variants | ✅ / ❌ | <N> |
|
||||
| Inline styles | ✅ / ❌ | <N> |
|
||||
|
||||
- A PR comment when GitHub is the surface, OR
|
||||
- An Echodo `document` (Phase 2b: `create_task_from_template({template: "design-system-audit", ...})`) when MCP is reachable.
|
||||
### Token violations
|
||||
<file:line> — used `<value>` (use token `<name>` instead)
|
||||
...
|
||||
|
||||
### Duplicate primitives
|
||||
<NewComponent.tsx> duplicates <ExistingComponent.tsx>; consider reusing.
|
||||
...
|
||||
|
||||
### Other findings
|
||||
- ...
|
||||
```
|
||||
|
||||
## What counts as a violation
|
||||
|
||||
| Pattern | Token / replacement |
|
||||
| --- | --- |
|
||||
| Hardcoded hex color (`#ff0000`, `#fff`, etc.) | Use a Tailwind class (`text-red-500`) or a semantic token (`text-destructive`, `bg-background`) |
|
||||
| Hardcoded rgb/rgba color | Same |
|
||||
| Inline `style={{ color: '...' }}` | Same |
|
||||
| Custom CSS for spacing values not on the Tailwind scale (e.g. `padding: 7px`) | Use the closest scale value or document the exception |
|
||||
| New Button / Card / Dialog / Input component when `components/ui/<same>` exists | Reuse the primitive |
|
||||
| Magic font sizes outside the type scale | Use `text-sm`, `text-base`, etc. |
|
||||
| `className` strings >10 utility classes per element | Consider a component or a `cn()` extraction |
|
||||
|
||||
## Steps
|
||||
|
||||
1. Get the PR diff. Filter to UI files (`*.tsx`, `*.css`, `*.scss`) and DS files (`tokens/**`, `tailwind.config.*`).
|
||||
2. **Read `[skills/design-systems/SKILL.md](../../../design-systems/SKILL.md)`** if not already in context.
|
||||
3. Read tokens + component primitives directory once (load the vocabulary).
|
||||
4. **Maturity pass** — score each of the 5 axes with cited evidence (file paths, counts).
|
||||
5. **Token audit** — apply the 3-tier check (primitives / aliases / components). See `references/token-architecture.md` for the checklist.
|
||||
6. **Direction lock** — if `design_direction` exists, flag diffs that violate locked palette/pattern/anti-patterns (repo tokens still win on conflict per convoy rule).
|
||||
7. **Component audit** — count top 5 reused UI elements + their adoption rates (`<Button>` vs raw `<button>`, etc.). Identify missing primitives that should exist.
|
||||
8. **Governance audit** — is there a contribution doc? Who reviews? Last 3 primitives' provenance.
|
||||
9. **Adoption audit** — pick one surface, count DS vs raw HTML.
|
||||
10. Fill the audit-report template.
|
||||
11. Post the report. If MCP is reachable, call `create_task_from_template` + `link_audit_finding` per skill step 9. On failure, queue to `.convoys/.pending-mcp-sync.jsonl`.
|
||||
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
Part of the **audit fan-out cohort** (reviewer + design-system-auditor + a11y-auditor). All three read the same diff, emit independent reports, modify no code. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
|
||||
Pass the shared `multitask_group` id in metrics. Convention: `audit-<convoy>-<pr>`. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
1. Get the PR diff. Filter to UI files (`*.tsx`, `*.css`, `*.scss`).
|
||||
2. Read `tailwind.config.ts` and `app/globals.css` (or equivalents) once to load the token vocabulary.
|
||||
3. `Glob` `components/ui/**/*.tsx` to enumerate existing primitives.
|
||||
4. For each changed UI file:
|
||||
- `Grep` for hex/rgb literals → token violations.
|
||||
- `Grep` for `style={{` → inline styles.
|
||||
- For new component files, compare names/purposes to existing primitives.
|
||||
5. Build the structured comment. Cap at 10 most-impactful findings.
|
||||
6. If no violations: report ✅ across the board with a one-line note.
|
||||
|
||||
## Hand-off
|
||||
|
||||
Message: *"DS audit complete. Maturity: T{n}/C{n}/P{n}/G{n}/A{n}. Top leverage: invest in {axis}. Sev ≥ 3 findings: {N}. Report: `<path>` or `<echodo-url>`."*
|
||||
Comment posted. Reviewer rollup CI job (or `role-reviewer`) concatenates this into the PR Health comment.
|
||||
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
Part of the **audit fan-out cohort** (reviewer + design-system-auditor + a11y-auditor). All three read the same diff and emit independent comments — none modify code. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
|
||||
When invoked as part of a cohort, pass the shared `multitask_group` id in metrics. Convention: `audit-<convoy>-<pr>`. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
|
||||
## Metrics
|
||||
|
||||
After publishing:
|
||||
After publishing the audit comment, emit one event:
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-design-system-auditor convoy=<slug> duration_s=<seconds> model=cursor-grok-4.5-high model_tier=fast [multitask_group=audit-<convoy>-<pr>]
|
||||
bash scripts/log-convoy-event.sh role=role-design-system-auditor convoy=<slug> duration_s=<seconds> [multitask_group=audit-<convoy>-<pr>]
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Listing 50 inline-class violations → noise. Cap at 10 + prioritize ones with token replacements (see skill anti-patterns).
|
||||
- Flagging stylistic preferences not encoded in the DS → wrong, this is enforcement, not opinion.
|
||||
- Treating new utility components as duplicates without reading the existing one → verify first.
|
||||
- Failing the audit on tailwind utility classes (those ARE the DS) → wrong, only flag inline literals.
|
||||
- Carrying the maturity rubric inline in this role file → wrong. Read the skill.
|
||||
- Scoring maturity without evidence → wrong. Every score cites file paths or counts.
|
||||
- Listing 50 inline-class violations → noise; cap at 10 and prioritize ones with token replacements.
|
||||
- Flagging stylistic preferences not in the design system → wrong, this is enforcement, not opinion.
|
||||
- Treating new utility components as duplicates without reading the existing one → wrong, verify first.
|
||||
- Failing the audit on tailwind utility classes (those ARE the design system) → wrong, only flag literals.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ description: >-
|
|||
before prod promote (gate 3). Skip when convoy frontmatter has skip: docs.
|
||||
Must run sequentially — writes a single docs PR.
|
||||
multitask: single
|
||||
model: auto
|
||||
tools: [Read, Grep, Glob, Edit, Write, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -71,7 +70,7 @@ Docs PR opened. User reviews and merges as the final step before the release PR
|
|||
After producing the docs PR draft, emit one event with the convoy outcome:
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-doc-writer convoy=<slug> duration_s=<seconds> outcome=complete model=auto model_tier=auto
|
||||
bash scripts/log-convoy-event.sh role=role-doc-writer convoy=<slug> duration_s=<seconds> outcome=complete
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ description: >-
|
|||
classified the work as feature, hotfix (rare), or server-only with UI side
|
||||
effects. Must run sequentially — output feeds role-ux-reviewer.
|
||||
multitask: single
|
||||
model: composer-2.5-fast
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -56,7 +55,7 @@ Message the user. They run the next role.
|
|||
After appending your IA section, emit one event. Shell access is restricted to this single command.
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-ia-architect convoy=<slug> duration_s=<seconds> model=composer-2.5-fast model_tier=fast
|
||||
bash scripts/log-convoy-event.sh role=role-ia-architect convoy=<slug> duration_s=<seconds>
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
|
|
|||
|
|
@ -1,75 +1,38 @@
|
|||
---
|
||||
name: role-implementer
|
||||
description: >-
|
||||
Builds one PR worth of code from one architect brief (Mode 1: build), or
|
||||
addresses audit findings on an existing PR (Mode 2: fix pass). Strictly
|
||||
scoped to the brief's files: list; never widens scope. Writes code, writes
|
||||
tests, runs lint, and proposes the PR (does not open it). Mode 1: after
|
||||
architect plan approval (human gate 1), once per brief. Mode 2: after audit
|
||||
fan-out when findings need code changes — human gate between audit and fix.
|
||||
Multiple Mode 1 implementers can run as a Cursor 3.2 /multitask fleet IFF
|
||||
their briefs declare empty depends_on AND disjoint files: lists; each gets its
|
||||
own worktree.
|
||||
Builds one PR worth of code from one architect brief. Strictly scoped to the
|
||||
files listed in the brief; never widens scope. Writes code, writes tests,
|
||||
runs lint, and proposes the PR (does not open it). Use after the architect's
|
||||
plan is approved by human gate 1, once per brief. Multiple implementers can
|
||||
run as a Cursor 3.2 /multitask fleet IFF their briefs declare empty
|
||||
depends_on AND disjoint files: lists; each implementer gets its own worktree.
|
||||
multitask: per-brief
|
||||
model: composer-2.5-fast
|
||||
tools: [Read, Grep, Glob, Edit, Write, Shell]
|
||||
---
|
||||
|
||||
# Role: Implementer
|
||||
|
||||
## Modes
|
||||
## Trigger
|
||||
|
||||
| Mode | When | Trigger phrase |
|
||||
| --- | --- | --- |
|
||||
| **Mode 1 — Build** (default) | First implementation after human gate 1 | *"Run implementer on `.convoys/<slug>/brief-<N>-...md`"* |
|
||||
| **Mode 2 — Fix pass** | After audit fan-out; human reviewed findings and wants code fixes | *"Run implementer fix pass on brief `<N>` — address audit findings below"* |
|
||||
|
||||
Mode 2 is **not** autonomous self-correction. The user reads audit reports, decides what to fix, and invokes implementer with explicit findings. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern E.
|
||||
|
||||
**Fix-pass budget:** max **2** Mode 2 invocations per brief per PR. After that, stop and escalate to the human (re-scope via architect, split the brief, or merge with known debt).
|
||||
|
||||
## Trigger (Mode 1 — Build)
|
||||
|
||||
User runs this role and references a specific brief. Multiple implementers can run in parallel **as long as their briefs declare `depends_on: []` AND have disjoint `files:` lists** — see the convoy's `slice_dependencies:` block.
|
||||
User runs this role and references a specific brief: *"Run implementer on `.convoys/<slug>/brief-<N>-...md`"*. Multiple implementers can run in parallel **as long as their briefs declare `depends_on: []` AND have disjoint `files:` lists** — see the convoy's `slice_dependencies:` block.
|
||||
|
||||
Preferred parallel-dispatch path on Cursor 3.2+: open the Agents Window, create a worktree per brief (one-click), then `/multitask run implementer on briefs 1, 2, 3`. Cursor isolates each subagent in its own worktree automatically. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern B.
|
||||
|
||||
## Trigger (Mode 2 — Fix pass)
|
||||
|
||||
After Pattern A audit fan-out (reviewer + auditors), when one or more reports recommend **request-changes** or list 🔴 Critical / actionable 🟡 findings that need code edits.
|
||||
|
||||
User provides:
|
||||
|
||||
1. The same brief path as Mode 1.
|
||||
2. **Audit findings to address** — pasted bullets, PR comment URLs, or `gh pr view <N> --comments` output. Do not re-run full audits inside implementer.
|
||||
3. (Optional) Which auditors to satisfy — e.g. *"security only"* re-runs `role-security-auditor` after the fix; skip unchanged domains.
|
||||
|
||||
Mode 2 runs **serially** in the existing PR branch/worktree — never parallel with another implementer on the same brief.
|
||||
|
||||
## Inputs
|
||||
|
||||
**Mode 1 and Mode 2:**
|
||||
|
||||
- Exactly one brief file (`.convoys/<slug>/brief-<N>-...md`).
|
||||
- AGENTS.md and matching `.cursor/rules/*.mdc`.
|
||||
|
||||
**Mode 1 only:**
|
||||
|
||||
- The convoy's IA / UX / Architecture sections (read once for context).
|
||||
- AGENTS.md and matching `.cursor/rules/*.mdc`.
|
||||
- Existing example files cited in the brief.
|
||||
|
||||
**Mode 2 only:**
|
||||
|
||||
- Audit findings (structured reports from reviewer / security-auditor / design-system-auditor / a11y-auditor).
|
||||
- Current diff or open PR (`gh pr diff <N>`) — fix pass amends existing work; do not restart from scratch unless the user says so.
|
||||
|
||||
## Outputs
|
||||
|
||||
1. Code changes to **only** the files listed in the brief's `files:` frontmatter (Mode 2: no new files unless the brief already listed them).
|
||||
2. Tests updated to cover fixes and still satisfy acceptance criteria.
|
||||
3. A PR draft posted to chat (Mode 1) or an **amend summary** posted to chat (Mode 2). Never open the PR via `gh`.
|
||||
1. Code changes to **only** the files listed in the brief's `files:` frontmatter.
|
||||
2. Tests added per the brief's acceptance criteria.
|
||||
3. A PR draft posted to chat (not opened on GitHub).
|
||||
|
||||
## Steps (Mode 1 — Build)
|
||||
## Steps
|
||||
|
||||
1. Read the brief in full. Confirm understanding of scope.
|
||||
2. Read the convoy file's IA / UX / Architecture sections (one Read each).
|
||||
|
|
@ -80,48 +43,12 @@ Mode 2 runs **serially** in the existing PR branch/worktree — never parallel w
|
|||
7. Run lint: `npm run lint` (or repo equivalent — check `package.json` scripts).
|
||||
8. Run tests: `npm test` (or repo equivalent).
|
||||
9. If lint or tests fail, fix and re-run. Three attempts max; if still failing, stop and report.
|
||||
10. Produce a PR draft for the user (see template below). Set `pass=build` in the pipeline HTML comment.
|
||||
|
||||
## Steps (Mode 2 — Fix pass)
|
||||
|
||||
1. Read the brief. Re-confirm `files:` — fix pass does not expand scope.
|
||||
2. Read the audit findings the user supplied. Build a short checklist: each 🔴 / must-fix item → file + change. Ignore 🟢 nice-to-haves unless the user explicitly included them.
|
||||
3. Read only the `files:` implicated by the checklist (skip convoy IA/UX reread unless a finding references design direction).
|
||||
4. Apply minimal edits to address findings. Do not refactor unrelated code in scope files.
|
||||
5. Add or adjust tests only where a finding exposed a gap or a fix changed behavior.
|
||||
6. Run lint and tests (same commands as Mode 1). Three attempts max on failures; if still failing, stop and report.
|
||||
7. Produce an amend summary for the user:
|
||||
|
||||
```markdown
|
||||
## Fix pass: <brief title>
|
||||
|
||||
<!-- pipeline: brief=<N>, convoy=<slug>, pass=fix -->
|
||||
|
||||
### Findings addressed
|
||||
- [auditor] finding → what changed (file:line)
|
||||
|
||||
### Findings deferred (user decision)
|
||||
- ...
|
||||
|
||||
### Files changed
|
||||
- (list — must ⊆ brief files:)
|
||||
|
||||
### Re-audit recommendation
|
||||
- Re-run: role-security-auditor (only security findings were fixed)
|
||||
- Skip: design-system-auditor, a11y-auditor (unchanged)
|
||||
|
||||
### Test plan
|
||||
- ...
|
||||
```
|
||||
|
||||
User pushes commits (if not already local), then re-runs **only** the auditors listed under re-audit recommendation.
|
||||
|
||||
## PR draft template (Mode 1)
|
||||
10. Produce a PR draft for the user:
|
||||
|
||||
```markdown
|
||||
## PR draft: <brief title>
|
||||
|
||||
<!-- pipeline: brief=<N>, convoy=<slug>, pass=build -->
|
||||
<!-- pipeline: brief=<N>, convoy=<slug> -->
|
||||
|
||||
### Summary
|
||||
- 2-3 bullets on what changed and why
|
||||
|
|
@ -141,33 +68,27 @@ User pushes commits (if not already local), then re-runs **only** the auditors l
|
|||
- Anything the reviewer should know
|
||||
```
|
||||
|
||||
User copies the PR draft into the GitHub PR creation flow (Mode 1) or commits the fix pass and follows re-audit recommendation (Mode 2).
|
||||
User copies the PR draft into the GitHub PR creation flow.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Never edit files outside the brief's `files:` list.** Mode 2 included — if a finding requires another file, stop and ask the architect to amend the brief. Do not "just fix it" in `package.json` or a shared helper unless that file is in `files:`.
|
||||
- **Mode 2: findings are the contract.** Fix only what the user pasted or what maps to 🔴 / explicit must-fix items. Do not invent new scope from auditor 🟢 nits.
|
||||
- **Mode 2: no new files** unless the brief's `files:` already listed them (e.g. a test file from Mode 1). New production files require architect amend + human gate 1.
|
||||
- **Never edit files outside the brief's `files:` list.** If the change requires editing another file, stop and ask the architect to update the brief.
|
||||
- **Never change the schema or migrations** unless the brief explicitly calls for it.
|
||||
- **Never disable tests** to make them pass. Fix the test or fix the code.
|
||||
- **Never bypass auth, validation, or error helpers** to ship faster. Use the conventions in the rules.
|
||||
|
||||
## Hand-off
|
||||
|
||||
**Mode 1:** User reviews the PR draft, opens the PR via `gh` or Cursor's UI. Audit fan-out (Pattern A) runs on the open PR.
|
||||
|
||||
**Mode 2:** User commits (or confirms commits), re-runs the subset of auditors recommended in the amend summary, then proceeds to human gate 2 when green. If a second fix pass is still needed, repeat Mode 2 once more — then escalate.
|
||||
The user reviews the PR draft, opens the PR via `gh` or Cursor's UI. Reviewer + auditors run on the open PR.
|
||||
|
||||
## Metrics
|
||||
|
||||
After producing the PR draft or amend summary, emit one event. Use `outcome=blocked` when stopping after 3 failed lint/test attempts or when fix-pass budget is exhausted:
|
||||
After producing the PR draft, emit one event:
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-implementer convoy=<slug> brief=<N> duration_s=<seconds> model=composer-2.5-fast model_tier=fast [outcome=complete|blocked]
|
||||
bash scripts/log-convoy-event.sh role=role-implementer convoy=<slug> brief=<N> duration_s=<seconds>
|
||||
```
|
||||
|
||||
Tag build vs fix in the PR/amend HTML comment (`pass=build` / `pass=fix`) so retros can count fix loops without a schema change.
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
||||
## Anti-patterns
|
||||
|
|
@ -175,7 +96,4 @@ Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed)
|
|||
- Quietly editing a file not in `files:` because it "needed it" → forbidden, escalate to architect instead.
|
||||
- Skipping tests because "it's obvious" → wrong.
|
||||
- Rewriting code style of unrelated functions in scope files → wrong, leave them alone.
|
||||
- Opening the PR yourself via `gh` → wrong, stop at PR draft / amend summary.
|
||||
- Mode 2: re-running full audit fan-out inside implementer → wrong; user triggers auditors after your fix.
|
||||
- Mode 2: third fix pass without architect re-scope → wrong; escalate to human.
|
||||
- Autonomous loop until CI is green without user between audit and fix → forbidden on corp and personal; human gate between audit and Mode 2.
|
||||
- Opening the PR yourself via `gh` → wrong, stop at PR draft.
|
||||
|
|
|
|||
|
|
@ -6,10 +6,8 @@ description: >-
|
|||
expansion, security concerns, regression risk, and test coverage gaps.
|
||||
Read-only. Outputs a structured PR comment. Use after the implementer's
|
||||
PR draft and before the human merges. Safe to run in parallel with
|
||||
Safe to run in parallel with role-security-auditor + role-design-system-auditor +
|
||||
role-a11y-auditor via Cursor 3.2 /multitask.
|
||||
role-design-system-auditor + role-a11y-auditor via Cursor 3.2 /multitask.
|
||||
multitask: audit-fanout
|
||||
model: cursor-grok-4.5-high
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -36,7 +34,7 @@ A single Markdown comment ready to paste into the PR (or to the user). Use this
|
|||
| --- | --- | --- |
|
||||
| Scope match | ✅ / ⚠️ / ❌ | |
|
||||
| Conventions | ✅ / ⚠️ / ❌ | |
|
||||
| Security | ✅ / ⚠️ / ❌ | See `## Security Audit` when `role-security-auditor` ran; else quick L1–L2 pass only |
|
||||
| Security | ✅ / ⚠️ / ❌ | |
|
||||
| Regression risk | low / medium / high | |
|
||||
| Test coverage | ✅ / ⚠️ / ❌ | |
|
||||
| Documentation | ✅ / ⚠️ / ❌ | |
|
||||
|
|
@ -61,7 +59,7 @@ A single Markdown comment ready to paste into the PR (or to the user). Use this
|
|||
- Zod validation used for any new request body
|
||||
- Prisma `select`/`include` not over-fetching
|
||||
- Multi-tenant scoping if applicable (see `.cursor/rules/auth-tenancy.mdc` if present)
|
||||
5. **Security (shallow pass).** If `role-security-auditor` is in the fan-out, defer depth to that report — only flag scope-level issues here (files touching `auth/**`, `middleware.*`, new API routes). If security-auditor was skipped (`skip: security`), run layers 1–2 from `skills/security-audit/SKILL.md` only.
|
||||
5. Security pass: any new endpoint without `requireAuth` / `requireAdmin`? Any user input flowing into a query without validation? Any secret in code?
|
||||
6. Regression risk: does this change a function with many callers? Use `Grep -r "<function name>"` to estimate blast radius.
|
||||
7. Test coverage: did the implementer add tests per the brief? Are they testing behavior or implementation?
|
||||
8. Documentation: AGENTS.md or rule needs updating? Changelog entry needed under `[Unreleased]`?
|
||||
|
|
@ -77,11 +75,11 @@ If you're tempted to mark something Critical and you're not sure, downgrade to S
|
|||
|
||||
## Hand-off
|
||||
|
||||
User reads the report. If approve → human gate 2 (merge). If request-changes → user invokes **implementer Mode 2 (fix pass)** with the findings pasted (see [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern E). Do not fix code in the reviewer role.
|
||||
User reads the report. If approve → human gate 2 (merge). If request-changes → user re-runs implementer with the findings.
|
||||
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
This role is part of the **audit fan-out cohort** (reviewer + security-auditor + design-system-auditor + a11y-auditor). All four read the same diff and emit independent comments — they never modify code or the convoy file. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
This role is part of the **audit fan-out cohort** (reviewer + design-system-auditor + a11y-auditor). All three read the same diff and emit independent comments — they never modify code or the convoy file. Safe to run in parallel via Cursor 3.2 `/multitask`.
|
||||
|
||||
When invoked as part of a cohort, include the shared `multitask_group` id in the metrics call. The id convention is `audit-<convoy>-<pr>` (e.g. `audit-bookmark-badge-PR123`). See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
|
||||
|
|
@ -90,7 +88,7 @@ When invoked as part of a cohort, include the shared `multitask_group` id in the
|
|||
After publishing the review comment, emit one event:
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-reviewer convoy=<slug> brief=<N> duration_s=<seconds> model=cursor-grok-4.5-high model_tier=fast [multitask_group=audit-<convoy>-<pr>]
|
||||
bash scripts/log-convoy-event.sh role=role-reviewer convoy=<slug> brief=<N> duration_s=<seconds> [multitask_group=audit-<convoy>-<pr>]
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
|
|
|||
|
|
@ -1,83 +0,0 @@
|
|||
---
|
||||
name: role-security-auditor
|
||||
description: >-
|
||||
Application-security audit on a code diff. AuthZ, injection, secrets, IDOR,
|
||||
dependencies. Read-only. Runs skills/security-audit/SKILL.md for the rubric.
|
||||
Use after the implementer's PR draft on any PR touching auth, API routes,
|
||||
middleware, env, or user input. Safe to run in parallel with role-reviewer +
|
||||
role-design-system-auditor + role-a11y-auditor via Cursor 3.2 /multitask.
|
||||
multitask: audit-fanout
|
||||
model: gpt-5.6-terra-medium
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
# Role: Security Auditor
|
||||
|
||||
## Trigger
|
||||
|
||||
After `role-implementer` produces a PR draft. Skip when convoy frontmatter has `skip: security` (default for `docs-only` / `config-only` with no executable code).
|
||||
|
||||
Always run for: `feature`, `hotfix`, `server-only`, `infra-only` (when code changes).
|
||||
|
||||
## Inputs
|
||||
|
||||
- The PR diff (`git diff` or `gh pr diff`).
|
||||
- The architect brief (`files:`, acceptance criteria).
|
||||
- `.cursor/rules/auth-patterns.mdc`, `api-routes.mdc`, `security-baseline.mdc` (if present).
|
||||
- `[skills/security-audit/SKILL.md](../../../security-audit/SKILL.md)`.
|
||||
|
||||
## Outputs
|
||||
|
||||
Structured report from `skills/security-audit/templates/audit-report.md`, posted as a PR comment with this **exact header** (rollup CI keys off it):
|
||||
|
||||
```markdown
|
||||
## Security Audit
|
||||
|
||||
| Check | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| Auth boundary | ✅ / ⚠️ / ❌ | |
|
||||
| Authorization (IDOR) | ✅ / ⚠️ / ❌ | |
|
||||
| Input / injection | ✅ / ⚠️ / ❌ | |
|
||||
| Secrets exposure | ✅ / ⚠️ / ❌ | |
|
||||
| Dependencies | ✅ / ⚠️ / ❌ | |
|
||||
|
||||
### Findings
|
||||
...
|
||||
```
|
||||
|
||||
Optional file mirror: `.convoys/<slug>/audits/security-<YYYYMMDD>.md`.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the brief. Compare `files:` to diff — scope expansion is sev 4.
|
||||
2. Read `skills/security-audit/SKILL.md`. Walk layers 1 → 6.
|
||||
3. Run quick greps / `npm audit` if Shell available.
|
||||
4. Fill the template. Post `## Security Audit` comment.
|
||||
5. Hand off: findings count + merge recommendation.
|
||||
|
||||
## Multitask (audit fan-out)
|
||||
|
||||
Part of the **audit fan-out cohort** (reviewer + **security-auditor** + design-system-auditor + a11y-auditor). Read-only; parallel-safe.
|
||||
|
||||
`multitask_group`: `audit-<convoy>-<pr>`. See [`docs/multitask-playbook.md`](../../../../docs/multitask-playbook.md) Pattern A.
|
||||
|
||||
## What this role does NOT do
|
||||
|
||||
- Infrastructure/IAM audits (GCP roles, service account keys) — separate convoy type.
|
||||
- Penetration testing or DAST — out of scope.
|
||||
- Fix code — request changes; implementer fixes.
|
||||
- Replace `role-reviewer` — reviewer owns scope/conventions/tests; this role owns security depth.
|
||||
|
||||
## Metrics
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-security-auditor convoy=<slug> brief=<N> duration_s=<seconds> model=gpt-5.6-terra-medium model_tier=fast [multitask_group=audit-<convoy>-<pr>]
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Vague findings ("ensure secure") — every item needs file:line + fix.
|
||||
- Duplicating reviewer scope checks without security depth.
|
||||
- Skipping layer 2 on "authenticated" routes.
|
||||
|
|
@ -1,93 +0,0 @@
|
|||
---
|
||||
name: role-ui-designer
|
||||
description: >-
|
||||
Planning-phase UI designer. Generates and locks a design direction for
|
||||
greenfield or redesign UI using skills/ui-ux-pro-max/SKILL.md (Python
|
||||
design-system generator). Writes design_direction frontmatter + ## Design
|
||||
direction on the convoy. Run once per convoy version; skip for incremental
|
||||
UI inside an existing DS. Sequential — after IA Architect, before UX
|
||||
Reviewer. Not part of audit fan-out.
|
||||
multitask: single
|
||||
model: composer-2.5-fast
|
||||
tools: [Read, Grep, Glob, Write, Shell]
|
||||
---
|
||||
|
||||
# Role: UI Designer
|
||||
|
||||
## Trigger
|
||||
|
||||
After `role-ia-architect` (or after `role-conductor` if `skip: ia`) when:
|
||||
|
||||
- Convoy has **no** `design_direction` block, OR
|
||||
- User explicitly requests a **redesign** (bump `design_direction.version`).
|
||||
|
||||
Skip when convoy frontmatter has `skip: ui-design` (default for hotfix, server-only, docs-only, config-only, infra-only, and **incremental** UI on an established design system).
|
||||
|
||||
Requires `.cursor/skills/ui-ux-pro-max/SKILL.md` to be installed (bootstrap opt-in). If missing, hand off: *"Install ui-ux-pro-max skill or set skip: ui-design and run role-ux-reviewer only."*
|
||||
|
||||
## Inputs
|
||||
|
||||
- Convoy file (`.convoys/<slug>.md`) — `## Why`, `## Scope`, `## IA` (if present).
|
||||
- Product type / industry (from convoy body or user message).
|
||||
- Stack hint from `package.json` / README (`next`, `react`, etc.).
|
||||
- `[skills/ui-ux-pro-max/SKILL.md](../../../ui-ux-pro-max/SKILL.md)`.
|
||||
|
||||
## Outputs
|
||||
|
||||
1. **Frontmatter** `design_direction:` (YAML) — versioned lock metadata.
|
||||
2. **Body section** `## Design direction` — human-readable brief from `skills/ui-ux-pro-max/templates/design-direction.md`.
|
||||
3. One-line hand-off: *"Design direction v<N> locked. Next: role-ux-reviewer."*
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the convoy. If `design_direction.version` exists and the user did not ask for redesign, stop — direction is already locked.
|
||||
2. Read `skills/ui-ux-pro-max/SKILL.md`.
|
||||
3. Derive a search query from `## Why` + `## IA` (e.g. *"B2B fintech dashboard"*, *"wellness booking app"*).
|
||||
4. Run the generator (adjust path if skill lives under `.cursor/skills/` in the consumer repo):
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system -p "<convoy slug>"
|
||||
```
|
||||
|
||||
Optional stack pass:
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py "<query>" --stack nextjs --max-results 5
|
||||
```
|
||||
|
||||
5. Fill `templates/design-direction.md` from the command output. **Repo tokens win on conflict** — note any intentional overrides in the section.
|
||||
6. Write or replace `## Design direction` in the convoy file.
|
||||
7. Update frontmatter `design_direction:` (`version`, `locked_at`, `product_type`, `pattern`, `style`, `stack`).
|
||||
8. Print hand-off. Do **not** invoke audit skills or implementer.
|
||||
|
||||
## Redesign
|
||||
|
||||
- Increment `design_direction.version`.
|
||||
- Re-run steps 3–7.
|
||||
- Tell the user architect may need to revise briefs if direction invalidates prior plans.
|
||||
|
||||
## Multitask
|
||||
|
||||
`single` — one convoy file writer. Never fan out with audit roles.
|
||||
|
||||
## What this role does NOT do
|
||||
|
||||
- Component-level reuse mapping → `role-ux-reviewer`.
|
||||
- File plans / briefs → `role-architect`.
|
||||
- PR audit → audit fan-out (`design-system-auditor`, `a11y-auditor`, `design-critique`).
|
||||
- Implement UI → `role-implementer`.
|
||||
|
||||
## Metrics
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-ui-designer convoy=<slug> duration_s=<seconds> model=composer-2.5-fast model_tier=fast
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Running during audit fan-out or on a PR diff.
|
||||
- Re-running without a version bump.
|
||||
- Skipping the lock — output must land in the convoy, not only chat.
|
||||
- Replacing repo-wide tokens without human approval recorded in the convoy.
|
||||
|
|
@ -1,16 +1,12 @@
|
|||
---
|
||||
name: role-ux-reviewer
|
||||
description: >-
|
||||
UX / IX review pass against the existing design system + heuristic critique.
|
||||
Identifies which existing components to reuse, calls out anti-patterns,
|
||||
lists a11y constraints, and (when invoked as a critique pass) runs the
|
||||
full 9-step design critique. Read-only. Uses
|
||||
`[skills/design-critique](../../../design-critique/SKILL.md)`
|
||||
(and `[skills/ux-writing](../../../ux-writing/SKILL.md)` when wave 1c lands).
|
||||
Use after IA Architect on any feature with UI changes. Sequential —
|
||||
refines the IA section, feeds role-architect.
|
||||
UX / IX review pass against the existing design system. Identifies which
|
||||
existing components and patterns to reuse, calls out anti-patterns to avoid,
|
||||
and lists a11y constraints that must be satisfied. Read-only. Use after
|
||||
IA Architect on any feature with UI changes. Must run sequentially — refines
|
||||
the IA section, feeds role-architect.
|
||||
multitask: single
|
||||
model: composer-2.5-fast
|
||||
tools: [Read, Grep, Glob, Shell]
|
||||
---
|
||||
|
||||
|
|
@ -20,61 +16,46 @@ tools: [Read, Grep, Glob, Shell]
|
|||
|
||||
After `role-ia-architect` for any classification that includes UI work. Skip when convoy frontmatter has `skip: ux`.
|
||||
|
||||
If `design_direction` is locked in the convoy frontmatter, **read it** and map reuse/constraints to that direction — do **not** re-run `ui-ux-pro-max`.
|
||||
|
||||
Two invocation modes:
|
||||
|
||||
1. **Sequential UX-pass** (default) — appends a `## UX` section to the convoy file. Feeds the Architect. Lightweight.
|
||||
2. **Critique pass** (on-request, or when the convoy's success metric is below target) — runs the full 9-step critique per `[skills/design-critique/SKILL.md](../../../design-critique/SKILL.md)` and posts a `design-critique` report.
|
||||
|
||||
## Inputs
|
||||
|
||||
- The convoy file (with the IA section appended).
|
||||
- `design_direction:` in convoy frontmatter and `## Design direction` (if present — from `role-ui-designer`).
|
||||
- Existing UI primitives directory (`components/ui/` or equivalent).
|
||||
- Design tokens (`tailwind.config.ts`, `app/globals.css` CSS variables, or `tokens/**`).
|
||||
- Any rule scoped to `components.mdc`, `styling.mdc`, `design-system.mdc`.
|
||||
- `[skills/design-critique/SKILL.md](../../../design-critique/SKILL.md)` — Nielsen 10 + UX laws + 9-step framework.
|
||||
- The convoy file (with the IA section appended by the previous role).
|
||||
- Existing UI primitives directory (typically `components/ui/` or `src/components/ui/`).
|
||||
- Design tokens (typically `tailwind.config.ts`, `app/globals.css` CSS variables).
|
||||
- Any rule scoped to `components.mdc`, `styling.mdc`, or `design-system.mdc`.
|
||||
|
||||
## Outputs
|
||||
|
||||
### Mode 1: Sequential UX-pass
|
||||
|
||||
Append a `## UX` section to the convoy file with:
|
||||
|
||||
1. **Existing components to reuse** — bullet list of `<ComponentName>` (`path/to/file.tsx`) for each reusable primitive the screens need. Name the file.
|
||||
2. **Design direction alignment** — how locked `design_direction` maps to repo tokens (or note conflicts deferred to human).
|
||||
3. **Existing patterns to follow** — referenced rules and example screens that solve a similar problem.
|
||||
4. **A11y constraints** — bullets enumerating required ARIA labels, keyboard navigation paths, focus management, color-contrast requirements specific to this change. Hand to `role-a11y-auditor`.
|
||||
5. **Interaction patterns** — short list with `required` / `nice-to-have` annotations: hover/focus/active states, optimistic UI, error states, empty states, loading states. Cite Nielsen heuristic # per pattern (`H1` for loading, `H9` for errors, etc.).
|
||||
6. **Anti-patterns to avoid** — explicit list of what NOT to do, with the violated heuristic in parens.
|
||||
7. **Mobile / responsive notes** — mandatory if UI is touched.
|
||||
|
||||
### Mode 2: Critique pass
|
||||
|
||||
Full report following `skills/design-critique/templates/critique-report.md`. Posted as a PR comment OR Echodo `document` (Phase 2b: `create_task_from_template({template: "design-critique", ...})`). Severity ≥ 3 findings spawn child tasks.
|
||||
1. **Existing components to reuse** — bullet list of `<ComponentName>` (`path/to/file.tsx`) for each reusable primitive the screens need. Be specific — name the file.
|
||||
2. **Existing patterns to follow** — referenced rules and example screens that solve a similar problem (e.g. *"PostCard.tsx is the canonical card pattern; use the same Badge primitive there"*).
|
||||
3. **A11y constraints** — bullets enumerating: required ARIA labels, keyboard navigation paths, focus management, color-contrast requirements specific to this change.
|
||||
4. **Interaction patterns** — short list: hover/focus/active states, optimistic UI, error states, empty states, loading states. Mark each as `required` or `nice-to-have`.
|
||||
5. **Anti-patterns to avoid** — explicit list of what NOT to do (e.g. *"Don't add a new color outside the design tokens for the badge background"*).
|
||||
6. **Mobile / responsive notes** — if the change has UI, this section is mandatory. If headless/server-only, note that.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Read the convoy file. Find the IA section.
|
||||
2. For each screen in the IA inventory:
|
||||
- `Glob` for relevant existing components in `components/ui/`.
|
||||
- `Glob` for relevant existing components in `components/ui/` (or equivalent).
|
||||
- Identify the closest existing pattern by reading 1-3 example files.
|
||||
3. Read the design tokens once (single Read of `tailwind.config.ts` or `tokens/**`).
|
||||
4. **Mode 1 (default):** Author the UX section. Be opinionated. Pick one pattern, not three options. Cite specific Nielsen heuristics per pattern. Append section to convoy file. Print: *"UX pass complete. Reuse: <N> primitives. A11y constraints: <M>. Next role: role-architect."*
|
||||
5. **Mode 2 (critique):** Read `[skills/design-critique/SKILL.md](../../../design-critique/SKILL.md)`. Walk the 9 steps in order. Fill the critique-report template. Post the report. If MCP is reachable, call `create_task_from_template` + `link_audit_finding` per skill step 7. Hand off with score + top-3 fixes.
|
||||
3. Read the design tokens once (one Read of `tailwind.config.ts` or `app/globals.css`).
|
||||
4. Author the UX section. Be opinionated. Pick one pattern, not three options.
|
||||
5. Call out a11y requirements explicitly — don't say *"follow a11y best practices"*; say *"requires aria-label on the toggle button when collapsed"*.
|
||||
6. Append section to convoy file.
|
||||
7. Print: *"UX pass complete. Reuse: <N> primitives. A11y constraints: <M>. Next role: role-architect."*
|
||||
|
||||
## Hand-off
|
||||
|
||||
Mode 1: message the user.
|
||||
Mode 2: message: *"UX critique complete. Score X/50. N sev-≥-3 findings. Top 3 fixes: ..."*
|
||||
Message the user.
|
||||
|
||||
## Metrics
|
||||
|
||||
After completing:
|
||||
After appending your UX section, emit one event. Shell access is restricted to this single command.
|
||||
|
||||
```bash
|
||||
bash scripts/log-convoy-event.sh role=role-ux-reviewer convoy=<slug> duration_s=<seconds> model=composer-2.5-fast model_tier=fast
|
||||
bash scripts/log-convoy-event.sh role=role-ux-reviewer convoy=<slug> duration_s=<seconds>
|
||||
```
|
||||
|
||||
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
||||
|
|
@ -82,9 +63,6 @@ Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed)
|
|||
## Anti-patterns
|
||||
|
||||
- Suggesting new components when an existing one fits → wrong, this role's job is reuse.
|
||||
- Vague a11y guidance ("follow WCAG") → wrong, list specific requirements with WCAG numbers.
|
||||
- Three alternatives — pick one with reasoning.
|
||||
- Vague a11y guidance ("follow WCAG") → wrong, list specific requirements.
|
||||
- Three alternatives — pick one → wrong, pick one with reasoning.
|
||||
- Designing the schema or API → wrong, that's Architect.
|
||||
- Critiquing without citing a Nielsen heuristic or UX law → wrong (see `design-critique` anti-patterns). Every finding cites evidence.
|
||||
- Carrying the 9-step critique framework inline in this role file → wrong. Read the skill.
|
||||
- Re-running `ui-ux-pro-max` or rewriting `## Design direction` → wrong, that's `role-ui-designer`.
|
||||
|
|
|
|||
|
|
@ -1,32 +0,0 @@
|
|||
---
|
||||
description: Pipeline planning uses .convoys/*.md — not Cursor Plan files in .cursor/plans/
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Convoy planning (pipeline work)
|
||||
|
||||
When scoping, planning, or kicking off **pipeline work** (features, hotfixes, epics tracked by L2 roles), use **convoy files** — not Cursor's native Plan mode.
|
||||
|
||||
## Where plans live
|
||||
|
||||
| Use case | Location | Who writes it |
|
||||
| --- | --- | --- |
|
||||
| **Pipeline convoy** (idea → briefs → PR) | `.convoys/<slug>.md` | `role-conductor`, then other L2 roles append sections |
|
||||
| **Implementer briefs** | `.convoys/<slug>/brief-<N>-<title>.md` | `role-architect` |
|
||||
| **Cursor Plan mode** (ad-hoc, non-pipeline) | `.cursor/plans/*.plan.md` | Cursor UI — **not** the agent-pipeline |
|
||||
|
||||
## Do
|
||||
|
||||
- Start pipeline work: *"Run role-conductor: start a new convoy for [idea]. Success = [metric]."*
|
||||
- Read [`.convoys/README.md`](.convoys/README.md) for frontmatter, skip flags, and lifecycle.
|
||||
- Read [`.cursor/agents/role-conductor.md`](.cursor/agents/role-conductor.md) before writing a convoy file.
|
||||
|
||||
## Do not
|
||||
|
||||
- Create `.cursor/plans/` files for convoy or L2-role work.
|
||||
- Use vague prompts like *"make a plan"* or *"plan this feature"* when the user meant a convoy — ask once, then invoke the Conductor.
|
||||
- Put architecture or brief content only in chat when a convoy file should exist.
|
||||
|
||||
## If a `.cursor/plans/` file already exists
|
||||
|
||||
That is Cursor's native Plan artifact, not a pipeline convoy. Either delete it, or copy the useful content into `.convoys/<slug>.md` and continue from the convoy file.
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
---
|
||||
description: Model tier defaults for the agent pipeline — Composer Standard for architect; fast/Grok for build and audit; Sonnet 5 escalation
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Model routing (cost-aware pipeline, v0.7)
|
||||
|
||||
Cursor subagent roles in `.cursor/agents/role-*.md` declare a `model:` in frontmatter. **Invoke roles from the Agents dropdown** (or a fresh chat pinned to that role) so the configured model applies. Parent chats on Opus that spawn Task subagents may override role models — see `docs/model-routing-policy.md` (or `docs/agent-context/model-routing-policy.md`).
|
||||
|
||||
## Default session model
|
||||
|
||||
- **Parent chat (ad hoc work):** `auto` or `composer-2.5-fast`.
|
||||
- **Escalate to Sonnet 5** (`claude-sonnet-5-thinking-medium`) for failed implementer briefs or architect-flagged security/schema work.
|
||||
- **Opus** (`claude-4.6-opus-high-thinking`) only when a brief sets `recommended_model: claude-4.6-opus-high-thinking`.
|
||||
- **Never use Opus 4.7 / xhigh** for routine pipeline work.
|
||||
|
||||
## Per-role tiers (canonical, v0.7)
|
||||
|
||||
| Tier | Roles | Model |
|
||||
| --- | --- | --- |
|
||||
| Standard | architect | `composer-2.5` (Standard mode in picker) |
|
||||
| Fast | conductor, ia-architect, ui-designer, ux-reviewer, implementer | `composer-2.5-fast` |
|
||||
| Audit | reviewer, design-system-auditor, a11y-auditor | `cursor-grok-4.5-high` |
|
||||
| Security | security-auditor | `gpt-5.6-terra-medium` |
|
||||
| Auto | doc-writer | `auto` |
|
||||
|
||||
Read `model_policy:` from the convoy frontmatter when present; it overrides these defaults for that convoy.
|
||||
|
||||
## Context discipline (biggest cost lever)
|
||||
|
||||
- Implementers and auditors: read **only** the brief + files in `files:` — not the whole convoy, not `prisma/schema.prisma` unless listed.
|
||||
- Audits: diff + brief only; no repo-wide grep sweeps.
|
||||
- Stop and ask before any single chat exceeds ~5M tokens; start a fresh scoped chat instead.
|
||||
|
||||
## Metrics
|
||||
|
||||
After each role, log `model=` and `model_tier=` via `scripts/log-convoy-event.sh` (see each role's Metrics section).
|
||||
|
|
@ -28,7 +28,7 @@ Do not edit, refactor, or quote as context examples. If you think you need to ch
|
|||
## Local-only / per-developer
|
||||
|
||||
- `.code-review-graph/` — local MCP graph index (only if `user-code-review-graph` is installed)
|
||||
- `.convoys/.metrics.jsonl` — convoy role-event telemetry (tracked in git when metrics gate is installed; otherwise gitignored)
|
||||
- `.convoys/.metrics.jsonl` — per-developer convoy analytics (gitignored by default)
|
||||
|
||||
## Editing rules of thumb
|
||||
|
||||
|
|
|
|||
|
|
@ -1,39 +0,0 @@
|
|||
---
|
||||
description: Security baseline — secrets, input validation, auth boundaries, logging
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Security baseline
|
||||
|
||||
Complements `no-go-zones.mdc` (what not to touch) with **how to write secure code**. For auth specifics, see `auth-patterns.mdc` and `api-routes.mdc` when installed.
|
||||
|
||||
## Secrets
|
||||
|
||||
- Never commit credentials, API keys, tokens, or private keys. Use environment variables.
|
||||
- Never log passwords, session tokens, or full payment details.
|
||||
- Never expose secrets to the browser (`NEXT_PUBLIC_*` is public forever).
|
||||
- If a secret appears in git history, rotate it — deleting the commit line is not enough.
|
||||
|
||||
## Input & output
|
||||
|
||||
- Validate every request body and untrusted query param at the API boundary (Zod or repo equivalent).
|
||||
- Parameterize database queries — no string concatenation with user input.
|
||||
- Return generic errors to clients; put details in server logs only.
|
||||
- Do not reflect raw user input into HTML without sanitization.
|
||||
|
||||
## Auth
|
||||
|
||||
- Protected routes must call the repo's auth helper **before** business logic.
|
||||
- Authorization: verify the session user may access **this** resource (IDOR prevention).
|
||||
- Rate-limit authentication endpoints (login, register, password reset).
|
||||
- No dev-only auth bypass in production code paths.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Run `npm audit` / `pnpm audit` before merging dependency changes.
|
||||
- Do not add packages for one-liners when the stdlib or an existing dep suffices.
|
||||
|
||||
## Pipeline
|
||||
|
||||
- For convoy work, run `role-security-auditor` in the audit fan-out unless `skip: security` is set.
|
||||
- Security findings with severity ≥ 3 block merge unless the convoy documents an accepted risk.
|
||||
|
|
@ -1,108 +0,0 @@
|
|||
---
|
||||
name: security-audit
|
||||
description: >-
|
||||
Run an application-security audit on a code diff or surface. Produces a
|
||||
severity-ranked findings report keyed to OWASP-style categories (authZ,
|
||||
injection, secrets, IDOR, SSRF, dependencies). Use when role-security-auditor
|
||||
is invoked, when the user asks for a security review, before merging
|
||||
auth/API/data convoys, or whenever a change touches authentication,
|
||||
authorization, API routes, middleware, env config, or user-controlled input.
|
||||
Skip if `skip: security` is set in the convoy or the change is docs-only
|
||||
with no executable code.
|
||||
---
|
||||
|
||||
# Security audit
|
||||
|
||||
Six-layer audit framework for **application code** (not infra/IAM — those are separate convoys). Outputs a severity 0–4 findings list, an executive summary, and fix suggestions with file:line citations. Deep reference: `references/owasp-checklist.md`.
|
||||
|
||||
## When to invoke
|
||||
|
||||
- **Automatic:** by `role-security-auditor` on every PR draft except when `skip: security` is set.
|
||||
- **Manual:** when the user says *"security review"*, *"audit this for vulnerabilities"*, or before merging auth/API/schema convoys.
|
||||
- **Pre-merge:** audit fan-out — `/multitask role-reviewer + role-security-auditor + role-design-system-auditor + role-a11y-auditor`.
|
||||
|
||||
## Severity scale
|
||||
|
||||
| Severity | Meaning | Treatment |
|
||||
| --- | --- | --- |
|
||||
| **4 — Critical** | Exploitable without unusual conditions: auth bypass, secret in client bundle, SQL/command injection on user input, IDOR on another user's data. | Block merge. |
|
||||
| **3 — High** | Serious weakness requiring attacker effort or specific config: missing rate limit on auth, weak session TTL, missing auth on non-public route, mass assignment. | Fix before merge unless documented exception in convoy. |
|
||||
| **2 — Medium** | Defense-in-depth gap: verbose error leaks stack trace, missing security headers, log line includes PII. | Fix or track; recommend before next release. |
|
||||
| **1 — Low** | Hardening opportunity: inconsistent auth helper usage, missing Zod on low-risk query param. | Inline in report. |
|
||||
| **0 — Info** | Note for maintainer; not a defect. | Inline only. |
|
||||
|
||||
## The 6 layers
|
||||
|
||||
Run in order. Stop early only if the diff is literally comment-only.
|
||||
|
||||
### Layer 1 — Authentication boundary
|
||||
|
||||
Every protected route and server action must identify the caller before doing work.
|
||||
|
||||
- New or changed API routes / server actions: is there an auth gate (`requireAuth`, `auth()`, session check, Bearer verify)?
|
||||
- Auth endpoints: rate limiting present? (`checkAuthRateLimit` or equivalent)
|
||||
- No synthetic-admin / dev-bypass fallbacks in production paths
|
||||
- JWT/session: secret from env (fail-loud if unset), reasonable TTL, not in client bundle
|
||||
- Password handling: hashed (bcrypt/argon2), never logged, never returned in API responses
|
||||
|
||||
### Layer 2 — Authorization (IDOR / tenancy)
|
||||
|
||||
Authentication ≠ authorization. Check resource ownership on every read/write.
|
||||
|
||||
- Every query scoped by `userId` / `tenantId` / collection permission — not just "user is logged in"
|
||||
- Path params (`/api/users/:id`) validated against session identity
|
||||
- Admin routes use dedicated guard (`requireAdmin`, `withAdmin`) — not inline role string compare copy-pasted
|
||||
- Public vs private resources: `is_public` / share links cannot leak other users' data
|
||||
|
||||
### Layer 3 — Input validation & injection
|
||||
|
||||
All user-controlled input validated at the boundary.
|
||||
|
||||
- Request bodies: Zod/schema validation (or repo equivalent) — no trusting `req.body` shape
|
||||
- SQL: parameterized queries / ORM — no string concatenation with user input; no `sql.unsafe` with user data
|
||||
- Shell commands: no `exec`/`spawn` with user input; no `eval`
|
||||
- HTML/XSS: no `dangerouslySetInnerHTML` without sanitization; no reflecting raw user input in responses
|
||||
- File upload: type/size limits, storage path not user-controlled
|
||||
|
||||
### Layer 4 — Secrets & sensitive data
|
||||
|
||||
- No API keys, tokens, passwords in source, comments, or client bundles
|
||||
- `.env` values not committed; no `NEXT_PUBLIC_*` for secrets
|
||||
- Logs: no passwords, tokens, full credit card numbers, or session cookies
|
||||
- Error responses: generic message to client; details server-side only
|
||||
|
||||
### Layer 5 — Dependencies & supply chain
|
||||
|
||||
- Run `npm audit` / `pnpm audit` when Shell is available; surface high/critical in report
|
||||
- New dependencies: justified? Known risky packages?
|
||||
- Pin or review major version bumps on auth/crypto libraries
|
||||
|
||||
### Layer 6 — Transport & headers (when diff touches middleware / next.config / server)
|
||||
|
||||
- Cookies: `HttpOnly`, `Secure`, `SameSite` where applicable
|
||||
- CORS: no wildcard `*` on authenticated APIs unless explicitly documented
|
||||
- Security headers: CSP, X-Frame-Options / frame-ancestors where relevant
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Scope read.** `git diff` + brief `files:` list. Flag any file outside scope as Critical (scope expansion).
|
||||
2. **Read repo auth rules.** `.cursor/rules/auth-patterns.mdc`, `api-routes.mdc`, `AGENTS.md` auth section — match repo conventions, don't invent new ones.
|
||||
3. **Layer pass 1 → 6.** For each finding: category, severity, file:line, exploit scenario (one sentence), fix (verbatim diff when possible).
|
||||
4. **Automated sweep (optional).** `npm audit --json`, `grep` for `dangerouslySetInnerHTML`, `eval(`, hardcoded `sk-`, `password\s*=`.
|
||||
5. **Report.** Fill `templates/audit-report.md`. Post as `## Security Audit` PR comment (exact header — rollup CI parses it).
|
||||
6. **Hand off:** *"Security audit complete. N findings (sev ≥ 3: M). Recommend fixing sev ≥ 3 before merge."*
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Marking style nits as Critical — credibility matters.
|
||||
- Auditing without reading the brief — scope expansion is the first check.
|
||||
- Recommending auth patterns the repo doesn't use — read `auth-patterns.mdc` first.
|
||||
- Skipping layer 2 because "route requires login" — IDOR lives here.
|
||||
|
||||
## References
|
||||
|
||||
- `references/owasp-checklist.md` — expanded checklist by layer.
|
||||
|
||||
## Output template
|
||||
|
||||
- `templates/audit-report.md` — fillable report for PR comment or `.convoys/<slug>/audits/security-<timestamp>.md` mirror.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
# OWASP-aligned security checklist (agent reference)
|
||||
|
||||
Cite the **layer + item** in findings (e.g. "Layer 2 — IDOR"). Not a substitute for penetration testing.
|
||||
|
||||
## Layer 1 — Authentication
|
||||
|
||||
- [ ] All non-public API routes call a shared auth helper
|
||||
- [ ] Login/register/forgot-password rate limited
|
||||
- [ ] Session/JWT secret from environment; app fails start if missing
|
||||
- [ ] No long-lived tokens in `localStorage` without documented threat model
|
||||
- [ ] Password reset tokens single-use + short TTL
|
||||
- [ ] No credentials in URLs or query strings
|
||||
|
||||
## Layer 2 — Authorization
|
||||
|
||||
- [ ] Resource IDs in path/body checked against session user/tenant
|
||||
- [ ] List endpoints filter by ownership — no "return all rows"
|
||||
- [ ] Admin operations behind explicit admin guard
|
||||
- [ ] Role checks use server-side source of truth (DB), not client-only flags
|
||||
- [ ] Bulk operations cannot target arbitrary user IDs
|
||||
|
||||
## Layer 3 — Input & injection
|
||||
|
||||
- [ ] All POST/PATCH/PUT bodies validated with schema
|
||||
- [ ] Query params validated/coerced (Zod `z.coerce` or explicit parse)
|
||||
- [ ] ORM/raw SQL uses parameters only
|
||||
- [ ] No `dangerouslySetInnerHTML` without DOMPurify or equivalent
|
||||
- [ ] File paths constructed server-side; no `../` from user input
|
||||
- [ ] SSRF: server-side fetch URLs not user-controlled to internal IPs
|
||||
|
||||
## Layer 4 — Secrets & data
|
||||
|
||||
- [ ] No secrets in git history in this diff
|
||||
- [ ] `NEXT_PUBLIC_` prefix only on truly public values
|
||||
- [ ] PII minimized in logs and analytics events
|
||||
- [ ] API responses omit internal IDs when unnecessary
|
||||
|
||||
## Layer 5 — Dependencies
|
||||
|
||||
- [ ] No new high/critical `npm audit` findings introduced
|
||||
- [ ] Auth/crypto libs from reputable sources, pinned versions
|
||||
|
||||
## Layer 6 — Transport & config
|
||||
|
||||
- [ ] Auth cookies: Secure + HttpOnly
|
||||
- [ ] CORS allowlist explicit for API routes
|
||||
- [ ] Webhook endpoints verify signatures
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
# Security audit — {{convoy_slug}} / brief-{{brief_n}}
|
||||
|
||||
**Reviewer:** role-security-auditor
|
||||
**Convoy:** {{convoy_slug}}
|
||||
**Brief / PR:** {{brief_n}} / {{pr_number_or_draft}}
|
||||
**Date:** {{YYYY-MM-DD}}
|
||||
**Diff scope:** {{files_changed_count}} files
|
||||
|
||||
## Executive summary
|
||||
|
||||
- {{bullet 1 — overall risk posture}}
|
||||
- {{bullet 2 — highest severity finding or "no sev ≥ 3"}}
|
||||
- {{bullet 3 — auth/IDOR/injection/deps headline}}
|
||||
|
||||
## Findings
|
||||
|
||||
| Sev | Layer | Surface | Issue | Fix |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 4 | L2 AuthZ | `app/api/foo/route.ts:42` | IDOR: `userId` from path not checked against session | Add `if (session.user.id !== params.id) return forbidden()` |
|
||||
| 2 | L3 Input | `app/api/bar/route.ts:18` | Body not validated | Add Zod schema per `api-routes.mdc` |
|
||||
|
||||
### Severity ≥ 3 detail
|
||||
|
||||
{{Expand each sev 3–4 with exploit scenario + suggested patch.}}
|
||||
|
||||
### Patterns (optional)
|
||||
|
||||
{{One row if the same mistake appears 3+ times.}}
|
||||
|
||||
## Automated checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| `npm audit` (high+) | {{pass / N findings}} |
|
||||
| Hardcoded secret grep | {{pass / findings}} |
|
||||
|
||||
## Approval recommendation
|
||||
|
||||
- [ ] **approve** — no sev ≥ 3; sev 2 acceptable with notes
|
||||
- [ ] **request-changes** — sev ≥ 3 open
|
||||
- [ ] **comment-only** — informational
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2024 Next Level Builder
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
<!--
|
||||
Vendored engine: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — see UPSTREAM.md, LICENSE, data/, scripts/.
|
||||
Pipeline wrapper: agent-pipeline — planning-only; paired with role-ui-designer.
|
||||
-->
|
||||
---
|
||||
name: ui-ux-pro-max
|
||||
description: >-
|
||||
Generate a locked design direction for greenfield UI (pattern, palette,
|
||||
typography, anti-patterns) from product type. Planning phase only — invoke
|
||||
via role-ui-designer at convoy start or on explicit redesign. Do not use
|
||||
during audit fan-out or incremental UI tweaks inside an existing DS.
|
||||
---
|
||||
|
||||
# UI UX Pro Max (planning)
|
||||
|
||||
Data-driven design intelligence: industry rules, styles, palettes, typography, and stack guidelines. **Generate once, lock in the convoy, enforce later** with `design-critique`, `design-systems`, and `accessibility-audit`.
|
||||
|
||||
## When to invoke
|
||||
|
||||
| Do | Don't |
|
||||
| --- | --- |
|
||||
| New screen, landing, marketing surface, major visual refresh | Hotfix, docs-only, server-only |
|
||||
| User says *redesign* or bumps `design_direction.version` | Audit fan-out on a PR diff |
|
||||
| `role-ui-designer` at convoy start (skill installed) | Every implementer brief |
|
||||
| Re-run after explicit redesign request | Auto-re-run because code "looks off" |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.x on the machine running the agent (`python3 --version`).
|
||||
- Skill installed at `.cursor/skills/ui-ux-pro-max/` (bootstrap opt-in).
|
||||
|
||||
## Generate a design system (primary workflow)
|
||||
|
||||
From repo root:
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py \
|
||||
"<product type query>" \
|
||||
--design-system \
|
||||
-p "<Project or convoy name>"
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py "B2B SaaS analytics dashboard" --design-system -p "Deck Hearth admin"
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py "wellness spa booking" --design-system -p "Serenity Spa"
|
||||
```
|
||||
|
||||
Pick stack-specific guidelines when the convoy targets a known stack:
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/ui-ux-pro-max/scripts/search.py "checkout flow" --stack nextjs --max-results 5
|
||||
```
|
||||
|
||||
## Lock in the convoy
|
||||
|
||||
1. Parse generator output into `skills/ui-ux-pro-max/templates/design-direction.md`.
|
||||
2. Append `## Design direction` to `.convoys/<slug>.md`.
|
||||
3. Set frontmatter:
|
||||
|
||||
```yaml
|
||||
design_direction:
|
||||
source: role-ui-designer
|
||||
skill: ui-ux-pro-max
|
||||
skill_version: "2.5.0"
|
||||
version: 1
|
||||
locked_at: YYYY-MM-DD
|
||||
product_type: "<from query>"
|
||||
pattern: "<from output>"
|
||||
style: "<from output>"
|
||||
stack: nextjs
|
||||
```
|
||||
|
||||
On **redesign**, bump `version` and replace the section — do not edit in place without bumping.
|
||||
|
||||
## Hand-off to other skills
|
||||
|
||||
| Next | Role / skill | Job |
|
||||
| --- | --- | --- |
|
||||
| Reuse + constraints | `role-ux-reviewer` | Maps locked direction to existing components; a11y constraints |
|
||||
| Briefs | `role-architect` | Briefs must not contradict `design_direction` |
|
||||
| Enforce | audit fan-out | `design-systems`, `accessibility-audit`, `design-critique` on the diff |
|
||||
|
||||
**Conflict rule:** repo tokens (`tailwind.config`, `globals.css`, `components/ui/`) **win** over generated palettes unless the convoy records an approved override.
|
||||
|
||||
## What this skill does NOT do
|
||||
|
||||
- Replace `design-critique` / `design-systems` / `accessibility-audit` at PR time.
|
||||
- Commit code or open PRs.
|
||||
- Install npm packages or fonts — implementer adds dependencies per brief.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Running the generator during audit fan-out.
|
||||
- Re-running on brief 2, 3, … without a redesign request.
|
||||
- Ignoring existing repo DS when the convoy is incremental UI (`skip: ui-design`).
|
||||
- Loading entire `data/*.csv` into chat — always use `scripts/search.py`.
|
||||
|
||||
## References
|
||||
|
||||
- Upstream docs: [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)
|
||||
- Convoy output template: `templates/design-direction.md`
|
||||
- L2 role: `role-ui-designer` in `.cursor/agents/`
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
# Upstream: UI UX Pro Max
|
||||
|
||||
Vendored from [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill).
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Upstream tag | `v2.6.2` (clone ref `d457006`) |
|
||||
| Upstream `skill.json` version | `2.5.0` |
|
||||
| License | MIT — see `LICENSE` |
|
||||
| Vendored paths | `data/`, `scripts/` |
|
||||
|
||||
Do not edit `data/` or `scripts/` in place for pipeline-specific behavior — wrap in `SKILL.md` and `role-ui-designer.md` instead. To refresh from upstream, replace `data/` + `scripts/` from a new tag and bump this file.
|
||||
|
|
@ -1,414 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
"""
|
||||
Sync colors.csv and ui-reasoning.csv with the updated products.csv (161 entries).
|
||||
- Remove deleted product types
|
||||
- Rename mismatched entries
|
||||
- Add new entries for missing product types
|
||||
- Keep colors.csv aligned 1:1 with products.csv
|
||||
- Renumber everything
|
||||
"""
|
||||
import csv, os, json
|
||||
|
||||
BASE = os.path.dirname(os.path.abspath(__file__))
|
||||
|
||||
# ─── Color derivation helpers ────────────────────────────────────────────────
|
||||
def h2r(h):
|
||||
h = h.lstrip("#")
|
||||
return tuple(int(h[i:i+2], 16) for i in (0, 2, 4))
|
||||
|
||||
def r2h(r, g, b):
|
||||
return f"#{max(0,min(255,int(r))):02X}{max(0,min(255,int(g))):02X}{max(0,min(255,int(b))):02X}"
|
||||
|
||||
def lum(h):
|
||||
r, g, b = [x/255.0 for x in h2r(h)]
|
||||
r, g, b = [(x/12.92 if x<=0.03928 else ((x+0.055)/1.055)**2.4) for x in (r, g, b)]
|
||||
return 0.2126*r + 0.7152*g + 0.0722*b
|
||||
|
||||
def is_dark(bg):
|
||||
return lum(bg) < 0.18
|
||||
|
||||
def on_color(bg):
|
||||
return "#FFFFFF" if lum(bg) < 0.4 else "#0F172A"
|
||||
|
||||
def blend(a, b, f=0.15):
|
||||
ra, ga, ba = h2r(a)
|
||||
rb, gb, bb = h2r(b)
|
||||
return r2h(ra+(rb-ra)*f, ga+(gb-ga)*f, ba+(bb-ba)*f)
|
||||
|
||||
def shift(h, n):
|
||||
r, g, b = h2r(h)
|
||||
return r2h(r+n, g+n, b+n)
|
||||
|
||||
def derive_row(pt, pri, sec, acc, bg, notes=""):
|
||||
"""Generate full 16-token color row from 4 base colors."""
|
||||
dark = is_dark(bg)
|
||||
fg = "#FFFFFF" if dark else "#0F172A"
|
||||
on_pri = on_color(pri)
|
||||
on_sec = on_color(sec)
|
||||
on_acc = on_color(acc)
|
||||
card = shift(bg, 10) if dark else "#FFFFFF"
|
||||
card_fg = "#FFFFFF" if dark else "#0F172A"
|
||||
muted = blend(bg, pri, 0.08) if dark else blend("#FFFFFF", pri, 0.06)
|
||||
muted_fg = "#94A3B8" if dark else "#64748B"
|
||||
border = f"rgba(255,255,255,0.08)" if dark else blend("#FFFFFF", pri, 0.12)
|
||||
destr = "#DC2626"
|
||||
on_destr = "#FFFFFF"
|
||||
ring = pri
|
||||
return [pt, pri, on_pri, sec, on_sec, acc, on_acc, bg, fg, card, card_fg, muted, muted_fg, border, destr, on_destr, ring, notes]
|
||||
|
||||
# ─── Rename maps ─────────────────────────────────────────────────────────────
|
||||
COLOR_RENAMES = {
|
||||
"Quantum Computing": "Quantum Computing Interface",
|
||||
"Biohacking / Longevity": "Biohacking / Longevity App",
|
||||
"Autonomous Systems": "Autonomous Drone Fleet Manager",
|
||||
"Generative AI Art": "Generative Art Platform",
|
||||
"Spatial / Vision OS": "Spatial Computing OS / App",
|
||||
"Climate Tech": "Sustainable Energy / Climate Tech",
|
||||
}
|
||||
UI_RENAMES = {
|
||||
"Architecture/Interior": "Architecture / Interior",
|
||||
"Autonomous Drone Fleet": "Autonomous Drone Fleet Manager",
|
||||
"B2B SaaS Enterprise": "B2B Service",
|
||||
"Biohacking/Longevity App": "Biohacking / Longevity App",
|
||||
"Biotech/Life Sciences": "Biotech / Life Sciences",
|
||||
"Developer Tool/IDE": "Developer Tool / IDE",
|
||||
"Education": "Educational App",
|
||||
"Fintech (Banking)": "Fintech/Crypto",
|
||||
"Government/Public": "Government/Public Service",
|
||||
"Home Services": "Home Services (Plumber/Electrician)",
|
||||
"Micro-Credentials/Badges": "Micro-Credentials/Badges Platform",
|
||||
"Music/Entertainment": "Music Streaming",
|
||||
"Quantum Computing": "Quantum Computing Interface",
|
||||
"Real Estate": "Real Estate/Property",
|
||||
"Remote Work/Collaboration": "Remote Work/Collaboration Tool",
|
||||
"Restaurant/Food": "Restaurant/Food Service",
|
||||
"SaaS Dashboard": "Analytics Dashboard",
|
||||
"Space Tech/Aerospace": "Space Tech / Aerospace",
|
||||
"Spatial Computing OS": "Spatial Computing OS / App",
|
||||
"Startup Landing": "Micro SaaS",
|
||||
"Sustainable Energy/Climate": "Sustainable Energy / Climate Tech",
|
||||
"Travel/Tourism": "Travel/Tourism Agency",
|
||||
"Wellness/Mental Health": "Mental Health App",
|
||||
}
|
||||
|
||||
REMOVE_TYPES = {
|
||||
"Service Landing Page", "Sustainability/ESG Platform",
|
||||
"Cleaning Service", "Coffee Shop",
|
||||
"Consulting Firm", "Conference/Webinar Platform",
|
||||
}
|
||||
|
||||
# ─── New color definitions: (primary, secondary, accent, bg, notes) ──────────
|
||||
# Grouped by category for clarity. Each tuple generates a full 16-token row.
|
||||
NEW_COLORS = {
|
||||
# ── Old #97-#116 that never got colors ──
|
||||
"Todo & Task Manager": ("#2563EB","#3B82F6","#059669","#F8FAFC","Functional blue + progress green"),
|
||||
"Personal Finance Tracker": ("#1E40AF","#3B82F6","#059669","#0F172A","Trust blue + profit green on dark"),
|
||||
"Chat & Messaging App": ("#2563EB","#6366F1","#059669","#FFFFFF","Messenger blue + online green"),
|
||||
"Notes & Writing App": ("#78716C","#A8A29E","#D97706","#FFFBEB","Warm ink + amber accent on cream"),
|
||||
"Habit Tracker": ("#D97706","#F59E0B","#059669","#FFFBEB","Streak amber + habit green"),
|
||||
"Food Delivery / On-Demand": ("#EA580C","#F97316","#2563EB","#FFF7ED","Appetizing orange + trust blue"),
|
||||
"Ride Hailing / Transportation":("#1E293B","#334155","#2563EB","#0F172A","Map dark + route blue"),
|
||||
"Recipe & Cooking App": ("#9A3412","#C2410C","#059669","#FFFBEB","Warm terracotta + fresh green"),
|
||||
"Meditation & Mindfulness": ("#7C3AED","#8B5CF6","#059669","#FAF5FF","Calm lavender + mindful green"),
|
||||
"Weather App": ("#0284C7","#0EA5E9","#F59E0B","#F0F9FF","Sky blue + sun amber"),
|
||||
"Diary & Journal App": ("#92400E","#A16207","#6366F1","#FFFBEB","Warm journal brown + ink violet"),
|
||||
"CRM & Client Management": ("#2563EB","#3B82F6","#059669","#F8FAFC","Professional blue + deal green"),
|
||||
"Inventory & Stock Management":("#334155","#475569","#059669","#F8FAFC","Industrial slate + stock green"),
|
||||
"Flashcard & Study Tool": ("#7C3AED","#8B5CF6","#059669","#FAF5FF","Study purple + correct green"),
|
||||
"Booking & Appointment App": ("#0284C7","#0EA5E9","#059669","#F0F9FF","Calendar blue + available green"),
|
||||
"Invoice & Billing Tool": ("#1E3A5F","#2563EB","#059669","#F8FAFC","Navy professional + paid green"),
|
||||
"Grocery & Shopping List": ("#059669","#10B981","#D97706","#ECFDF5","Fresh green + food amber"),
|
||||
"Timer & Pomodoro": ("#DC2626","#EF4444","#059669","#0F172A","Focus red on dark + break green"),
|
||||
"Parenting & Baby Tracker": ("#EC4899","#F472B6","#0284C7","#FDF2F8","Soft pink + trust blue"),
|
||||
"Scanner & Document Manager": ("#1E293B","#334155","#2563EB","#F8FAFC","Document grey + scan blue"),
|
||||
# ── A. Utility / Productivity ──
|
||||
"Calendar & Scheduling App": ("#2563EB","#3B82F6","#059669","#F8FAFC","Calendar blue + event green"),
|
||||
"Password Manager": ("#1E3A5F","#334155","#059669","#0F172A","Vault dark blue + secure green"),
|
||||
"Expense Splitter / Bill Split":("#059669","#10B981","#DC2626","#F8FAFC","Balance green + owe red"),
|
||||
"Voice Recorder & Memo": ("#DC2626","#EF4444","#2563EB","#FFFFFF","Recording red + waveform blue"),
|
||||
"Bookmark & Read-Later": ("#D97706","#F59E0B","#2563EB","#FFFBEB","Warm amber + link blue"),
|
||||
"Translator App": ("#2563EB","#0891B2","#EA580C","#F8FAFC","Global blue + teal + accent orange"),
|
||||
"Calculator & Unit Converter": ("#EA580C","#F97316","#2563EB","#1C1917","Operation orange on dark"),
|
||||
"Alarm & World Clock": ("#D97706","#F59E0B","#6366F1","#0F172A","Time amber + night indigo on dark"),
|
||||
"File Manager & Transfer": ("#2563EB","#3B82F6","#D97706","#F8FAFC","Folder blue + file amber"),
|
||||
"Email Client": ("#2563EB","#3B82F6","#DC2626","#FFFFFF","Inbox blue + priority red"),
|
||||
# ── B. Games ──
|
||||
"Casual Puzzle Game": ("#EC4899","#8B5CF6","#F59E0B","#FDF2F8","Cheerful pink + reward gold"),
|
||||
"Trivia & Quiz Game": ("#2563EB","#7C3AED","#F59E0B","#EFF6FF","Quiz blue + gold leaderboard"),
|
||||
"Card & Board Game": ("#15803D","#166534","#D97706","#0F172A","Felt green + gold on dark"),
|
||||
"Idle & Clicker Game": ("#D97706","#F59E0B","#7C3AED","#FFFBEB","Coin gold + prestige purple"),
|
||||
"Word & Crossword Game": ("#15803D","#059669","#D97706","#FFFFFF","Word green + letter amber"),
|
||||
"Arcade & Retro Game": ("#DC2626","#2563EB","#22C55E","#0F172A","Neon red+blue on dark + score green"),
|
||||
# ── C. Creator Tools ──
|
||||
"Photo Editor & Filters": ("#7C3AED","#6366F1","#0891B2","#0F172A","Editor violet + filter cyan on dark"),
|
||||
"Short Video Editor": ("#EC4899","#DB2777","#2563EB","#0F172A","Video pink on dark + timeline blue"),
|
||||
"Drawing & Sketching Canvas": ("#7C3AED","#8B5CF6","#0891B2","#1C1917","Canvas purple + tool teal on dark"),
|
||||
"Music Creation & Beat Maker": ("#7C3AED","#6366F1","#22C55E","#0F172A","Studio purple + waveform green on dark"),
|
||||
"Meme & Sticker Maker": ("#EC4899","#F59E0B","#2563EB","#FFFFFF","Viral pink + comedy yellow + share blue"),
|
||||
"AI Photo & Avatar Generator": ("#7C3AED","#6366F1","#EC4899","#FAF5FF","AI purple + generation pink"),
|
||||
"Link-in-Bio Page Builder": ("#2563EB","#7C3AED","#EC4899","#FFFFFF","Brand blue + creator purple"),
|
||||
# ── D. Personal Life ──
|
||||
"Wardrobe & Outfit Planner": ("#BE185D","#EC4899","#D97706","#FDF2F8","Fashion rose + gold accent"),
|
||||
"Plant Care Tracker": ("#15803D","#059669","#D97706","#F0FDF4","Nature green + sun yellow"),
|
||||
"Book & Reading Tracker": ("#78716C","#92400E","#D97706","#FFFBEB","Book brown + page amber"),
|
||||
"Couple & Relationship App": ("#BE185D","#EC4899","#DC2626","#FDF2F8","Romance rose + love red"),
|
||||
"Family Calendar & Chores": ("#2563EB","#059669","#D97706","#F8FAFC","Family blue + chore green"),
|
||||
"Mood Tracker": ("#7C3AED","#6366F1","#D97706","#FAF5FF","Mood purple + insight amber"),
|
||||
"Gift & Wishlist": ("#DC2626","#D97706","#EC4899","#FFF1F2","Gift red + gold + surprise pink"),
|
||||
# ── E. Health ──
|
||||
"Running & Cycling GPS": ("#EA580C","#F97316","#059669","#0F172A","Energetic orange + pace green on dark"),
|
||||
"Yoga & Stretching Guide": ("#6B7280","#78716C","#0891B2","#F5F5F0","Sage neutral + calm teal"),
|
||||
"Sleep Tracker": ("#4338CA","#6366F1","#7C3AED","#0F172A","Night indigo + dream violet on dark"),
|
||||
"Calorie & Nutrition Counter": ("#059669","#10B981","#EA580C","#ECFDF5","Healthy green + macro orange"),
|
||||
"Period & Cycle Tracker": ("#BE185D","#EC4899","#7C3AED","#FDF2F8","Blush rose + fertility lavender"),
|
||||
"Medication & Pill Reminder": ("#0284C7","#0891B2","#DC2626","#F0F9FF","Medical blue + alert red"),
|
||||
"Water & Hydration Reminder": ("#0284C7","#06B6D4","#0891B2","#F0F9FF","Refreshing blue + water cyan"),
|
||||
"Fasting & Intermittent Timer":("#6366F1","#4338CA","#059669","#0F172A","Fasting indigo on dark + eating green"),
|
||||
# ── F. Social ──
|
||||
"Anonymous Community / Confession":("#475569","#334155","#0891B2","#0F172A","Protective grey + subtle teal on dark"),
|
||||
"Local Events & Discovery": ("#EA580C","#F97316","#2563EB","#FFF7ED","Event orange + map blue"),
|
||||
"Study Together / Virtual Coworking":("#2563EB","#3B82F6","#059669","#F8FAFC","Focus blue + session green"),
|
||||
# ── G. Education ──
|
||||
"Coding Challenge & Practice": ("#22C55E","#059669","#D97706","#0F172A","Code green + difficulty amber on dark"),
|
||||
"Kids Learning (ABC & Math)": ("#2563EB","#F59E0B","#EC4899","#EFF6FF","Learning blue + play yellow + fun pink"),
|
||||
"Music Instrument Learning": ("#DC2626","#9A3412","#D97706","#FFFBEB","Musical red + warm amber"),
|
||||
# ── H. Transport ──
|
||||
"Parking Finder": ("#2563EB","#059669","#DC2626","#F0F9FF","Available blue/green + occupied red"),
|
||||
"Public Transit Guide": ("#2563EB","#0891B2","#EA580C","#F8FAFC","Transit blue + line colors"),
|
||||
"Road Trip Planner": ("#EA580C","#0891B2","#D97706","#FFF7ED","Adventure orange + map teal"),
|
||||
# ── I. Safety & Lifestyle ──
|
||||
"VPN & Privacy Tool": ("#1E3A5F","#334155","#22C55E","#0F172A","Shield dark + connected green"),
|
||||
"Emergency SOS & Safety": ("#DC2626","#EF4444","#2563EB","#FFF1F2","Alert red + safety blue"),
|
||||
"Wallpaper & Theme App": ("#7C3AED","#EC4899","#2563EB","#FAF5FF","Aesthetic purple + trending pink"),
|
||||
"White Noise & Ambient Sound": ("#475569","#334155","#4338CA","#0F172A","Ambient grey + deep indigo on dark"),
|
||||
"Home Decoration & Interior Design":("#78716C","#A8A29E","#D97706","#FAF5F2","Interior warm grey + gold accent"),
|
||||
}
|
||||
|
||||
# ─── 1. REBUILD colors.csv ───────────────────────────────────────────────────
|
||||
def rebuild_colors():
|
||||
src = os.path.join(BASE, "colors.csv")
|
||||
with open(src, newline="", encoding="utf-8") as f:
|
||||
reader = csv.DictReader(f)
|
||||
headers = reader.fieldnames
|
||||
existing = list(reader)
|
||||
|
||||
# Build lookup: Product Type -> row data
|
||||
color_map = {}
|
||||
for row in existing:
|
||||
pt = row.get("Product Type", "").strip()
|
||||
if not pt:
|
||||
continue
|
||||
# Remove deleted types
|
||||
if pt in REMOVE_TYPES:
|
||||
print(f" [colors] REMOVE: {pt}")
|
||||
continue
|
||||
# Rename mismatched types
|
||||
if pt in COLOR_RENAMES:
|
||||
new_name = COLOR_RENAMES[pt]
|
||||
print(f" [colors] RENAME: {pt} → {new_name}")
|
||||
row["Product Type"] = new_name
|
||||
pt = new_name
|
||||
color_map[pt] = row
|
||||
|
||||
# Read products.csv to get the correct order
|
||||
with open(os.path.join(BASE, "products.csv"), newline="", encoding="utf-8") as f:
|
||||
products = list(csv.DictReader(f))
|
||||
|
||||
# Build final rows in products.csv order
|
||||
final_rows = []
|
||||
added = 0
|
||||
for i, prod in enumerate(products, 1):
|
||||
pt = prod["Product Type"]
|
||||
if pt in color_map:
|
||||
row = color_map[pt]
|
||||
row["No"] = str(i)
|
||||
final_rows.append(row)
|
||||
elif pt in NEW_COLORS:
|
||||
pri, sec, acc, bg, notes = NEW_COLORS[pt]
|
||||
new_row = derive_row(pt, pri, sec, acc, bg, notes)
|
||||
d = dict(zip(headers, [str(i)] + new_row))
|
||||
final_rows.append(d)
|
||||
added += 1
|
||||
else:
|
||||
print(f" [colors] WARNING: No color data for '{pt}' - using defaults")
|
||||
new_row = derive_row(pt, "#2563EB", "#3B82F6", "#059669", "#F8FAFC", "Auto-generated default")
|
||||
d = dict(zip(headers, [str(i)] + new_row))
|
||||
final_rows.append(d)
|
||||
added += 1
|
||||
|
||||
# Write
|
||||
with open(src, "w", newline="", encoding="utf-8") as f:
|
||||
writer = csv.DictWriter(f, fieldnames=headers)
|
||||
writer.writeheader()
|
||||
writer.writerows(final_rows)
|
||||
|
||||
product_count = len(products)
|
||||
print(f"\n ✅ colors.csv: {len(final_rows)} rows ({product_count} products)")
|
||||
print(f" Added: {added} new color rows")
|
||||
|
||||
# ─── 2. REBUILD ui-reasoning.csv ─────────────────────────────────────────────
|
||||
def derive_ui_reasoning(prod):
|
||||
"""Generate ui-reasoning row from products.csv row."""
|
||||
pt = prod["Product Type"]
|
||||
style = prod.get("Primary Style Recommendation", "")
|
||||
landing = prod.get("Landing Page Pattern", "")
|
||||
color_focus = prod.get("Color Palette Focus", "")
|
||||
considerations = prod.get("Key Considerations", "")
|
||||
keywords = prod.get("Keywords", "")
|
||||
|
||||
# Typography mood derived from style
|
||||
typo_map = {
|
||||
"Minimalism": "Professional + Clean hierarchy",
|
||||
"Glassmorphism": "Modern + Clear hierarchy",
|
||||
"Brutalism": "Bold + Oversized + Monospace",
|
||||
"Claymorphism": "Playful + Rounded + Friendly",
|
||||
"Dark Mode": "High contrast + Light on dark",
|
||||
"Neumorphism": "Subtle + Soft + Monochromatic",
|
||||
"Flat Design": "Bold + Clean + Sans-serif",
|
||||
"Vibrant": "Energetic + Bold + Large",
|
||||
"Aurora": "Elegant + Gradient-friendly",
|
||||
"AI-Native": "Conversational + Minimal chrome",
|
||||
"Organic": "Warm + Humanist + Natural",
|
||||
"Motion": "Dynamic + Hierarchy-shifting",
|
||||
"Accessible": "Large + High contrast + Clear",
|
||||
"Soft UI": "Modern + Accessible + Balanced",
|
||||
"Trust": "Professional + Serif accents",
|
||||
"Swiss": "Grid-based + Mathematical + Helvetica",
|
||||
"3D": "Immersive + Spatial + Variable",
|
||||
"Retro": "Nostalgic + Monospace + Neon",
|
||||
"Cyberpunk": "Terminal + Monospace + Neon",
|
||||
"Pixel": "Retro + Blocky + 8-bit",
|
||||
}
|
||||
typo_mood = "Professional + Clear hierarchy"
|
||||
for key, val in typo_map.items():
|
||||
if key.lower() in style.lower():
|
||||
typo_mood = val
|
||||
break
|
||||
|
||||
# Key effects from style
|
||||
eff_map = {
|
||||
"Glassmorphism": "Backdrop blur (10-20px) + Translucent overlays",
|
||||
"Neumorphism": "Dual shadows (light+dark) + Soft press 150ms",
|
||||
"Claymorphism": "Multi-layer shadows + Spring bounce + Soft press 200ms",
|
||||
"Brutalism": "No transitions + Hard borders + Instant feedback",
|
||||
"Dark Mode": "Subtle glow + Neon accents + High contrast",
|
||||
"Flat Design": "Color shift hover + Fast 150ms transitions + No shadows",
|
||||
"Minimalism": "Subtle hover 200ms + Smooth transitions + Clean",
|
||||
"Motion-Driven": "Scroll animations + Parallax + Page transitions",
|
||||
"Micro-interactions": "Haptic feedback + Small 50-100ms animations",
|
||||
"Vibrant": "Large section gaps 48px+ + Color shift hover + Scroll-snap",
|
||||
"Aurora": "Flowing gradients 8-12s + Color morphing",
|
||||
"AI-Native": "Typing indicator + Streaming text + Context reveal",
|
||||
"Organic": "Rounded 16-24px + Natural shadows + Flowing SVG",
|
||||
"Soft UI": "Improved shadows + Modern 200-300ms + Focus visible",
|
||||
"3D": "WebGL/Three.js + Parallax 3-5 layers + Physics 300-400ms",
|
||||
"Trust": "Clear focus rings + Badge hover + Metric pulse",
|
||||
"Accessible": "Focus rings 3-4px + ARIA + Reduced motion",
|
||||
}
|
||||
key_effects = "Subtle hover (200ms) + Smooth transitions"
|
||||
for key, val in eff_map.items():
|
||||
if key.lower() in style.lower():
|
||||
key_effects = val
|
||||
break
|
||||
|
||||
# Decision rules
|
||||
rules = {}
|
||||
if "dark" in style.lower() or "oled" in style.lower():
|
||||
rules["if_light_mode_needed"] = "provide-theme-toggle"
|
||||
if "glass" in style.lower():
|
||||
rules["if_low_performance"] = "fallback-to-flat"
|
||||
if "conversion" in landing.lower():
|
||||
rules["if_conversion_focused"] = "add-urgency-colors"
|
||||
if "social" in landing.lower():
|
||||
rules["if_trust_needed"] = "add-testimonials"
|
||||
if "data" in keywords.lower() or "dashboard" in keywords.lower():
|
||||
rules["if_data_heavy"] = "prioritize-data-density"
|
||||
if not rules:
|
||||
rules["if_ux_focused"] = "prioritize-clarity"
|
||||
rules["if_mobile"] = "optimize-touch-targets"
|
||||
|
||||
# Anti-patterns
|
||||
anti_patterns = []
|
||||
if "minimalism" in style.lower() or "minimal" in style.lower():
|
||||
anti_patterns.append("Excessive decoration")
|
||||
if "dark" in style.lower():
|
||||
anti_patterns.append("Pure white backgrounds")
|
||||
if "flat" in style.lower():
|
||||
anti_patterns.append("Complex shadows + 3D effects")
|
||||
if "vibrant" in style.lower():
|
||||
anti_patterns.append("Muted colors + Low energy")
|
||||
if "accessible" in style.lower():
|
||||
anti_patterns.append("Color-only indicators")
|
||||
if not anti_patterns:
|
||||
anti_patterns = ["Inconsistent styling", "Poor contrast ratios"]
|
||||
anti_str = " + ".join(anti_patterns[:2])
|
||||
|
||||
return {
|
||||
"UI_Category": pt,
|
||||
"Recommended_Pattern": landing,
|
||||
"Style_Priority": style,
|
||||
"Color_Mood": color_focus,
|
||||
"Typography_Mood": typo_mood,
|
||||
"Key_Effects": key_effects,
|
||||
"Decision_Rules": json.dumps(rules),
|
||||
"Anti_Patterns": anti_str,
|
||||
"Severity": "HIGH"
|
||||
}
|
||||
|
||||
|
||||
def rebuild_ui_reasoning():
|
||||
src = os.path.join(BASE, "ui-reasoning.csv")
|
||||
with open(src, newline="", encoding="utf-8") as f:
|
||||
reader = csv.DictReader(f)
|
||||
headers = reader.fieldnames
|
||||
existing = list(reader)
|
||||
|
||||
# Build lookup
|
||||
ui_map = {}
|
||||
for row in existing:
|
||||
cat = row.get("UI_Category", "").strip()
|
||||
if not cat:
|
||||
continue
|
||||
if cat in REMOVE_TYPES:
|
||||
print(f" [ui-reason] REMOVE: {cat}")
|
||||
continue
|
||||
if cat in UI_RENAMES:
|
||||
new_name = UI_RENAMES[cat]
|
||||
print(f" [ui-reason] RENAME: {cat} → {new_name}")
|
||||
row["UI_Category"] = new_name
|
||||
cat = new_name
|
||||
ui_map[cat] = row
|
||||
|
||||
with open(os.path.join(BASE, "products.csv"), newline="", encoding="utf-8") as f:
|
||||
products = list(csv.DictReader(f))
|
||||
|
||||
final_rows = []
|
||||
added = 0
|
||||
for i, prod in enumerate(products, 1):
|
||||
pt = prod["Product Type"]
|
||||
if pt in ui_map:
|
||||
row = ui_map[pt]
|
||||
row["No"] = str(i)
|
||||
final_rows.append(row)
|
||||
else:
|
||||
row = derive_ui_reasoning(prod)
|
||||
row["No"] = str(i)
|
||||
final_rows.append(row)
|
||||
added += 1
|
||||
|
||||
with open(src, "w", newline="", encoding="utf-8") as f:
|
||||
writer = csv.DictWriter(f, fieldnames=headers)
|
||||
writer.writeheader()
|
||||
writer.writerows(final_rows)
|
||||
|
||||
print(f"\n ✅ ui-reasoning.csv: {len(final_rows)} rows")
|
||||
print(f" Added: {added} new reasoning rows")
|
||||
|
||||
|
||||
# ─── MAIN ────────────────────────────────────────────────────────────────────
|
||||
if __name__ == "__main__":
|
||||
print("=== Rebuilding colors.csv ===")
|
||||
rebuild_colors()
|
||||
print("\n=== Rebuilding ui-reasoning.csv ===")
|
||||
rebuild_ui_reasoning()
|
||||
print("\n🎉 Done!")
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
|
||||
1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"<Pressable accessibilityLabel=""Close""><XIcon /></Pressable>","<Pressable><XIcon /></Pressable>",Critical
|
||||
2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"<View><Text>Email</Text><TextInput accessibilityLabel=""Email address"" /></View>","<TextInput placeholder=""Email"" /></View>",Critical
|
||||
3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"<Pressable accessibilityRole=""button"">Submit</Pressable>","<View onTouchStart={submit}>Submit</View>",High
|
||||
4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"<Text accessibilityLiveRegion=""polite"">{status}</Text>","<Text>{status}</Text>",Medium
|
||||
5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"<Icon accessible={false} importantForAccessibility=""no"" />","<Icon />",Medium
|
||||
6,Touch,Touch Target Size,touch 44x44 hitSlop,iOS/Android/React Native,Primary touch targets must be at least 44x44pt,Increase hitSlop or padding to meet minimum,Small icons with tiny touch area,"<Pressable hitSlop={10}><Icon /></Pressable>","<Pressable><Icon style={{ width: 16, height: 16 }} /></Pressable>",Critical
|
||||
7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,"<View style={{ gap: 8 }}><Button ... /><Button ... /></View>","<View><Button ... /><Button ... /></View>",Medium
|
||||
8,Touch,Gesture Conflicts,scroll swipe back gesture,iOS/Android/React Native,Custom gestures must not break system scroll/back,Reserve horizontal swipes for carousels,Full-screen custom swipe conflicting with back,"HorizontalPager inside vertical ScrollView","PanResponder on full screen blocking back",High
|
||||
9,Navigation,Back Behavior,back handler navigation stack,iOS/Android/React Native,Back navigation should be predictable and preserve state,Use navigation.goBack and keep screen state,Reset stack or exit app unexpectedly,onPress={() => navigation.goBack()},"BackHandler.exitApp() on first press",Critical
|
||||
10,Navigation,Bottom Tabs,tab bar max items,iOS/Android/React Native,Bottom tab bar should have at most 5 primary items,Use 3–5 tabs and move extras to More/Settings,Overloaded tab bar with many icons,Home/Explore/Profile/Settings,"Home/Explore/Shop/Cart/Profile/Settings/More",Medium
|
||||
11,Navigation,Modal Escape,modal dismiss close affordance,iOS/Android/React Native,Modals/sheets must have clear close actions,Provide close button and swipe-down where platform expects,Trapping users in modal with no obvious exit,"<Modal><Button title=""Close"" onPress={onClose} /></Modal>","<Modal><View>{children}</View></Modal>",High
|
||||
12,State,Preserve Screen State,navigation preserve state,iOS/Android/React Native,Returning to a screen should restore its scroll and form state,Keep components mounted or persist state,Reset list scroll and form inputs on every visit,"<Tab.Navigator screenOptions={{ unmountOnBlur: false }}>","<Tab.Screen options={{ unmountOnBlur: true }} />",Medium
|
||||
13,Feedback,Loading Indicators,activity indicator skeleton,iOS/Android/React Native,Show visible feedback during network operations,Use ActivityIndicator or skeleton for >300ms operations,Leave button and screen frozen,"{loading ? <ActivityIndicator /> : <Button title=""Save"" />}", "<Button title=""Save"" onPress={submit} /> // no loading",High
|
||||
14,Feedback,Success Feedback,toast checkmark banner,iOS/Android/React Native,Confirm successful actions with brief feedback,Show toast/checkmark or banner,Complete actions silently with no confirmation,"showToast('Saved successfully')","// silently update state only",Medium
|
||||
15,Feedback,Error Feedback,inline error banner,iOS/Android/React Native,Show clear error messages near the problem,input-level error + summary banner,Only change border color with no explanation,"<TextInput ... /><Text style={{color:'red'}}>{error}</Text>","<TextInput style={{borderColor:'red'}} />",High
|
||||
16,Forms,Inline Validation,onBlur validation,iOS/Android/React Native,Validate inputs on blur or submit with clear messaging,Validate onBlur and onSubmit,Validate on every keystroke causing jank,"onBlur={() => validateEmail(value)}","onChangeText={v => validateEmail(v)} // every char",Medium
|
||||
17,Forms,Keyboard Type,keyboardType returnKeyType,iOS/Android/React Native,Use appropriate keyboardType and returnKeyType,Match email/tel/number/search types,Use default keyboard for all inputs,"<TextInput keyboardType=""email-address"" />","<TextInput keyboardType=""default"" />",Medium
|
||||
18,Forms,Auto Focus & Next,autoFocus blurOnSubmit onSubmitEditing,iOS/Android/React Native,Guide users through form fields with Next/Done flows,Use onSubmitEditing to focus next input,Force users to tap each field manually,"onSubmitEditing={() => nextRef.current?.focus()}","// no onSubmitEditing, manual tap only",Low
|
||||
19,Forms,Password Visibility,secureTextEntry toggle,iOS/Android/React Native,Allow toggling password visibility securely,Provide Show/Hide icon toggling secureTextEntry,Force users to type blind with no option,"<TextInput secureTextEntry={secure} /><Icon onPress={toggle} />","<TextInput secureTextEntry /> // no toggle",Medium
|
||||
20,Performance,Virtualize Long Lists,FlatList SectionList virtualization,iOS/Android/React Native,Use FlatList/SectionList for lists over ~50 items,Use keyExtractor and initialNumToRender appropriately,Render hundreds of items with ScrollView,"<FlatList data={items} renderItem={...} />","<ScrollView>{items.map(renderItem)}</ScrollView>",High
|
||||
21,Performance,Image Size & Cache,Image resize cache,iOS/Android/React Native,Use correctly sized and cached images,Use Image component with proper resizeMode and caching,Load full-resolution images everywhere,"<Image source={{uri}} resizeMode=""cover"" />","<Image source={require('4k.png')} /> // small avatar",Medium
|
||||
22,Performance,Debounce High-Freq Events,debounce scroll search,iOS/Android/React Native,Debounce scroll/search callbacks to avoid jank,Wrap handlers with debounce/throttle,Run heavy logic on every event,"onScroll={debouncedHandleScroll}","onScroll={handleScrollHeavy}",Medium
|
||||
23,Animation,Duration & Easing,animation duration easing,iOS/Android/React Native,Micro-interactions should be 150–300ms with native-like easing,Use ease-out for enter/ease-in for exit,Use long or linear animations for core UI,"Animated.timing(..., { duration: 200, easing: Easing.out(Easing.quad) })","Animated.timing(..., { duration: 800, easing: Easing.linear })",Medium
|
||||
24,Animation,Respect Reduced Motion,reduced motion accessibility,iOS/Android/React Native,Respect OS reduced-motion accessibility setting,Check reduceMotionEnabled and simplify animations,Ignore user motion preferences,"if (reduceMotionEnabled) skipAnimation()","Always run complex parallax animations",Critical
|
||||
25,Animation,Limited Continuous Motion,loop animation loader,iOS/Android/React Native,Reserve infinite animations for loaders and live data,Use looping only where necessary,Keep decorative elements looping forever,"Animated.loop(loaderAnim) for ActivityIndicator","Animated.loop(bounceAnim) on background icons",Medium
|
||||
26,Typography,Base Font Size,fontScale dynamic type,iOS/Android/React Native,Body text must be readable and support Dynamic Type,Use platform fontScale and at least 14–16pt base,Render critical text below 12pt,"<Text style={{ fontSize: 16 }}>Body</Text>","<Text style={{ fontSize: 10 }}>Body</Text>",High
|
||||
27,Typography,Dynamic Type Support,allowFontScaling adjustsFontSizeToFit,iOS/Android/React Native,Support system text scaling without breaking layout,Set allowFontScaling and test large text,Disable scaling on all text globally,"<Text allowFontScaling>{label}</Text>","<Text allowFontScaling={false}>{label}</Text>",High
|
||||
28,Safe Areas,Safe Area Insets,safe area insets notch gesture,iOS/Android/React Native,Content must not overlap notches/gesture bars,Wrap screens in SafeAreaView or apply insets,Place tappable content under system bars,"<SafeAreaView style={{ flex: 1 }}><Screen /></SafeAreaView>","<View style={{ flex: 1 }}><Screen /></View>",High
|
||||
29,Theming,Light/Dark Contrast,dark mode contrast tokens,iOS/Android/React Native,Ensure sufficient contrast in both light and dark themes,Use semantic tokens and test both themes,Reuse light-theme grays directly in dark mode,"colors.textPrimaryDark = '#F9FAFB'","colors.textPrimaryDark = '#9CA3AF' on '#111827'",High
|
||||
30,Anti-Pattern,No Gesture-Only Actions,gesture only hidden controls,iOS/Android/React Native,Don't rely solely on hidden gestures for core actions,Provide visible buttons in addition to gestures,Rely on swipe/shake only with no UI affordance,"Swipe to delete + visible Delete button","Only shake device to undo with no UI",Critical
|
||||
|
|
|
@ -1,26 +0,0 @@
|
|||
No,Data Type,Keywords,Best Chart Type,Secondary Options,When to Use,When NOT to Use,Data Volume Threshold,Color Guidance,Accessibility Grade,Accessibility Notes,A11y Fallback,Library Recommendation,Interactive Level
|
||||
1,Trend Over Time,"trend, time-series, line, growth, timeline, progress",Line Chart,"Area Chart, Smooth Area","Data has a time axis; user needs to observe rise/fall trends or rate of change over a continuous period","Fewer than 4 data points (use stat card); more than 6 series (visual noise); no time dimension exists","<1000 pts: SVG; ≥1000 pts: Canvas + downsampling; >10000: aggregate to intervals","Primary: #0080FF. Multiple series: distinct colors + distinct line styles. Fill: 20% opacity",AA,"Differentiate series by line style (solid/dashed/dotted) not color alone. Add pattern overlays for colorblind users.","Dashed/dotted lines per series; togglable data table with timestamps and values","Chart.js, Recharts, ApexCharts",Hover + Zoom
|
||||
2,Compare Categories,"compare, categories, bar, comparison, ranking",Bar Chart (Horizontal or Vertical),"Column Chart, Grouped Bar","Comparing discrete categories by magnitude; ranking or ordering is the core insight; categories ≤ 15","Categories > 15 (use table or search); data has time dimension (use line); showing proportions (use waffle/stacked)","<20 categories: vertical bar; 20–50: horizontal bar; >50: paginated table","Each bar: distinct color. Grouped: same hue family. Always sort descending by value",AAA,"Value labels on each bar by default. Sort control for user reordering.","Value labels always visible; provide CSV export","Chart.js, Recharts, D3.js",Hover + Sort
|
||||
3,Part-to-Whole,"part-to-whole, pie, donut, percentage, proportion, share",Pie Chart or Donut,"Stacked Bar, Waffle Chart","≤5 categories; one dominant segment vs rest; emphasis on visual proportion over exact values","Categories > 5; slice differences < 5% (visually indistinguishable); user needs precise values; accessibility-first context","Max 6 slices; beyond that switch to stacked bar 100%","5–6 max colors. Contrasting palette. Largest slice at 12 o'clock. Always label slices with %",C,"Pie charts fail WCAG for colorblind users. Slices rely on color alone. Avoid as primary chart in a11y contexts.","Must provide stacked bar alternative + percentage data table as mandatory fallback","Chart.js, Recharts, D3.js",Hover + Drill
|
||||
4,Correlation / Distribution,"correlation, distribution, scatter, relationship, pattern, cluster",Scatter Plot or Bubble Chart,"Heat Map, Matrix","Exploring relationship between two continuous variables; identifying clusters or outliers in a dataset","Variables are categorical (use grouped bar); fewer than 20 points (patterns aren't meaningful); mobile-primary context","<500 pts: SVG; 500–5000: Canvas at 0.6–0.8 opacity; >5000: hexbin or aggregate first","Color axis: gradient (blue → red). Bubble size: relative to 3rd variable. Opacity: 0.6–0.8 to show density",B,"Provide data table alternative. Combine color + shape distinction for colorblind users.","Data table with correlation coefficient annotation; shape markers (circle/square/triangle) per group","D3.js, Plotly, Recharts",Hover + Brush
|
||||
5,Heatmap / Intensity,"heatmap, heat-map, intensity, density, matrix, calendar",Heat Map or Choropleth,"Grid Heat Map, Bubble Heat","Showing intensity/density across a 2D grid; time-based patterns (e.g., activity by hour × day)","Fewer than 20 cells (use bar); user needs to read exact values; colorblind users without pattern fallback","Up to 10,000 cells efficiently; beyond that aggregate; calendar heatmap: 365 cells max per SVG","Gradient: Cool (blue) to Hot (red). Divergent scale for ±data. Always include numeric color legend",B,"Pattern overlay for colorblind users. Numerical value on hover. Legend must include scale ticks.","Numerical overlay on hover; downloadable grid table with row/column labels","D3.js, Plotly, ApexCharts",Hover + Zoom
|
||||
6,Geographic Data,"geographic, map, location, region, geo, spatial, choropleth",Choropleth Map or Bubble Map,Geographic Heat Map,"Data has a regional/location dimension; spatial distribution is the core insight for the user","Regions have very different sizes making visual comparison misleading (use bar); mobile-primary context","<1000 regions: SVG; ≥1000: Canvas/WebGL (Deck.gl); global maps: tile-based rendering","Single color gradient per region group. Categorized colors for discrete types. Legend with clear scale breaks",B,"Include text labels for major regions. Provide keyboard navigation between regions.","Region text labels; sortable data table by region name and value; keyboard-navigable regions","D3.js, Mapbox, Leaflet",Pan + Zoom + Drill
|
||||
7,Funnel / Flow,"funnel, flow, conversion, drop-off, pipeline, stages",Funnel Chart or Sankey,Waterfall (for flows),"Sequential multi-stage process; showing conversion or drop-off rates between defined stages","Stages aren't sequential; values don't decrease monotonically (use bar); fewer than 3 stages","3–8 stages optimal; beyond 8 stages group minor steps into 'Other'","Stages: single color gradient (start → end). Show conversion % between each stage. Highlight biggest drop",AA,"Explicit conversion % as text per stage. Stage labels always visible. Linear list view as fallback.","Provide linear list view with stage name + count + drop-off %; keyboard traversal","D3.js, Recharts, Custom SVG",Hover + Drill
|
||||
8,Performance vs Target,"performance, target, kpi, gauge, goal, threshold, progress",Gauge Chart or Bullet Chart,"Dial, Thermometer","Single KPI measured against a defined target or threshold; dashboard summary context","No target or benchmark exists; comparing multiple KPIs at once (use bullet chart grid)","Single metric per gauge; for 3+ KPIs use bullet chart grid layout","Performance: Red → Yellow → Green gradient. Target: marker line. Threshold zones clearly differentiated",AA,"Always show numerical value + % of target as text beside chart. Never rely on color position alone.","Numerical value + % of target shown as visible text; ARIA live region for real-time updates","D3.js, ApexCharts, Custom SVG",Hover
|
||||
9,Time-Series Forecast,"forecast, prediction, confidence, band, projection, estimate",Line with Confidence Band,Ribbon Chart,"Historical data + model predictions; communicating uncertainty range to non-technical stakeholders","No historical baseline; prediction confidence is too low to be useful; audience is not data-literate","Keep historical window to 30–90 days for readability; forecast horizon ≤ 30% of visible x-axis range","Actual: solid line #0080FF. Forecast: dashed #FF9500. Confidence band: 15% opacity fill same hue",AA,"Toggle between actual-only and forecast views. Legend must distinguish lines beyond color (solid vs dashed).","Toggle actual/forecast independently; legend labels must include line-style description","Chart.js, ApexCharts, Plotly",Hover + Toggle
|
||||
10,Anomaly Detection,"anomaly, outlier, spike, alert, detection, monitoring, deviation",Line Chart with Highlights,Scatter with Alert,"Monitoring a time-series for outliers; alerting users to unexpected spikes or dips in operational data","Anomalies are predefined categories (use bar with highlight); real-time context without a pause control","Stream at ≤60fps with Canvas; batch: up to 10,000 pts; mark anomalies as a separate data layer","Normal: #0080FF solid line. Anomaly marker: #FF0000 circle + filled. Alert band: #FFF3CD background zone",AA,"Use shape marker (not color only) for anomaly points. Add text annotation per anomaly event.","Text alert annotation per anomaly; anomaly summary list panel alongside chart","D3.js, Plotly, ApexCharts",Hover + Alert
|
||||
11,Hierarchical / Nested Data,"hierarchy, nested, treemap, parent, children, breakdown, drill",Treemap,"Sunburst, Nested Donut, Icicle","Showing size relationships within a hierarchy; overview of proportional structure (e.g., budget breakdown)","Hierarchy depth > 3 levels (too complex to read); user needs to compare sibling values precisely","<200 nodes: SVG; 200–1000: Canvas; >1000: paginate or pre-filter before rendering","Parent nodes: distinct hues. Children: lighter shades of same hue. White separator borders: 2–3px",C,"Poor baseline accessibility. Always provide table alternative as primary view. Label all large areas.","Collapsible tree table as primary view; treemap as supplementary visual only","D3.js, Recharts, ApexCharts",Hover + Drilldown
|
||||
12,Flow / Process Data,"flow, process, sankey, distribution, source, target, transfer",Sankey Diagram,"Alluvial, Chord Diagram","Showing how quantities flow between nodes; multi-source multi-target distribution","Flow directions form loops (use network graph); fewer than 3 source-target pairs; mobile-primary context","<50 flows: SVG; ≥50: Canvas; >200 flows: aggregate minor flows into 'Other' node","Gradient from source to target color. Flow opacity: 0.4–0.6. Node labels always visible",C,"Structural flow charts cannot be conveyed by color alone. Provide flow table. Avoid on mobile.","Flow table (Source → Target → Value); keyboard-traversable node list with tab stops","D3.js (d3-sankey), Plotly",Hover + Drilldown
|
||||
13,Cumulative Changes,"waterfall, cumulative, variance, incremental, bridge, delta",Waterfall Chart,"Stacked Bar, Cascade","Showing how individual positive/negative components add up to a final total (e.g., P&L, budget variance)","Changes are not additive; more than 12 bars (readability breaks); audience expects a simple total","4–12 bars optimal; beyond 12 aggregate minor items into a single 'Other' bar","Increases: #4CAF50. Decreases: #F44336. Start total: #2196F3. End total: #0D47A1. Running total line: dashed",AA,"Color + directional arrow icon per bar (not color alone). Labels on every bar.","Table with running total column; directional arrow icons per row","ApexCharts, Highcharts, Plotly",Hover
|
||||
14,Multi-Variable Comparison,"radar, spider, multi-variable, attributes, dimensions, comparison",Radar / Spider Chart,"Parallel Coordinates, Grouped Bar","Comparing multiple entities across the same fixed set of attributes (e.g., product feature comparison)","Axes > 8 (unreadable); values need precise comparison (use grouped bar); audience unfamiliar with radar charts","2–3 datasets maximum per chart; 5–8 axes; beyond 8 axes switch to parallel coordinates","Single dataset: #0080FF at 20% fill. Multiple: distinct hues with 30% fill. Border: full opacity",B,"Limit axes to 5–8. Always provide grouped bar chart alternative for precise reading.","Grouped bar chart as mandatory alternative; include raw data table","Chart.js, Recharts, ApexCharts",Hover + Toggle
|
||||
15,Stock / Trading OHLC,"stock, trading, ohlc, candlestick, finance, price, volume",Candlestick Chart,"OHLC Bar, Heikin-Ashi","Financial time-series with Open/High/Low/Close data; trading or investment product context only","Non-financial audience; no OHLC data available (use line chart); accessibility-first context","Real-time: Canvas required. Historical: paginate by time range. Max 500 candles visible at once","Bullish: #26A69A. Bearish: #EF5350. Volume bars: 40% opacity below. Body fill vs hollow for OHLC style",B,"Provide OHLC data table. Colorblind: use fill vs outline pattern (bullish = filled, bearish = hollow).","OHLC data table with sortable columns; numeric summary panel (daily change %)","Lightweight Charts (TradingView), ApexCharts",Real-time + Hover + Zoom
|
||||
16,Relationship / Connection Data,"network, graph, nodes, edges, connections, relationships, force",Network Graph,"Hierarchical Tree, Adjacency Matrix","Mapping connections between entities; network topology or social graph exploration context","Node count > 500 without clustering pre-applied; user needs precise connection counts; mobile context","≤100 nodes: SVG; 101–500: Canvas; >500: must apply clustering/LOD before rendering","Node types: categorical colors. Edges: #90A4AE at 60% opacity. Highlight path: #F59E0B",D,"Fundamentally inaccessible without alternative. Never use as sole representation. Always provide list alternative.","Adjacency list table (Node A → Node B → Weight); hierarchical tree view when structure allows","D3.js (d3-force), Vis.js, Cytoscape.js",Drilldown + Hover + Drag
|
||||
17,Distribution / Statistical,"distribution, statistical, spread, median, outlier, quartile, boxplot",Box Plot,"Violin Plot, Beeswarm","Showing spread, median, and outliers of a dataset; comparing distributions across multiple groups","Fewer than 20 data points per group (distribution is not meaningful); audience unfamiliar with statistical charts","Any sample size; aggregated representation so rendering is ⚡ Excellent at any volume","Box fill: #BBDEFB. Border: #1976D2. Median line: #D32F2F bold. Outlier dots: #F44336",AA,"Include stats summary table. Annotate outlier count in chart subtitle.","Stats summary table (min / Q1 / median / Q3 / max / mean); outlier count annotation","Plotly, D3.js, Chart.js (plugin)",Hover
|
||||
18,Performance vs Target (Compact),"bullet, compact, kpi, dashboard, target, benchmark, range",Bullet Chart,"Gauge, Progress Bar","Dashboard with multiple KPIs side by side; space-constrained contexts where a gauge is too large","Single KPI with emphasis (use gauge); data has no defined target range; fewer than 3 KPIs","Ideal for 3–10 bullet charts in a grid; scales to any count efficiently","Qualitative ranges: #FFCDD2 / #FFF9C4 / #C8E6C9 (bad/ok/good). Performance bar: #1976D2. Target: black 3px marker",AAA,"All values always visible as text. Color ranges are labeled with text thresholds not color alone.","Numerical values always visible (not hover-only); color ranges labeled with threshold text","D3.js, Plotly, Custom SVG",Hover
|
||||
19,Proportional / Percentage,"waffle, percentage, proportion, progress, filled, grid",Waffle Chart,"Pictogram, Stacked Bar 100%","Showing what fraction of a whole is filled; percentage progress in a visually engaging and accessible format","More than 5 categories (use stacked bar); exact values matter over visual proportion; very tight space","10×10 grid standard (100 cells); for > 5 categories switch to stacked 100% bar","3–5 categories max. 2–3px gap between cells. Each category a distinct accessible color pair",AA,"Better than pie for accessibility. Percentage text label always visible. Each cell has aria-label.","Percentage text always visible; grid cells labeled with aria-label value; provide legend","D3.js, React-Waffle, Custom CSS Grid",Hover
|
||||
20,Hierarchical Proportional,"sunburst, hierarchy, nested, proportion, radial, circle",Sunburst Chart,"Treemap, Icicle, Circle Packing","Exploring nested proportions where both hierarchy and relative size matter (e.g., org spend breakdown)","More than 3 hierarchy levels (outer rings become unreadable); precision matters over overview; mobile","<100 nodes: SVG; 100–500: Canvas; >500: filter to top N before rendering","Center to outer: darker to lighter hue. Each level 15–20% lighter. Contrasting border between sectors",C,"Poor accessibility beyond 2 levels. Mandatory table alternative required for any production use.","Collapsible indented list with percentages; breadcrumb trail for current drill-down state","D3.js (d3-hierarchy), Recharts, ApexCharts",Drilldown + Hover
|
||||
21,Root Cause Analysis,"root cause, decomposition, tree, hierarchy, drill-down, ai-split, attribution",Decomposition Tree,"Decision Tree, Flow Chart","Decomposing a metric into contributing factors; AI-assisted analysis or BI drill-down scenarios","No clear parent-child causal relationship; audience expects a summary rather than exploration","Up to 5 levels deep; limit visible nodes to 20 per level for readability; lazy-load deeper levels","Positive impact nodes: #2563EB. Negative impact nodes: #EF4444. Neutral connectors: #94A3B8",AA,"Keyboard-navigable expand/collapse. Screen reader announces node value and % contribution.","Keyboard expand/collapse tree; screen reader announces node label + value + % impact","Power BI (native), React-Flow, Custom D3.js",Drill + Expand
|
||||
22,3D Spatial Data,"3d, spatial, immersive, terrain, molecular, volumetric, point-cloud",3D Scatter / Surface Plot,"Volumetric Rendering, Point Cloud","Scientific/engineering context where Z-axis carries essential info not expressible in 2D","2D projection conveys the same insight; mobile context; accessibility-required environments; standard business dashboards","WebGL required. Deck.gl: up to 1M points. Three.js: LOD required beyond 50,000 pts","Depth cues: lighting and shading. Z-axis: color gradient (cool → warm). Transparent overlapping: opacity 0.4",D,"3D spatial charts are fundamentally inaccessible. Must not be used as primary chart type in any product UI.","Mandatory 2D projection view + data table; do not use as primary chart type in product UI","Three.js, Deck.gl, Plotly 3D",Rotate + Zoom + VR
|
||||
23,Real-Time Streaming,"streaming, real-time, ticker, live, velocity, pulse, monitoring",Streaming Area Chart,"Ticker Tape, Moving Gauge","Live monitoring dashboards; IoT/ops data updating at ≥1 Hz; user needs current value at a glance","Update frequency < 1/min (use periodic-refresh line chart); flashing content without reduced-motion support","Canvas/WebGL required. Buffer last 60–300s of data. Downsample older data on scroll","Current pulse: #00FF00 (dark theme) or #0080FF (light theme). History: fading opacity. Grid: dark background",B,"Pause/resume control required. Current value as large visible text KPI. Respect prefers-reduced-motion.","Pause/resume button required; current value shown as large text KPI; prefers-reduced-motion: freeze animation","Smoothed D3.js, CanvasJS",Real-time + Pause + Zoom
|
||||
24,Sentiment / Emotion,"sentiment, emotion, nlp, opinion, feeling, text-analysis",Word Cloud with Sentiment,"Sentiment Arc, Radar Chart","NLP output visualization; exploratory analysis of text corpus sentiment; frequency-weighted keyword overview","Precise values matter (word size is inherently imprecise); screen-reader context; corpus < 50 items","50–5000 terms optimal. Beyond 5000: apply top-N filtering before render. Avoid on mobile","Positive: #22C55E. Negative: #EF4444. Neutral: #94A3B8. Word size maps to frequency",C,"Word clouds fail screen readers. Never use as sole output of NLP analysis. Always pair with list view.","Sortable list view by frequency with sentiment label column; word cloud as supplementary only","D3-cloud, Highcharts, Nivo",Hover + Filter
|
||||
25,Process Mining,"process, mining, variants, path, bottleneck, log, event",Process Map / Graph,"Directed Acyclic Graph (DAG), Petri Net","Analyzing event logs to visualize actual process flows; identifying bottlenecks and deviations in ops/product funnels","No event log data available; audience expects a static flowchart (use diagram tool); node count > 100 without pre-filtering","<30 nodes: SVG; 30–100: Canvas; >100: apply variant filtering (top 80% of cases) before rendering","Happy path: #10B981 thick line. Deviations: #F59E0B thin line. Bottleneck nodes: #EF4444 fill",B,"Complex graphs are hard to navigate. Provide path summary text. Highlight top 3 bottlenecks as annotations.","Path summary table (variant → frequency → avg duration); top 3 bottlenecks as text annotation panel","React-Flow, Cytoscape.js, Recharts",Drag + Node-Click
|
||||
|
|
|
@ -1,162 +0,0 @@
|
|||
No,Product Type,Primary,On Primary,Secondary,On Secondary,Accent,On Accent,Background,Foreground,Card,Card Foreground,Muted,Muted Foreground,Border,Destructive,On Destructive,Ring,Notes
|
||||
1,SaaS (General),#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#EA580C,#FFFFFF,#F8FAFC,#1E293B,#FFFFFF,#1E293B,#E9EFF8,#64748B,#E2E8F0,#DC2626,#FFFFFF,#2563EB,Trust blue + orange CTA contrast [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
2,Micro SaaS,#6366F1,#FFFFFF,#818CF8,#0F172A,#059669,#FFFFFF,#F5F3FF,#1E1B4B,#FFFFFF,#1E1B4B,#EBEFF9,#64748B,#E0E7FF,#DC2626,#FFFFFF,#6366F1,Indigo primary + emerald CTA [Accent adjusted from #10B981 for WCAG 3:1]
|
||||
3,E-commerce,#059669,#FFFFFF,#10B981,#0F172A,#EA580C,#FFFFFF,#ECFDF5,#064E3B,#FFFFFF,#064E3B,#E8F1F3,#64748B,#A7F3D0,#DC2626,#FFFFFF,#059669,Success green + urgency orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
4,E-commerce Luxury,#1C1917,#FFFFFF,#44403C,#FFFFFF,#A16207,#FFFFFF,#FAFAF9,#0C0A09,#FFFFFF,#0C0A09,#E8ECF0,#64748B,#D6D3D1,#DC2626,#FFFFFF,#1C1917,Premium dark + gold accent [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
5,B2B Service,#0F172A,#FFFFFF,#334155,#FFFFFF,#0369A1,#FFFFFF,#F8FAFC,#020617,#FFFFFF,#020617,#E8ECF1,#64748B,#E2E8F0,#DC2626,#FFFFFF,#0F172A,Professional navy + blue CTA
|
||||
6,Financial Dashboard,#0F172A,#FFFFFF,#1E293B,#FFFFFF,#22C55E,#0F172A,#020617,#F8FAFC,#0E1223,#F8FAFC,#1A1E2F,#94A3B8,#334155,#EF4444,#FFFFFF,#0F172A,Dark bg + green positive indicators
|
||||
7,Analytics Dashboard,#1E40AF,#FFFFFF,#3B82F6,#FFFFFF,#D97706,#FFFFFF,#F8FAFC,#1E3A8A,#FFFFFF,#1E3A8A,#E9EEF6,#64748B,#DBEAFE,#DC2626,#FFFFFF,#1E40AF,Blue data + amber highlights [Accent adjusted from #F59E0B for WCAG 3:1]
|
||||
8,Healthcare App,#0891B2,#FFFFFF,#22D3EE,#0F172A,#059669,#FFFFFF,#ECFEFF,#164E63,#FFFFFF,#164E63,#E8F1F6,#64748B,#A5F3FC,#DC2626,#FFFFFF,#0891B2,Calm cyan + health green
|
||||
9,Educational App,#4F46E5,#FFFFFF,#818CF8,#0F172A,#EA580C,#FFFFFF,#EEF2FF,#1E1B4B,#FFFFFF,#1E1B4B,#EBEEF8,#64748B,#C7D2FE,#DC2626,#FFFFFF,#4F46E5,Playful indigo + energetic orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
10,Creative Agency,#EC4899,#FFFFFF,#F472B6,#0F172A,#0891B2,#FFFFFF,#FDF2F8,#831843,#FFFFFF,#831843,#F1EEF5,#64748B,#FBCFE8,#DC2626,#FFFFFF,#EC4899,Bold pink + cyan accent [Accent adjusted from #06B6D4 for WCAG 3:1]
|
||||
11,Portfolio/Personal,#18181B,#FFFFFF,#3F3F46,#FFFFFF,#2563EB,#FFFFFF,#FAFAFA,#09090B,#FFFFFF,#09090B,#E8ECF0,#64748B,#E4E4E7,#DC2626,#FFFFFF,#18181B,Monochrome + blue accent
|
||||
12,Gaming,#7C3AED,#FFFFFF,#A78BFA,#0F172A,#F43F5E,#FFFFFF,#0F0F23,#E2E8F0,#1E1C35,#E2E8F0,#27273B,#94A3B8,#4C1D95,#EF4444,#FFFFFF,#7C3AED,Neon purple + rose action
|
||||
13,Government/Public Service,#0F172A,#FFFFFF,#334155,#FFFFFF,#0369A1,#FFFFFF,#F8FAFC,#020617,#FFFFFF,#020617,#E8ECF1,#64748B,#E2E8F0,#DC2626,#FFFFFF,#0F172A,High contrast navy + blue
|
||||
14,Fintech/Crypto,#F59E0B,#0F172A,#FBBF24,#0F172A,#8B5CF6,#FFFFFF,#0F172A,#F8FAFC,#222735,#F8FAFC,#272F42,#94A3B8,#334155,#EF4444,#FFFFFF,#F59E0B,Gold trust + purple tech
|
||||
15,Social Media App,#E11D48,#FFFFFF,#FB7185,#0F172A,#2563EB,#FFFFFF,#FFF1F2,#881337,#FFFFFF,#881337,#F0ECF2,#64748B,#FECDD3,#DC2626,#FFFFFF,#E11D48,Vibrant rose + engagement blue
|
||||
16,Productivity Tool,#0D9488,#FFFFFF,#14B8A6,#0F172A,#EA580C,#FFFFFF,#F0FDFA,#134E4A,#FFFFFF,#134E4A,#E8F1F4,#64748B,#99F6E4,#DC2626,#FFFFFF,#0D9488,Teal focus + action orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
17,Design System/Component Library,#4F46E5,#FFFFFF,#6366F1,#FFFFFF,#EA580C,#FFFFFF,#EEF2FF,#312E81,#FFFFFF,#312E81,#EBEEF8,#64748B,#C7D2FE,#DC2626,#FFFFFF,#4F46E5,Indigo brand + doc hierarchy [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
18,AI/Chatbot Platform,#7C3AED,#FFFFFF,#A78BFA,#0F172A,#0891B2,#FFFFFF,#FAF5FF,#1E1B4B,#FFFFFF,#1E1B4B,#ECEEF9,#64748B,#DDD6FE,#DC2626,#FFFFFF,#7C3AED,AI purple + cyan interactions [Accent adjusted from #06B6D4 for WCAG 3:1]
|
||||
19,NFT/Web3 Platform,#8B5CF6,#FFFFFF,#A78BFA,#0F172A,#FBBF24,#0F172A,#0F0F23,#F8FAFC,#1E1D35,#F8FAFC,#27273B,#94A3B8,#4C1D95,#EF4444,#FFFFFF,#8B5CF6,Purple tech + gold value
|
||||
20,Creator Economy Platform,#EC4899,#FFFFFF,#F472B6,#0F172A,#EA580C,#FFFFFF,#FDF2F8,#831843,#FFFFFF,#831843,#F1EEF5,#64748B,#FBCFE8,#DC2626,#FFFFFF,#EC4899,Creator pink + engagement orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
21,Remote Work/Collaboration Tool,#6366F1,#FFFFFF,#818CF8,#0F172A,#059669,#FFFFFF,#F5F3FF,#312E81,#FFFFFF,#312E81,#EBEFF9,#64748B,#E0E7FF,#DC2626,#FFFFFF,#6366F1,Calm indigo + success green [Accent adjusted from #10B981 for WCAG 3:1]
|
||||
22,Mental Health App,#8B5CF6,#FFFFFF,#C4B5FD,#0F172A,#059669,#FFFFFF,#FAF5FF,#4C1D95,#FFFFFF,#4C1D95,#EDEFF9,#64748B,#EDE9FE,#DC2626,#FFFFFF,#8B5CF6,Calming lavender + wellness green [Accent adjusted from #10B981 for WCAG 3:1]
|
||||
23,Pet Tech App,#F97316,#0F172A,#FB923C,#0F172A,#2563EB,#FFFFFF,#FFF7ED,#9A3412,#FFFFFF,#9A3412,#F1F0F0,#64748B,#FED7AA,#DC2626,#FFFFFF,#F97316,Playful orange + trust blue
|
||||
24,Smart Home/IoT Dashboard,#1E293B,#FFFFFF,#334155,#FFFFFF,#22C55E,#0F172A,#0F172A,#F8FAFC,#1B2336,#F8FAFC,#272F42,#94A3B8,#475569,#EF4444,#FFFFFF,#1E293B,Dark tech + status green
|
||||
25,EV/Charging Ecosystem,#0891B2,#FFFFFF,#22D3EE,#0F172A,#16A34A,#FFFFFF,#ECFEFF,#164E63,#FFFFFF,#164E63,#E8F1F6,#64748B,#A5F3FC,#DC2626,#FFFFFF,#0891B2,Electric cyan + eco green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
26,Subscription Box Service,#D946EF,#FFFFFF,#E879F9,#0F172A,#EA580C,#FFFFFF,#FDF4FF,#86198F,#FFFFFF,#86198F,#F0EEF9,#64748B,#F5D0FE,#DC2626,#FFFFFF,#D946EF,Excitement purple + urgency orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
27,Podcast Platform,#1E1B4B,#FFFFFF,#312E81,#FFFFFF,#F97316,#0F172A,#0F0F23,#F8FAFC,#1B1B30,#F8FAFC,#27273B,#94A3B8,#4338CA,#EF4444,#FFFFFF,#1E1B4B,Dark audio + warm accent
|
||||
28,Dating App,#E11D48,#FFFFFF,#FB7185,#0F172A,#EA580C,#FFFFFF,#FFF1F2,#881337,#FFFFFF,#881337,#F0ECF2,#64748B,#FECDD3,#DC2626,#FFFFFF,#E11D48,Romantic rose + warm orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
29,Micro-Credentials/Badges Platform,#0369A1,#FFFFFF,#0EA5E9,#0F172A,#A16207,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E7EFF5,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0369A1,Trust blue + achievement gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
30,Knowledge Base/Documentation,#475569,#FFFFFF,#64748B,#FFFFFF,#2563EB,#FFFFFF,#F8FAFC,#1E293B,#FFFFFF,#1E293B,#EAEFF3,#64748B,#E2E8F0,#DC2626,#FFFFFF,#475569,Neutral grey + link blue
|
||||
31,Hyperlocal Services,#059669,#FFFFFF,#10B981,#0F172A,#EA580C,#FFFFFF,#ECFDF5,#064E3B,#FFFFFF,#064E3B,#E8F1F3,#64748B,#A7F3D0,#DC2626,#FFFFFF,#059669,Location green + action orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
32,Beauty/Spa/Wellness Service,#EC4899,#FFFFFF,#F9A8D4,#0F172A,#8B5CF6,#FFFFFF,#FDF2F8,#831843,#FFFFFF,#831843,#F1EEF5,#64748B,#FBCFE8,#DC2626,#FFFFFF,#EC4899,Soft pink + lavender luxury
|
||||
33,Luxury/Premium Brand,#1C1917,#FFFFFF,#44403C,#FFFFFF,#A16207,#FFFFFF,#FAFAF9,#0C0A09,#FFFFFF,#0C0A09,#E8ECF0,#64748B,#D6D3D1,#DC2626,#FFFFFF,#1C1917,Premium black + gold accent [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
34,Restaurant/Food Service,#DC2626,#FFFFFF,#F87171,#0F172A,#A16207,#FFFFFF,#FEF2F2,#450A0A,#FFFFFF,#450A0A,#F0EDF1,#64748B,#FECACA,#DC2626,#FFFFFF,#DC2626,Appetizing red + warm gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
35,Fitness/Gym App,#F97316,#0F172A,#FB923C,#0F172A,#22C55E,#0F172A,#1F2937,#F8FAFC,#313742,#F8FAFC,#37414F,#94A3B8,#374151,#EF4444,#FFFFFF,#F97316,Energy orange + success green
|
||||
36,Real Estate/Property,#0F766E,#FFFFFF,#14B8A6,#0F172A,#0369A1,#FFFFFF,#F0FDFA,#134E4A,#FFFFFF,#134E4A,#E8F0F3,#64748B,#99F6E4,#DC2626,#FFFFFF,#0F766E,Trust teal + professional blue
|
||||
37,Travel/Tourism Agency,#0EA5E9,#0F172A,#38BDF8,#0F172A,#EA580C,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E8F2F8,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0EA5E9,Sky blue + adventure orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
38,Hotel/Hospitality,#1E3A8A,#FFFFFF,#3B82F6,#FFFFFF,#A16207,#FFFFFF,#F8FAFC,#1E40AF,#FFFFFF,#1E40AF,#E9EEF5,#64748B,#BFDBFE,#DC2626,#FFFFFF,#1E3A8A,Luxury navy + gold service [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
39,Wedding/Event Planning,#DB2777,#FFFFFF,#F472B6,#0F172A,#A16207,#FFFFFF,#FDF2F8,#831843,#FFFFFF,#831843,#F0EDF4,#64748B,#FBCFE8,#DC2626,#FFFFFF,#DB2777,Romantic pink + elegant gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
40,Legal Services,#1E3A8A,#FFFFFF,#1E40AF,#FFFFFF,#B45309,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#E9EEF5,#64748B,#CBD5E1,#DC2626,#FFFFFF,#1E3A8A,Authority navy + trust gold
|
||||
41,Insurance Platform,#0369A1,#FFFFFF,#0EA5E9,#0F172A,#16A34A,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E7EFF5,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0369A1,Security blue + protected green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
42,Banking/Traditional Finance,#0F172A,#FFFFFF,#1E3A8A,#FFFFFF,#A16207,#FFFFFF,#F8FAFC,#020617,#FFFFFF,#020617,#E8ECF1,#64748B,#E2E8F0,#DC2626,#FFFFFF,#0F172A,Trust navy + premium gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
43,Online Course/E-learning,#0D9488,#FFFFFF,#2DD4BF,#0F172A,#EA580C,#FFFFFF,#F0FDFA,#134E4A,#FFFFFF,#134E4A,#E8F1F4,#64748B,#5EEAD4,#DC2626,#FFFFFF,#0D9488,Progress teal + achievement orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
44,Non-profit/Charity,#0891B2,#FFFFFF,#22D3EE,#0F172A,#EA580C,#FFFFFF,#ECFEFF,#164E63,#FFFFFF,#164E63,#E8F1F6,#64748B,#A5F3FC,#DC2626,#FFFFFF,#0891B2,Compassion blue + action orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
45,Music Streaming,#1E1B4B,#FFFFFF,#4338CA,#FFFFFF,#22C55E,#0F172A,#0F0F23,#F8FAFC,#1B1B30,#F8FAFC,#27273B,#94A3B8,#312E81,#EF4444,#FFFFFF,#1E1B4B,Dark audio + play green
|
||||
46,Video Streaming/OTT,#0F0F23,#FFFFFF,#1E1B4B,#FFFFFF,#E11D48,#FFFFFF,#000000,#F8FAFC,#0C0C0D,#F8FAFC,#181818,#94A3B8,#312E81,#EF4444,#FFFFFF,#0F0F23,Cinema dark + play red
|
||||
47,Job Board/Recruitment,#0369A1,#FFFFFF,#0EA5E9,#0F172A,#16A34A,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E7EFF5,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0369A1,Professional blue + success green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
48,Marketplace (P2P),#7C3AED,#FFFFFF,#A78BFA,#0F172A,#16A34A,#FFFFFF,#FAF5FF,#4C1D95,#FFFFFF,#4C1D95,#ECEEF9,#64748B,#DDD6FE,#DC2626,#FFFFFF,#7C3AED,Trust purple + transaction green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
49,Logistics/Delivery,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#EA580C,#FFFFFF,#EFF6FF,#1E40AF,#FFFFFF,#1E40AF,#E9EFF8,#64748B,#BFDBFE,#DC2626,#FFFFFF,#2563EB,Tracking blue + delivery orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
50,Agriculture/Farm Tech,#15803D,#FFFFFF,#22C55E,#0F172A,#A16207,#FFFFFF,#F0FDF4,#14532D,#FFFFFF,#14532D,#E8F0F1,#64748B,#BBF7D0,#DC2626,#FFFFFF,#15803D,Earth green + harvest gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
51,Construction/Architecture,#64748B,#FFFFFF,#94A3B8,#0F172A,#EA580C,#FFFFFF,#F8FAFC,#334155,#FFFFFF,#334155,#EBF0F5,#64748B,#E2E8F0,#DC2626,#FFFFFF,#64748B,Industrial grey + safety orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
52,Automotive/Car Dealership,#1E293B,#FFFFFF,#334155,#FFFFFF,#DC2626,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#E9EDF1,#64748B,#E2E8F0,#DC2626,#FFFFFF,#1E293B,Premium dark + action red
|
||||
53,Photography Studio,#18181B,#FFFFFF,#27272A,#FFFFFF,#F8FAFC,#0F172A,#000000,#FAFAFA,#0C0C0C,#FAFAFA,#181818,#94A3B8,#3F3F46,#EF4444,#FFFFFF,#18181B,Pure black + white contrast
|
||||
54,Coworking Space,#F59E0B,#0F172A,#FBBF24,#0F172A,#2563EB,#FFFFFF,#FFFBEB,#78350F,#FFFFFF,#78350F,#F1F2EF,#64748B,#FDE68A,#DC2626,#FFFFFF,#F59E0B,Energetic amber + booking blue
|
||||
55,Home Services (Plumber/Electrician),#1E40AF,#FFFFFF,#3B82F6,#FFFFFF,#EA580C,#FFFFFF,#EFF6FF,#1E3A8A,#FFFFFF,#1E3A8A,#E9EEF6,#64748B,#BFDBFE,#DC2626,#FFFFFF,#1E40AF,Professional blue + urgent orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
56,Childcare/Daycare,#F472B6,#0F172A,#FBCFE8,#0F172A,#16A34A,#FFFFFF,#FDF2F8,#9D174D,#FFFFFF,#9D174D,#F1F0F6,#64748B,#FCE7F3,#DC2626,#FFFFFF,#F472B6,Soft pink + safe green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
57,Senior Care/Elderly,#0369A1,#FFFFFF,#38BDF8,#0F172A,#16A34A,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E7EFF5,#64748B,#E0F2FE,#DC2626,#FFFFFF,#0369A1,Calm blue + reassuring green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
58,Medical Clinic,#0891B2,#FFFFFF,#22D3EE,#0F172A,#16A34A,#FFFFFF,#F0FDFA,#134E4A,#FFFFFF,#134E4A,#E8F1F6,#64748B,#CCFBF1,#DC2626,#FFFFFF,#0891B2,Medical teal + health green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
59,Pharmacy/Drug Store,#15803D,#FFFFFF,#22C55E,#0F172A,#0369A1,#FFFFFF,#F0FDF4,#14532D,#FFFFFF,#14532D,#E8F0F1,#64748B,#BBF7D0,#DC2626,#FFFFFF,#15803D,Pharmacy green + trust blue
|
||||
60,Dental Practice,#0EA5E9,#0F172A,#38BDF8,#0F172A,#0EA5E9,#0F172A,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E8F2F8,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0EA5E9,Fresh blue + smile yellow [Accent adjusted from #FBBF24 for WCAG 3:1]
|
||||
61,Veterinary Clinic,#0D9488,#FFFFFF,#14B8A6,#0F172A,#EA580C,#FFFFFF,#F0FDFA,#134E4A,#FFFFFF,#134E4A,#E8F1F4,#64748B,#99F6E4,#DC2626,#FFFFFF,#0D9488,Caring teal + warm orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
62,Florist/Plant Shop,#15803D,#FFFFFF,#22C55E,#0F172A,#EC4899,#FFFFFF,#F0FDF4,#14532D,#FFFFFF,#14532D,#E8F0F1,#64748B,#BBF7D0,#DC2626,#FFFFFF,#15803D,Natural green + floral pink
|
||||
63,Bakery/Cafe,#92400E,#FFFFFF,#B45309,#FFFFFF,#92400E,#FFFFFF,#FEF3C7,#78350F,#FFFFFF,#78350F,#EDEEF0,#64748B,#FDE68A,#DC2626,#FFFFFF,#92400E,Warm brown + cream white [Accent adjusted from #F8FAFC for WCAG 3:1]
|
||||
64,Brewery/Winery,#7C2D12,#FFFFFF,#B91C1C,#FFFFFF,#A16207,#FFFFFF,#FEF2F2,#450A0A,#FFFFFF,#450A0A,#ECEDF0,#64748B,#FECACA,#DC2626,#FFFFFF,#7C2D12,Deep burgundy + craft gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
65,Airline,#1E3A8A,#FFFFFF,#3B82F6,#FFFFFF,#EA580C,#FFFFFF,#EFF6FF,#1E40AF,#FFFFFF,#1E40AF,#E9EEF5,#64748B,#BFDBFE,#DC2626,#FFFFFF,#1E3A8A,Sky blue + booking orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
66,News/Media Platform,#DC2626,#FFFFFF,#EF4444,#FFFFFF,#1E40AF,#FFFFFF,#FEF2F2,#450A0A,#FFFFFF,#450A0A,#F0EDF1,#64748B,#FECACA,#DC2626,#FFFFFF,#DC2626,Breaking red + link blue
|
||||
67,Magazine/Blog,#18181B,#FFFFFF,#3F3F46,#FFFFFF,#EC4899,#FFFFFF,#FAFAFA,#09090B,#FFFFFF,#09090B,#E8ECF0,#64748B,#E4E4E7,#DC2626,#FFFFFF,#18181B,Editorial black + accent pink
|
||||
68,Freelancer Platform,#6366F1,#FFFFFF,#818CF8,#0F172A,#16A34A,#FFFFFF,#EEF2FF,#312E81,#FFFFFF,#312E81,#EBEFF9,#64748B,#C7D2FE,#DC2626,#FFFFFF,#6366F1,Creative indigo + hire green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
69,Marketing Agency,#EC4899,#FFFFFF,#F472B6,#0F172A,#0891B2,#FFFFFF,#FDF2F8,#831843,#FFFFFF,#831843,#F1EEF5,#64748B,#FBCFE8,#DC2626,#FFFFFF,#EC4899,Bold pink + creative cyan [Accent adjusted from #06B6D4 for WCAG 3:1]
|
||||
70,Event Management,#7C3AED,#FFFFFF,#A78BFA,#0F172A,#EA580C,#FFFFFF,#FAF5FF,#4C1D95,#FFFFFF,#4C1D95,#ECEEF9,#64748B,#DDD6FE,#DC2626,#FFFFFF,#7C3AED,Excitement purple + action orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
71,Membership/Community,#7C3AED,#FFFFFF,#A78BFA,#0F172A,#16A34A,#FFFFFF,#FAF5FF,#4C1D95,#FFFFFF,#4C1D95,#ECEEF9,#64748B,#DDD6FE,#DC2626,#FFFFFF,#7C3AED,Community purple + join green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
72,Newsletter Platform,#0369A1,#FFFFFF,#0EA5E9,#0F172A,#EA580C,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E7EFF5,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0369A1,Trust blue + subscribe orange [Accent adjusted from #F97316 for WCAG 3:1]
|
||||
73,Digital Products/Downloads,#6366F1,#FFFFFF,#818CF8,#0F172A,#16A34A,#FFFFFF,#EEF2FF,#312E81,#FFFFFF,#312E81,#EBEFF9,#64748B,#C7D2FE,#DC2626,#FFFFFF,#6366F1,Digital indigo + buy green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
74,Church/Religious Organization,#7C3AED,#FFFFFF,#A78BFA,#0F172A,#A16207,#FFFFFF,#FAF5FF,#4C1D95,#FFFFFF,#4C1D95,#ECEEF9,#64748B,#DDD6FE,#DC2626,#FFFFFF,#7C3AED,Spiritual purple + warm gold [Accent adjusted from #CA8A04 for WCAG 3:1]
|
||||
75,Sports Team/Club,#DC2626,#FFFFFF,#EF4444,#FFFFFF,#DC2626,#FFFFFF,#FEF2F2,#7F1D1D,#FFFFFF,#7F1D1D,#F0EDF1,#64748B,#FECACA,#DC2626,#FFFFFF,#DC2626,Team red + championship gold [Accent adjusted from #FBBF24 for WCAG 3:1]
|
||||
76,Museum/Gallery,#18181B,#FFFFFF,#27272A,#FFFFFF,#18181B,#FFFFFF,#FAFAFA,#09090B,#FFFFFF,#09090B,#E8ECF0,#64748B,#E4E4E7,#DC2626,#FFFFFF,#18181B,Gallery black + white space [Accent adjusted from #F8FAFC for WCAG 3:1]
|
||||
77,Theater/Cinema,#1E1B4B,#FFFFFF,#312E81,#FFFFFF,#CA8A04,#0F172A,#0F0F23,#F8FAFC,#1B1B30,#F8FAFC,#27273B,#94A3B8,#4338CA,#EF4444,#FFFFFF,#1E1B4B,Dramatic dark + spotlight gold
|
||||
78,Language Learning App,#4F46E5,#FFFFFF,#818CF8,#0F172A,#16A34A,#FFFFFF,#EEF2FF,#312E81,#FFFFFF,#312E81,#EBEEF8,#64748B,#C7D2FE,#DC2626,#FFFFFF,#4F46E5,Learning indigo + progress green [Accent adjusted from #22C55E for WCAG 3:1]
|
||||
79,Coding Bootcamp,#0F172A,#FFFFFF,#1E293B,#FFFFFF,#22C55E,#0F172A,#020617,#F8FAFC,#0E1223,#F8FAFC,#1A1E2F,#94A3B8,#334155,#EF4444,#FFFFFF,#0F172A,Terminal dark + success green
|
||||
80,Cybersecurity Platform,#00FF41,#0F172A,#0D0D0D,#FFFFFF,#FF3333,#FFFFFF,#000000,#E0E0E0,#0C130E,#E0E0E0,#181818,#94A3B8,#1F1F1F,#EF4444,#FFFFFF,#00FF41,Matrix green + alert red
|
||||
81,Developer Tool / IDE,#1E293B,#FFFFFF,#334155,#FFFFFF,#22C55E,#0F172A,#0F172A,#F8FAFC,#1B2336,#F8FAFC,#272F42,#94A3B8,#475569,#EF4444,#FFFFFF,#1E293B,Code dark + run green
|
||||
82,Biotech / Life Sciences,#0EA5E9,#0F172A,#0284C7,#FFFFFF,#059669,#FFFFFF,#F0F9FF,#0C4A6E,#FFFFFF,#0C4A6E,#E8F2F8,#64748B,#BAE6FD,#DC2626,#FFFFFF,#0EA5E9,DNA blue + life green [Accent adjusted from #10B981 for WCAG 3:1]
|
||||
83,Space Tech / Aerospace,#F8FAFC,#0F172A,#94A3B8,#0F172A,#3B82F6,#FFFFFF,#0B0B10,#F8FAFC,#1E1E23,#F8FAFC,#232328,#94A3B8,#1E293B,#EF4444,#FFFFFF,#F8FAFC,Star white + launch blue
|
||||
84,Architecture / Interior,#171717,#FFFFFF,#404040,#FFFFFF,#A16207,#FFFFFF,#FFFFFF,#171717,#FFFFFF,#171717,#E8ECF0,#64748B,#E5E5E5,#DC2626,#FFFFFF,#171717,Minimal black + accent gold [Accent adjusted from #D4AF37 for WCAG 3:1]
|
||||
85,Quantum Computing Interface,#00FFFF,#0F172A,#7B61FF,#FFFFFF,#FF00FF,#FFFFFF,#050510,#E0E0FF,#101823,#E0E0FF,#1D1D28,#94A3B8,#333344,#EF4444,#FFFFFF,#00FFFF,Quantum cyan + interference purple
|
||||
86,Biohacking / Longevity App,#FF4D4D,#FFFFFF,#4D94FF,#FFFFFF,#059669,#FFFFFF,#F5F5F7,#1C1C1E,#FFFFFF,#1C1C1E,#F2EEF2,#64748B,#E5E5EA,#DC2626,#FFFFFF,#FF4D4D,Bio red/blue + vitality green [Accent adjusted from #00E676 for WCAG 3:1]
|
||||
87,Autonomous Drone Fleet Manager,#00FF41,#0F172A,#008F11,#FFFFFF,#FF3333,#FFFFFF,#0D1117,#E6EDF3,#182424,#E6EDF3,#25292F,#94A3B8,#30363D,#EF4444,#FFFFFF,#00FF41,Terminal green + alert red
|
||||
88,Generative Art Platform,#18181B,#FFFFFF,#3F3F46,#FFFFFF,#EC4899,#FFFFFF,#FAFAFA,#09090B,#FFFFFF,#09090B,#E8ECF0,#64748B,#E4E4E7,#DC2626,#FFFFFF,#18181B,Canvas neutral + creative pink
|
||||
89,Spatial Computing OS / App,#FFFFFF,#0F172A,#E5E5E5,#0F172A,#FFFFFF,#0F172A,#888888,#000000,#999999,#000000,#777777,#D4D4D4,#CCCCCC,#FF3B30,#FFFFFF,#007AFF,Glass white + system blue [Accent adjusted from #007AFF for WCAG 3:1]
|
||||
90,Sustainable Energy / Climate Tech,#059669,#FFFFFF,#10B981,#0F172A,#059669,#FFFFFF,#ECFDF5,#064E3B,#FFFFFF,#064E3B,#E8F1F3,#64748B,#A7F3D0,#DC2626,#FFFFFF,#059669,Nature green + solar gold [Accent adjusted from #FBBF24 for WCAG 3:1]
|
||||
91,Personal Finance Tracker,#1E40AF,#FFFFFF,#3B82F6,#FFFFFF,#059669,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#101A34,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#1E40AF,Trust blue + profit green on dark
|
||||
92,Chat & Messaging App,#2563EB,#FFFFFF,#6366F1,#FFFFFF,#059669,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Messenger blue + online green
|
||||
93,Notes & Writing App,#78716C,#FFFFFF,#A8A29E,#FFFFFF,#D97706,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#F6F6F6,#64748B,#EEEDED,#DC2626,#FFFFFF,#78716C,Warm ink + amber accent on cream
|
||||
94,Habit Tracker,#D97706,#FFFFFF,#F59E0B,#0F172A,#059669,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#FCF6F0,#64748B,#FAEEE1,#DC2626,#FFFFFF,#D97706,Streak amber + habit green
|
||||
95,Food Delivery / On-Demand,#EA580C,#FFFFFF,#F97316,#FFFFFF,#2563EB,#FFFFFF,#FFF7ED,#0F172A,#FFFFFF,#0F172A,#FDF4F0,#64748B,#FCEAE1,#DC2626,#FFFFFF,#EA580C,Appetizing orange + trust blue
|
||||
96,Ride Hailing / Transportation,#1E293B,#FFFFFF,#334155,#FFFFFF,#2563EB,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#10182B,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#1E293B,Map dark + route blue
|
||||
97,Recipe & Cooking App,#9A3412,#FFFFFF,#C2410C,#FFFFFF,#059669,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#F8F2F0,#64748B,#F2E6E2,#DC2626,#FFFFFF,#9A3412,Warm terracotta + fresh green
|
||||
98,Meditation & Mindfulness,#7C3AED,#FFFFFF,#8B5CF6,#FFFFFF,#059669,#FFFFFF,#FAF5FF,#0F172A,#FFFFFF,#0F172A,#F7F3FD,#64748B,#EFE7FC,#DC2626,#FFFFFF,#7C3AED,Calm lavender + mindful green
|
||||
99,Weather App,#0284C7,#FFFFFF,#0EA5E9,#FFFFFF,#F59E0B,#0F172A,#F0F9FF,#0F172A,#FFFFFF,#0F172A,#EFF7FB,#64748B,#E0F0F8,#DC2626,#FFFFFF,#0284C7,Sky blue + sun amber
|
||||
100,Diary & Journal App,#92400E,#FFFFFF,#A16207,#FFFFFF,#6366F1,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#F8F3F0,#64748B,#F1E8E2,#DC2626,#FFFFFF,#92400E,Warm journal brown + ink violet
|
||||
101,CRM & Client Management,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#059669,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Professional blue + deal green
|
||||
102,Inventory & Stock Management,#334155,#FFFFFF,#475569,#FFFFFF,#059669,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F2F3F4,#64748B,#E6E8EA,#DC2626,#FFFFFF,#334155,Industrial slate + stock green
|
||||
103,Flashcard & Study Tool,#7C3AED,#FFFFFF,#8B5CF6,#FFFFFF,#059669,#FFFFFF,#FAF5FF,#0F172A,#FFFFFF,#0F172A,#F7F3FD,#64748B,#EFE7FC,#DC2626,#FFFFFF,#7C3AED,Study purple + correct green
|
||||
104,Booking & Appointment App,#0284C7,#FFFFFF,#0EA5E9,#FFFFFF,#059669,#FFFFFF,#F0F9FF,#0F172A,#FFFFFF,#0F172A,#EFF7FB,#64748B,#E0F0F8,#DC2626,#FFFFFF,#0284C7,Calendar blue + available green
|
||||
105,Invoice & Billing Tool,#1E3A5F,#FFFFFF,#2563EB,#FFFFFF,#059669,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F3F5,#64748B,#E4E7EB,#DC2626,#FFFFFF,#1E3A5F,Navy professional + paid green
|
||||
106,Grocery & Shopping List,#059669,#FFFFFF,#10B981,#FFFFFF,#D97706,#FFFFFF,#ECFDF5,#0F172A,#FFFFFF,#0F172A,#F0F8F6,#64748B,#E1F2ED,#DC2626,#FFFFFF,#059669,Fresh green + food amber
|
||||
107,Timer & Pomodoro,#DC2626,#FFFFFF,#EF4444,#FFFFFF,#059669,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#1F1829,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#DC2626,Focus red on dark + break green
|
||||
108,Parenting & Baby Tracker,#EC4899,#FFFFFF,#F472B6,#FFFFFF,#0284C7,#FFFFFF,#FDF2F8,#0F172A,#FFFFFF,#0F172A,#FDF4F8,#64748B,#FCE9F2,#DC2626,#FFFFFF,#EC4899,Soft pink + trust blue
|
||||
109,Scanner & Document Manager,#1E293B,#FFFFFF,#334155,#FFFFFF,#2563EB,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F2F3,#64748B,#E4E5E7,#DC2626,#FFFFFF,#1E293B,Document grey + scan blue
|
||||
110,Calendar & Scheduling App,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#059669,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Calendar blue + event green
|
||||
111,Password Manager,#1E3A5F,#FFFFFF,#334155,#FFFFFF,#059669,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#10192E,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#1E3A5F,Vault dark blue + secure green
|
||||
112,Expense Splitter / Bill Split,#059669,#FFFFFF,#10B981,#FFFFFF,#DC2626,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F0F8F6,#64748B,#E1F2ED,#DC2626,#FFFFFF,#059669,Balance green + owe red
|
||||
113,Voice Recorder & Memo,#DC2626,#FFFFFF,#EF4444,#FFFFFF,#2563EB,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#FCF1F1,#64748B,#FAE4E4,#DC2626,#FFFFFF,#DC2626,Recording red + waveform blue
|
||||
114,Bookmark & Read-Later,#D97706,#FFFFFF,#F59E0B,#0F172A,#2563EB,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#FCF6F0,#64748B,#FAEEE1,#DC2626,#FFFFFF,#D97706,Warm amber + link blue
|
||||
115,Translator App,#2563EB,#FFFFFF,#0891B2,#FFFFFF,#EA580C,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Global blue + teal + accent orange
|
||||
116,Calculator & Unit Converter,#EA580C,#FFFFFF,#F97316,#FFFFFF,#2563EB,#FFFFFF,#1C1917,#FFFFFF,#262321,#FFFFFF,#2C1E16,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#EA580C,Operation orange on dark
|
||||
117,Alarm & World Clock,#D97706,#FFFFFF,#F59E0B,#0F172A,#6366F1,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#1F1E27,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#D97706,Time amber + night indigo on dark
|
||||
118,File Manager & Transfer,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#D97706,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Folder blue + file amber
|
||||
119,Email Client,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#DC2626,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Inbox blue + priority red
|
||||
120,Casual Puzzle Game,#EC4899,#FFFFFF,#8B5CF6,#FFFFFF,#F59E0B,#0F172A,#FDF2F8,#0F172A,#FFFFFF,#0F172A,#FDF4F8,#64748B,#FCE9F2,#DC2626,#FFFFFF,#EC4899,Cheerful pink + reward gold
|
||||
121,Trivia & Quiz Game,#2563EB,#FFFFFF,#7C3AED,#FFFFFF,#F59E0B,#0F172A,#EFF6FF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Quiz blue + gold leaderboard
|
||||
122,Card & Board Game,#15803D,#FFFFFF,#166534,#FFFFFF,#D97706,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#0F1F2B,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#15803D,Felt green + gold on dark
|
||||
123,Idle & Clicker Game,#D97706,#FFFFFF,#F59E0B,#0F172A,#7C3AED,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#FCF6F0,#64748B,#FAEEE1,#DC2626,#FFFFFF,#D97706,Coin gold + prestige purple
|
||||
124,Word & Crossword Game,#15803D,#FFFFFF,#059669,#FFFFFF,#D97706,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#F0F7F3,#64748B,#E2EFE7,#DC2626,#FFFFFF,#15803D,Word green + letter amber
|
||||
125,Arcade & Retro Game,#DC2626,#FFFFFF,#2563EB,#FFFFFF,#22C55E,#0F172A,#0F172A,#FFFFFF,#192134,#FFFFFF,#1F1829,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#DC2626,Neon red+blue on dark + score green
|
||||
126,Photo Editor & Filters,#7C3AED,#FFFFFF,#6366F1,#FFFFFF,#0891B2,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#171939,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#7C3AED,Editor violet + filter cyan on dark
|
||||
127,Short Video Editor,#EC4899,#FFFFFF,#DB2777,#FFFFFF,#2563EB,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#201A32,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#EC4899,Video pink on dark + timeline blue
|
||||
128,Drawing & Sketching Canvas,#7C3AED,#FFFFFF,#8B5CF6,#FFFFFF,#0891B2,#FFFFFF,#1C1917,#FFFFFF,#262321,#FFFFFF,#231B28,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#7C3AED,Canvas purple + tool teal on dark
|
||||
129,Music Creation & Beat Maker,#7C3AED,#FFFFFF,#6366F1,#FFFFFF,#22C55E,#0F172A,#0F172A,#FFFFFF,#192134,#FFFFFF,#171939,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#7C3AED,Studio purple + waveform green on dark
|
||||
130,Meme & Sticker Maker,#EC4899,#FFFFFF,#F59E0B,#0F172A,#2563EB,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#FDF4F8,#64748B,#FCE9F2,#DC2626,#FFFFFF,#EC4899,Viral pink + comedy yellow + share blue
|
||||
131,AI Photo & Avatar Generator,#7C3AED,#FFFFFF,#6366F1,#FFFFFF,#EC4899,#FFFFFF,#FAF5FF,#0F172A,#FFFFFF,#0F172A,#F7F3FD,#64748B,#EFE7FC,#DC2626,#FFFFFF,#7C3AED,AI purple + generation pink
|
||||
132,Link-in-Bio Page Builder,#2563EB,#FFFFFF,#7C3AED,#FFFFFF,#EC4899,#FFFFFF,#FFFFFF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Brand blue + creator purple
|
||||
133,Wardrobe & Outfit Planner,#BE185D,#FFFFFF,#EC4899,#FFFFFF,#D97706,#FFFFFF,#FDF2F8,#0F172A,#FFFFFF,#0F172A,#FBF1F5,#64748B,#F7E3EB,#DC2626,#FFFFFF,#BE185D,Fashion rose + gold accent
|
||||
134,Plant Care Tracker,#15803D,#FFFFFF,#059669,#FFFFFF,#D97706,#FFFFFF,#F0FDF4,#0F172A,#FFFFFF,#0F172A,#F0F7F3,#64748B,#E2EFE7,#DC2626,#FFFFFF,#15803D,Nature green + sun yellow
|
||||
135,Book & Reading Tracker,#78716C,#FFFFFF,#92400E,#FFFFFF,#D97706,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#F6F6F6,#64748B,#EEEDED,#DC2626,#FFFFFF,#78716C,Book brown + page amber
|
||||
136,Couple & Relationship App,#BE185D,#FFFFFF,#EC4899,#FFFFFF,#DC2626,#FFFFFF,#FDF2F8,#0F172A,#FFFFFF,#0F172A,#FBF1F5,#64748B,#F7E3EB,#DC2626,#FFFFFF,#BE185D,Romance rose + love red
|
||||
137,Family Calendar & Chores,#2563EB,#FFFFFF,#059669,#FFFFFF,#D97706,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Family blue + chore green
|
||||
138,Mood Tracker,#7C3AED,#FFFFFF,#6366F1,#FFFFFF,#D97706,#FFFFFF,#FAF5FF,#0F172A,#FFFFFF,#0F172A,#F7F3FD,#64748B,#EFE7FC,#DC2626,#FFFFFF,#7C3AED,Mood purple + insight amber
|
||||
139,Gift & Wishlist,#DC2626,#FFFFFF,#D97706,#FFFFFF,#EC4899,#FFFFFF,#FFF1F2,#0F172A,#FFFFFF,#0F172A,#FCF1F1,#64748B,#FAE4E4,#DC2626,#FFFFFF,#DC2626,Gift red + gold + surprise pink
|
||||
140,Running & Cycling GPS,#EA580C,#FFFFFF,#F97316,#FFFFFF,#059669,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#201C27,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#EA580C,Energetic orange + pace green on dark
|
||||
141,Yoga & Stretching Guide,#6B7280,#FFFFFF,#78716C,#FFFFFF,#0891B2,#FFFFFF,#F5F5F0,#0F172A,#FFFFFF,#0F172A,#F6F6F7,#64748B,#EDEEEF,#DC2626,#FFFFFF,#6B7280,Sage neutral + calm teal
|
||||
142,Sleep Tracker,#4338CA,#FFFFFF,#6366F1,#FFFFFF,#7C3AED,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#131936,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#4338CA,Night indigo + dream violet on dark
|
||||
143,Calorie & Nutrition Counter,#059669,#FFFFFF,#10B981,#FFFFFF,#EA580C,#FFFFFF,#ECFDF5,#0F172A,#FFFFFF,#0F172A,#F0F8F6,#64748B,#E1F2ED,#DC2626,#FFFFFF,#059669,Healthy green + macro orange
|
||||
144,Period & Cycle Tracker,#BE185D,#FFFFFF,#EC4899,#FFFFFF,#7C3AED,#FFFFFF,#FDF2F8,#0F172A,#FFFFFF,#0F172A,#FBF1F5,#64748B,#F7E3EB,#DC2626,#FFFFFF,#BE185D,Blush rose + fertility lavender
|
||||
145,Medication & Pill Reminder,#0284C7,#FFFFFF,#0891B2,#FFFFFF,#DC2626,#FFFFFF,#F0F9FF,#0F172A,#FFFFFF,#0F172A,#EFF7FB,#64748B,#E0F0F8,#DC2626,#FFFFFF,#0284C7,Medical blue + alert red
|
||||
146,Water & Hydration Reminder,#0284C7,#FFFFFF,#06B6D4,#FFFFFF,#0891B2,#FFFFFF,#F0F9FF,#0F172A,#FFFFFF,#0F172A,#EFF7FB,#64748B,#E0F0F8,#DC2626,#FFFFFF,#0284C7,Refreshing blue + water cyan
|
||||
147,Fasting & Intermittent Timer,#6366F1,#FFFFFF,#4338CA,#FFFFFF,#059669,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#151D39,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#6366F1,Fasting indigo on dark + eating green
|
||||
148,Anonymous Community / Confession,#475569,#FFFFFF,#334155,#FFFFFF,#0891B2,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#131B2F,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#475569,Protective grey + subtle teal on dark
|
||||
149,Local Events & Discovery,#EA580C,#FFFFFF,#F97316,#FFFFFF,#2563EB,#FFFFFF,#FFF7ED,#0F172A,#FFFFFF,#0F172A,#FDF4F0,#64748B,#FCEAE1,#DC2626,#FFFFFF,#EA580C,Event orange + map blue
|
||||
150,Study Together / Virtual Coworking,#2563EB,#FFFFFF,#3B82F6,#FFFFFF,#059669,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Focus blue + session green
|
||||
151,Coding Challenge & Practice,#22C55E,#0F172A,#059669,#FFFFFF,#D97706,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#10242E,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#22C55E,Code green + difficulty amber on dark
|
||||
152,Kids Learning (ABC & Math),#2563EB,#FFFFFF,#F59E0B,#0F172A,#EC4899,#FFFFFF,#EFF6FF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Learning blue + play yellow + fun pink
|
||||
153,Music Instrument Learning,#DC2626,#FFFFFF,#9A3412,#FFFFFF,#D97706,#FFFFFF,#FFFBEB,#0F172A,#FFFFFF,#0F172A,#FCF1F1,#64748B,#FAE4E4,#DC2626,#FFFFFF,#DC2626,Musical red + warm amber
|
||||
154,Parking Finder,#2563EB,#FFFFFF,#059669,#FFFFFF,#DC2626,#FFFFFF,#F0F9FF,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Available blue/green + occupied red
|
||||
155,Public Transit Guide,#2563EB,#FFFFFF,#0891B2,#FFFFFF,#EA580C,#FFFFFF,#F8FAFC,#0F172A,#FFFFFF,#0F172A,#F1F5FD,#64748B,#E4ECFC,#DC2626,#FFFFFF,#2563EB,Transit blue + line colors
|
||||
156,Road Trip Planner,#EA580C,#FFFFFF,#0891B2,#FFFFFF,#D97706,#FFFFFF,#FFF7ED,#0F172A,#FFFFFF,#0F172A,#FDF4F0,#64748B,#FCEAE1,#DC2626,#FFFFFF,#EA580C,Adventure orange + map teal
|
||||
157,VPN & Privacy Tool,#1E3A5F,#FFFFFF,#334155,#FFFFFF,#22C55E,#0F172A,#0F172A,#FFFFFF,#192134,#FFFFFF,#10192E,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#1E3A5F,Shield dark + connected green
|
||||
158,Emergency SOS & Safety,#DC2626,#FFFFFF,#EF4444,#FFFFFF,#2563EB,#FFFFFF,#FFF1F2,#0F172A,#FFFFFF,#0F172A,#FCF1F1,#64748B,#FAE4E4,#DC2626,#FFFFFF,#DC2626,Alert red + safety blue
|
||||
159,Wallpaper & Theme App,#7C3AED,#FFFFFF,#EC4899,#FFFFFF,#2563EB,#FFFFFF,#FAF5FF,#0F172A,#FFFFFF,#0F172A,#F7F3FD,#64748B,#EFE7FC,#DC2626,#FFFFFF,#7C3AED,Aesthetic purple + trending pink
|
||||
160,White Noise & Ambient Sound,#475569,#FFFFFF,#334155,#FFFFFF,#4338CA,#FFFFFF,#0F172A,#FFFFFF,#192134,#FFFFFF,#131B2F,#94A3B8,"rgba(255,255,255,0.08)",#DC2626,#FFFFFF,#475569,Ambient grey + deep indigo on dark
|
||||
161,Home Decoration & Interior Design,#78716C,#FFFFFF,#A8A29E,#FFFFFF,#D97706,#FFFFFF,#FAF5F2,#0F172A,#FFFFFF,#0F172A,#F6F6F6,#64748B,#EEEDED,#DC2626,#FFFFFF,#78716C,Interior warm grey + gold accent
|
||||
|
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
|
@ -1,106 +0,0 @@
|
|||
No,Category,Icon Name,Keywords,Library,Import Code,Usage,Best For,Style
|
||||
1,Navigation,list,hamburger menu navigation toggle bars,Phosphor,import { List } from '@phosphor-icons/react',<List size={20} weight="regular" />,Mobile navigation drawer toggle sidebar,Outline
|
||||
2,Navigation,arrow-left,back previous return navigate,Phosphor,import { ArrowLeft } from '@phosphor-icons/react',<ArrowLeft size={20} weight="regular" />,Back button breadcrumb navigation,Outline
|
||||
3,Navigation,arrow-right,next forward continue navigate,Phosphor,import { ArrowRight } from '@phosphor-icons/react',<ArrowRight size={20} weight="regular" />,Forward button next step CTA,Outline
|
||||
4,Navigation,caret-down,dropdown expand accordion select,Phosphor,import { CaretDown } from '@phosphor-icons/react',<CaretDown size={20} weight="regular" />,Dropdown toggle accordion header,Outline
|
||||
5,Navigation,caret-up,collapse close accordion minimize,Phosphor,import { CaretUp } from '@phosphor-icons/react',<CaretUp size={20} weight="regular" />,Accordion collapse minimize,Outline
|
||||
6,Navigation,house,homepage main dashboard start,Phosphor,import { House } from '@phosphor-icons/react',<House size={20} weight="regular" />,Home navigation main page,Outline
|
||||
7,Navigation,x,close cancel dismiss remove exit,Phosphor,import { X } from '@phosphor-icons/react',<X size={20} weight="regular" />,Modal close dismiss button,Outline
|
||||
8,Navigation,arrow-square-out,open new tab external link,Phosphor,import { ArrowSquareOut } from '@phosphor-icons/react',<ArrowSquareOut size={20} weight="regular" />,External link indicator,Outline
|
||||
9,Action,plus,add create new insert,Phosphor,import { Plus } from '@phosphor-icons/react',<Plus size={20} weight="regular" />,Add button create new item,Outline
|
||||
10,Action,minus,remove subtract decrease delete,Phosphor,import { Minus } from '@phosphor-icons/react',<Minus size={20} weight="regular" />,Remove item quantity decrease,Outline
|
||||
11,Action,trash,delete remove discard bin,Phosphor,import { Trash } from '@phosphor-icons/react',<Trash size={20} weight="regular" />,Delete action destructive,Outline
|
||||
12,Action,pencil-simple,pencil modify change update,Phosphor,import { PencilSimple } from '@phosphor-icons/react',<PencilSimple size={20} weight="regular" />,Edit button modify content,Outline
|
||||
13,Action,floppy-disk,disk store persist save,Phosphor,import { FloppyDisk } from '@phosphor-icons/react',<FloppyDisk size={20} weight="regular" />,Save button persist changes,Outline
|
||||
14,Action,download-simple,export save file download,Phosphor,import { DownloadSimple } from '@phosphor-icons/react',<DownloadSimple size={20} weight="regular" />,Download file export,Outline
|
||||
15,Action,upload-simple,import file attach upload,Phosphor,import { UploadSimple } from '@phosphor-icons/react',<UploadSimple size={20} weight="regular" />,Upload file import,Outline
|
||||
16,Action,copy,duplicate clipboard paste,Phosphor,import { Copy } from '@phosphor-icons/react',<Copy size={20} weight="regular" />,Copy to clipboard,Outline
|
||||
17,Action,share,social distribute send,Phosphor,import { Share } from '@phosphor-icons/react',<Share size={20} weight="regular" />,Share button social,Outline
|
||||
18,Action,magnifying-glass,find lookup filter query,Phosphor,import { MagnifyingGlass } from '@phosphor-icons/react',<MagnifyingGlass size={20} weight="regular" />,Search input bar,Outline
|
||||
19,Action,funnel,sort refine narrow options,Phosphor,import { Funnel } from '@phosphor-icons/react',<Funnel size={20} weight="regular" />,Filter dropdown sort,Outline
|
||||
20,Action,gear,gear cog preferences config,Phosphor,import { Gear } from '@phosphor-icons/react',<Gear size={20} weight="regular" />,Settings page configuration,Outline
|
||||
21,Status,check,success done complete verified,Phosphor,import { Check } from '@phosphor-icons/react',<Check size={20} weight="regular" />,Success state checkmark,Outline
|
||||
22,Status,check-circle,success verified approved complete,Phosphor,import { CheckCircle } from '@phosphor-icons/react',<CheckCircle size={20} weight="regular" />,Success badge verified,Outline
|
||||
23,Status,x-circle,error failed cancel rejected,Phosphor,import { XCircle } from '@phosphor-icons/react',<XCircle size={20} weight="regular" />,Error state failed,Outline
|
||||
24,Status,warning,warning caution attention danger,Phosphor,import { Warning } from '@phosphor-icons/react',<Warning size={20} weight="regular" />,Warning message caution,Outline
|
||||
25,Status,warning-circle,info notice information help,Phosphor,import { WarningCircle } from '@phosphor-icons/react',<WarningCircle size={20} weight="regular" />,Info notice alert,Outline
|
||||
26,Status,info,information help tooltip details,Phosphor,import { Info } from '@phosphor-icons/react',<Info size={20} weight="regular" />,Information tooltip help,Outline
|
||||
27,Status,circle-notch,loading spinner processing wait,Phosphor,import { CircleNotch } from '@phosphor-icons/react',<CircleNotch size={20} weight="regular" className="animate-spin" />,Loading state spinner,Outline
|
||||
28,Status,clock,time schedule pending wait,Phosphor,import { Clock } from '@phosphor-icons/react',<Clock size={20} weight="regular" />,Pending time schedule,Outline
|
||||
29,Communication,envelope,email message inbox letter,Phosphor,import { Envelope } from '@phosphor-icons/react',<Envelope size={20} weight="regular" />,Email contact inbox,Outline
|
||||
30,Communication,chat-circle,chat comment bubble conversation,Phosphor,import { ChatCircle } from '@phosphor-icons/react',<ChatCircle size={20} weight="regular" />,Chat comment message,Outline
|
||||
31,Communication,phone,call mobile telephone contact,Phosphor,import { Phone } from '@phosphor-icons/react',<Phone size={20} weight="regular" />,Phone contact call,Outline
|
||||
32,Communication,paper-plane-tilt,submit dispatch message airplane,Phosphor,import { PaperPlaneTilt } from '@phosphor-icons/react',<PaperPlaneTilt size={20} weight="regular" />,Send message submit,Outline
|
||||
33,Communication,bell,notification alert ring reminder,Phosphor,import { Bell } from '@phosphor-icons/react',<Bell size={20} weight="regular" />,Notification bell alert,Outline
|
||||
34,User,user,profile account person avatar,Phosphor,import { User } from '@phosphor-icons/react',<User size={20} weight="regular" />,User profile account,Outline
|
||||
35,User,users,team group people members,Phosphor,import { Users } from '@phosphor-icons/react',<Users size={20} weight="regular" />,Team group members,Outline
|
||||
36,User,user-plus,add invite new member,Phosphor,import { UserPlus } from '@phosphor-icons/react',<UserPlus size={20} weight="regular" />,Add user invite,Outline
|
||||
37,User,sign-in,signin authenticate enter,Phosphor,import { SignIn } from '@phosphor-icons/react',<SignIn size={20} weight="regular" />,Login signin,Outline
|
||||
38,User,sign-out,signout exit leave logout,Phosphor,import { SignOut } from '@phosphor-icons/react',<SignOut size={20} weight="regular" />,Logout signout,Outline
|
||||
39,Media,image,photo picture gallery thumbnail,Phosphor,import { Image } from '@phosphor-icons/react',<Image size={20} weight="regular" />,Image photo gallery,Outline
|
||||
40,Media,video,movie film play record,Phosphor,import { Video } from '@phosphor-icons/react',<Video size={20} weight="regular" />,Video player media,Outline
|
||||
41,Media,play,start video audio media,Phosphor,import { Play } from '@phosphor-icons/react',<Play size={20} weight="regular" />,Play button video audio,Outline
|
||||
42,Media,pause,stop halt video audio,Phosphor,import { Pause } from '@phosphor-icons/react',<Pause size={20} weight="regular" />,Pause button media,Outline
|
||||
43,Media,speaker-high,sound audio speaker music,Phosphor,import { SpeakerHigh } from '@phosphor-icons/react',<SpeakerHigh size={20} weight="regular" />,Volume audio sound,Outline
|
||||
44,Media,microphone,microphone record voice audio,Phosphor,import { Microphone } from '@phosphor-icons/react',<Microphone size={20} weight="regular" />,Microphone voice record,Outline
|
||||
45,Media,camera,photo capture snapshot picture,Phosphor,import { Camera } from '@phosphor-icons/react',<Camera size={20} weight="regular" />,Camera photo capture,Outline
|
||||
46,Commerce,shopping-cart,cart checkout basket buy,Phosphor,import { ShoppingCart } from '@phosphor-icons/react',<ShoppingCart size={20} weight="regular" />,Shopping cart e-commerce,Outline
|
||||
47,Commerce,shopping-bag,purchase buy store bag,Phosphor,import { ShoppingBag } from '@phosphor-icons/react',<ShoppingBag size={20} weight="regular" />,Shopping bag purchase,Outline
|
||||
48,Commerce,credit-card,payment card checkout stripe,Phosphor,import { CreditCard } from '@phosphor-icons/react',<CreditCard size={20} weight="regular" />,Payment credit card,Outline
|
||||
49,Commerce,currency-dollar,money price currency cost,Phosphor,import { CurrencyDollar } from '@phosphor-icons/react',<CurrencyDollar size={20} weight="regular" />,Price money currency,Outline
|
||||
50,Commerce,tag,label price discount sale,Phosphor,import { Tag } from '@phosphor-icons/react',<Tag size={20} weight="regular" />,Price tag label,Outline
|
||||
51,Commerce,gift,present reward bonus offer,Phosphor,import { Gift } from '@phosphor-icons/react',<Gift size={20} weight="regular" />,Gift reward offer,Outline
|
||||
52,Commerce,percent,discount sale offer promo,Phosphor,import { Percent } from '@phosphor-icons/react',<Percent size={20} weight="regular" />,Discount percentage sale,Outline
|
||||
53,Data,chart-bar,analytics statistics graph metrics,Phosphor,import { ChartBar } from '@phosphor-icons/react',<ChartBar size={20} weight="regular" />,Bar chart analytics,Outline
|
||||
54,Data,chart-pie,statistics distribution breakdown,Phosphor,import { ChartPie } from '@phosphor-icons/react',<ChartPie size={20} weight="regular" />,Pie chart distribution,Outline
|
||||
55,Data,trend-up,growth increase positive trend,Phosphor,import { TrendUp } from '@phosphor-icons/react',<TrendUp size={20} weight="regular" />,Growth trend positive,Outline
|
||||
56,Data,trend-down,decline decrease negative trend,Phosphor,import { TrendDown } from '@phosphor-icons/react',<TrendDown size={20} weight="regular" />,Decline trend negative,Outline
|
||||
57,Data,activity,pulse heartbeat monitor live,Phosphor,import { Activity } from '@phosphor-icons/react',<Activity size={20} weight="regular" />,Activity monitor pulse,Outline
|
||||
58,Data,database,storage server data backend,Phosphor,import { Database } from '@phosphor-icons/react',<Database size={20} weight="regular" />,Database storage,Outline
|
||||
59,Files,file,document page paper doc,Phosphor,import { File } from '@phosphor-icons/react',<File size={20} weight="regular" />,File document,Outline
|
||||
60,Files,file-text,document text page article,Phosphor,import { FileText } from '@phosphor-icons/react',<FileText size={20} weight="regular" />,Text document article,Outline
|
||||
61,Files,folder,directory organize group files,Phosphor,import { Folder } from '@phosphor-icons/react',<Folder size={20} weight="regular" />,Folder directory,Outline
|
||||
62,Files,folder-open,expanded browse files view,Phosphor,import { FolderOpen } from '@phosphor-icons/react',<FolderOpen size={20} weight="regular" />,Open folder browse,Outline
|
||||
63,Files,paperclip,attachment attach file link,Phosphor,import { Paperclip } from '@phosphor-icons/react',<Paperclip size={20} weight="regular" />,Attachment paperclip,Outline
|
||||
64,Files,link,url hyperlink chain connect,Phosphor,import { Link } from '@phosphor-icons/react',<Link size={20} weight="regular" />,Link URL hyperlink,Outline
|
||||
65,Files,clipboard,paste copy buffer notes,Phosphor,import { Clipboard } from '@phosphor-icons/react',<Clipboard size={20} weight="regular" />,Clipboard paste,Outline
|
||||
66,Layout,grid-four,tiles gallery layout dashboard,Phosphor,import { GridFour } from '@phosphor-icons/react',<GridFour size={20} weight="regular" />,Grid layout gallery,Outline
|
||||
67,Layout,list-bullets,rows table lines items,Phosphor,import { ListBullets } from '@phosphor-icons/react',<ListBullets size={20} weight="regular" />,List view rows,Outline
|
||||
68,Layout,columns,layout split dual sidebar,Phosphor,import { Columns } from '@phosphor-icons/react',<Columns size={20} weight="regular" />,Column layout split,Outline
|
||||
69,Layout,arrows-out,fullscreen expand enlarge zoom,Phosphor,import { ArrowsOut } from '@phosphor-icons/react',<ArrowsOut size={20} weight="regular" />,Fullscreen maximize,Outline
|
||||
70,Layout,arrows-in,reduce shrink collapse exit,Phosphor,import { ArrowsIn } from '@phosphor-icons/react',<ArrowsIn size={20} weight="regular" />,Minimize reduce,Outline
|
||||
71,Layout,sidebar,panel drawer navigation menu,Phosphor,import { Sidebar } from '@phosphor-icons/react',<Sidebar size={20} weight="regular" />,Sidebar panel,Outline
|
||||
72,Social,heart,like love favorite wishlist,Phosphor,import { Heart } from '@phosphor-icons/react',<Heart size={20} weight="regular" />,Like favorite love,Outline
|
||||
73,Social,star,rating review favorite bookmark,Phosphor,import { Star } from '@phosphor-icons/react',<Star size={20} weight="regular" />,Star rating favorite,Outline
|
||||
74,Social,thumbs-up,like approve agree positive,Phosphor,import { ThumbsUp } from '@phosphor-icons/react',<ThumbsUp size={20} weight="regular" />,Like approve thumb,Outline
|
||||
75,Social,thumbs-down,dislike disapprove disagree negative,Phosphor,import { ThumbsDown } from '@phosphor-icons/react',<ThumbsDown size={20} weight="regular" />,Dislike disapprove,Outline
|
||||
76,Social,bookmark,save later favorite mark,Phosphor,import { Bookmark } from '@phosphor-icons/react',<Bookmark size={20} weight="regular" />,Bookmark save,Outline
|
||||
77,Social,flag,report mark important highlight,Phosphor,import { Flag } from '@phosphor-icons/react',<Flag size={20} weight="regular" />,Flag report,Outline
|
||||
78,Device,device-mobile,mobile phone device touch,Phosphor,import { DeviceMobile } from '@phosphor-icons/react',<DeviceMobile size={20} weight="regular" />,Mobile smartphone,Outline
|
||||
79,Device,device-tablet,ipad device touch screen,Phosphor,import { DeviceTablet } from '@phosphor-icons/react',<DeviceTablet size={20} weight="regular" />,Tablet device,Outline
|
||||
80,Device,monitor,desktop screen computer display,Phosphor,import { Monitor } from '@phosphor-icons/react',<Monitor size={20} weight="regular" />,Desktop monitor,Outline
|
||||
81,Device,laptop,notebook computer portable device,Phosphor,import { Laptop } from '@phosphor-icons/react',<Laptop size={20} weight="regular" />,Laptop computer,Outline
|
||||
82,Device,printer,print document output paper,Phosphor,import { Printer } from '@phosphor-icons/react',<Printer size={20} weight="regular" />,Printer print,Outline
|
||||
83,Security,lock,secure password protected private,Phosphor,import { Lock } from '@phosphor-icons/react',<Lock size={20} weight="regular" />,Lock secure,Outline
|
||||
84,Security,lock-open,open access unsecure public,Phosphor,import { LockOpen } from '@phosphor-icons/react',<LockOpen size={20} weight="regular" />,Unlock open,Outline
|
||||
85,Security,shield,protection security safe guard,Phosphor,import { Shield } from '@phosphor-icons/react',<Shield size={20} weight="regular" />,Shield protection,Outline
|
||||
86,Security,key,password access unlock login,Phosphor,import { Key } from '@phosphor-icons/react',<Key size={20} weight="regular" />,Key password,Outline
|
||||
87,Security,eye,view show visible password,Phosphor,import { Eye } from '@phosphor-icons/react',<Eye size={20} weight="regular" />,Show password view,Outline
|
||||
88,Security,eye-slash,hide invisible password hidden,Phosphor,import { EyeSlash } from '@phosphor-icons/react',<EyeSlash size={20} weight="regular" />,Hide password,Outline
|
||||
89,Location,map-pin,location marker place address,Phosphor,import { MapPin } from '@phosphor-icons/react',<MapPin size={20} weight="regular" />,Location pin marker,Outline
|
||||
90,Location,map,directions navigate geography location,Phosphor,import { Map } from '@phosphor-icons/react',<Map size={20} weight="regular" />,Map directions,Outline
|
||||
91,Location,compass,compass direction pointer arrow,Phosphor,import { Compass } from '@phosphor-icons/react',<Compass size={20} weight="regular" />,Navigation compass,Outline
|
||||
92,Location,globe,world international global web,Phosphor,import { Globe } from '@phosphor-icons/react',<Globe size={20} weight="regular" />,Globe world,Outline
|
||||
93,Time,calendar,date schedule event appointment,Phosphor,import { Calendar } from '@phosphor-icons/react',<Calendar size={20} weight="regular" />,Calendar date,Outline
|
||||
94,Time,arrows-clockwise,reload sync update refresh,Phosphor,import { ArrowsClockwise } from '@phosphor-icons/react',<ArrowsClockwise size={20} weight="regular" />,Refresh reload,Outline
|
||||
95,Time,arrow-counter-clockwise,undo back revert history,Phosphor,import { ArrowCounterClockwise } from '@phosphor-icons/react',<ArrowCounterClockwise size={20} weight="regular" />,Undo revert,Outline
|
||||
96,Time,arrow-clockwise,redo forward repeat history,Phosphor,import { ArrowClockwise } from '@phosphor-icons/react',<ArrowClockwise size={20} weight="regular" />,Redo forward,Outline
|
||||
97,Development,code,develop programming syntax html,Phosphor,import { Code } from '@phosphor-icons/react',<Code size={20} weight="regular" />,Code development,Outline
|
||||
98,Development,terminal,console cli command shell,Phosphor,import { Terminal } from '@phosphor-icons/react',<Terminal size={20} weight="regular" />,Terminal console,Outline
|
||||
99,Development,git-branch,version control branch merge,Phosphor,import { GitBranch } from '@phosphor-icons/react',<GitBranch size={20} weight="regular" />,Git branch,Outline
|
||||
100,Development,github-logo,repository code open source,Phosphor,import { GithubLogo } from '@phosphor-icons/react',<GithubLogo size={20} weight="regular" />,GitHub repository,Outline
|
||||
101,Style Config,bold-typography-icon-system,"bold typography, editorial, mono label, phosphor, weight regular, minimal, icon+label required, size 20–32",Phosphor (react-native),"import { ArrowRight } from 'phosphor-react-native'","<ArrowRight size={20} weight=""regular"" color={colors.accent} />","Bold Typography Mobile style: weight=""regular"". Size 20px for UI controls, 32px for feature anchors. Icons MUST be paired with a Mono-stack text label (JetBrains Mono). Standalone icons only allowed for standard navigation (e.g., Back arrow). Accent color #FF3D00 only.",Outline
|
||||
102,Style Config,cyberpunk-icon-system,"cyberpunk, neon, glow, hud, phosphor, weight regular, accent glow, dark, angular, react native",Phosphor (react-native),"import { Lightning } from 'phosphor-react-native'","<Lightning size={24} weight=""regular"" color={colors.accent} />","Cyberpunk Mobile HUD style: weight=""regular"", color={colors.accent} (#00FF88 Matrix Green). Wrap every icon in a View with shadowColor: colors.accent / shadowOpacity: 0.6 / shadowRadius: 8 to simulate neon glow. Use borderRadius: 0 on wrapper. Avoid rounded icon containers. Always pair icon with data label in JetBrains Mono.",Outline
|
||||
103,Style Config,academia-icon-system,"academia, library, brass, ornate, phosphor, weight thin, muted warm, scholarly, mobile",Phosphor (react-native),"import { BookOpen } from 'phosphor-react-native'","<BookOpen size={22} weight=""thin"" color={colors.brass} />","Academia (Scholarly Mobile) style: weight=""thin"" (thin engraved feel), color={colors.brass} (#C9A962). No sharp geometric or tech-inspired icons. Prefer book, scroll, key, quill-type icon metaphors. Wrap in circular View with 1px brass border. Avoid neon or saturated colored icons. All icon-only navigation must have an accessibilityLabel.",Outline
|
||||
104,Style Config,web3-bitcoin-icon-system,"web3, bitcoin, defi, crypto, neon orange, holographic, blurview, phosphor, glow, fintech mobile",Phosphor (react-native),"import { TrendUp } from 'phosphor-react-native'","<TrendUp size={24} weight=""regular"" color={colors.bitcoinOrange} />","Bitcoin DeFi Mobile style: weight=""regular"", color={colors.bitcoinOrange} (#F7931A). Wrap icons in circular BlurView (intensity: 20) with 1px borderColor: '#F7931A' border (Holographic Node effect). shadowColor: '#F7931A' / shadowOpacity: 0.4 / shadowRadius: 8. Prefer finance/data icons (TrendUp, Wallet, Shield, Layers). All data icons use JetBrains Mono label.",Outline
|
||||
105,Guideline,icon-fallback-rules,"icon fallback, phosphor, heroicons, any icon, extended set","Phosphor (primary) + Heroicons (fallback)","Primary: import { IconName } from '@phosphor-icons/react'. Fallback: import { IconName } from '@heroicons/react/24/outline' or '@heroicons/react/24/solid'.","当默认列表中没有合适图标时：优先继续从 Phosphor 中选择任何语义更贴切的图标（不必局限于本表列出的图标）。若 Phosphor 也无合适图标，可以改用 Heroicons，并在 UI 代码中保持风格统一（线性或填充、圆角程度、笔画粗细等）。","Icon library strategy and fallback rules",Outline
|
||||
|
Can't render this file because it contains an unexpected character in line 2 and column 134.
|
|
|
@ -1,35 +0,0 @@
|
|||
No,Pattern Name,Keywords,Section Order,Primary CTA Placement,Color Strategy,Recommended Effects,Conversion Optimization
|
||||
1,Hero + Features + CTA,"hero, hero-centric, hero-centric design, features, feature-rich, feature-rich showcase, cta, call-to-action","1. Hero with headline/image, 2. Value prop, 3. Key features (3-5), 4. CTA section, 5. Footer",Hero (sticky) + Bottom,Hero: Brand primary or vibrant. Features: Card bg #FAFAFA. CTA: Contrasting accent color,"Hero parallax, feature card hover lift, CTA glow on hover",Deep CTA placement. Use contrasting color (at least 7:1 contrast ratio). Sticky navbar CTA.
|
||||
2,Hero + Testimonials + CTA,"hero, testimonials, social-proof, social-proof-focused, social proof focused, trust, reviews, cta","1. Hero, 2. Problem statement, 3. Solution overview, 4. Testimonials carousel, 5. CTA",Hero (sticky) + Post-testimonials,"Hero: Brand color. Testimonials: Light bg #F5F5F5. Quotes: Italic, muted color #666. CTA: Vibrant","Testimonial carousel slide animations, quote marks animations, avatar fade-in",Social proof before CTA. Use 3-5 testimonials. Include photo + name + role. CTA after social proof.
|
||||
3,Product Demo + Features,"demo, product-demo, features, showcase, interactive, interactive-product-demo, interactive product demo","1. Hero, 2. Product video/mockup (center), 3. Feature breakdown per section, 4. Comparison (optional), 5. CTA",Video center + CTA right/bottom,Video surround: Brand color overlay. Features: Icon color #0080FF. Text: Dark #222,"Video play button pulse, feature scroll reveals, demo interaction highlights",Embedded product demo increases engagement. Use interactive mockup if possible. Auto-play video muted.
|
||||
4,Minimal Single Column,"minimal, simple, direct, minimal & direct, minimal-direct, single-column, clean","1. Hero headline, 2. Short description, 3. Benefit bullets (3 max), 4. CTA, 5. Footer","Center, large CTA button",Minimalist: Brand + white #FFFFFF + accent. Buttons: High contrast 7:1+. Text: Black/Dark grey,Minimal hover effects. Smooth scroll. CTA scale on hover (subtle),Single CTA focus. Large typography. Lots of whitespace. No nav clutter. Mobile-first.
|
||||
5,Funnel (3-Step Conversion),"funnel, conversion, conversion-optimized, conversion optimized, steps, wizard, onboarding","1. Hero, 2. Step 1 (problem), 3. Step 2 (solution), 4. Step 3 (action), 5. CTA progression",Each step: mini-CTA. Final: main CTA,"Step colors: 1 (Red/Problem), 2 (Orange/Process), 3 (Green/Solution). CTA: Brand color","Step number animations, progress bar fill, step transitions smooth scroll",Progressive disclosure. Show only essential info per step. Use progress indicators. Multiple CTAs.
|
||||
6,Comparison Table + CTA,"comparison, table, compare, versus, cta","1. Hero, 2. Problem intro, 3. Comparison table (product vs competitors), 4. Pricing (optional), 5. CTA",Table: Right column. CTA: Below table,Table: Alternating rows (white/light grey). Your product: Highlight #FFFACD (light yellow) or green. Text: Dark,"Table row hover highlight, price toggle animations, feature checkmark animations",Use comparison to show unique value. Highlight your product row. Include 'free trial' in pricing row.
|
||||
7,Lead Magnet + Form,"lead, form, signup, capture, email, magnet","1. Hero (benefit headline), 2. Lead magnet preview (ebook cover, checklist, etc), 3. Form (minimal fields), 4. CTA submit",Form CTA: Submit button,Lead magnet: Professional design. Form: Clean white bg. Inputs: Light border #CCCCCC. CTA: Brand color,"Form focus state animations, input validation animations, success confirmation animation",Form fields ≤ 3 for best conversion. Offer valuable lead magnet preview. Show form submission progress.
|
||||
8,Pricing Page + CTA,"pricing, plans, tiers, comparison, cta","1. Hero (pricing headline), 2. Price comparison cards, 3. Feature comparison table, 4. FAQ section, 5. Final CTA",Each card: CTA button. Sticky CTA in nav,"Free: Grey, Starter: Blue, Pro: Green/Gold, Enterprise: Dark. Cards: 1px border, shadow","Price toggle animation (monthly/yearly), card comparison highlight, FAQ accordion open/close",Recommend starter plan (pre-select/highlight). Show annual discount (20-30%). Use FAQs to address concerns.
|
||||
9,Video-First Hero,"video, hero, media, visual, engaging","1. Hero with video background, 2. Key features overlay, 3. Benefits section, 4. CTA",Overlay on video (center/bottom) + Bottom section,Dark overlay 60% on video. Brand accent for CTA. White text on dark.,"Video autoplay muted, parallax scroll, text fade-in on scroll",86% higher engagement with video. Add captions for accessibility. Compress video for performance.
|
||||
10,Scroll-Triggered Storytelling,"storytelling, scroll, narrative, story, immersive","1. Intro hook, 2. Chapter 1 (problem), 3. Chapter 2 (journey), 4. Chapter 3 (solution), 5. Climax CTA",End of each chapter (mini) + Final climax CTA,Progressive reveal. Each chapter has distinct color. Building intensity.,"ScrollTrigger animations, parallax layers, progressive disclosure, chapter transitions",Narrative increases time-on-page 3x. Use progress indicator. Mobile: simplify animations.
|
||||
11,AI Personalization Landing,"ai, personalization, smart, recommendation, dynamic","1. Dynamic hero (personalized), 2. Relevant features, 3. Tailored testimonials, 4. Smart CTA",Context-aware placement based on user segment,Adaptive based on user data. A/B test color variations per segment.,"Dynamic content swap, fade transitions, personalized product recommendations",20%+ conversion with personalization. Requires analytics integration. Fallback for new users.
|
||||
12,Waitlist/Coming Soon,"waitlist, coming-soon, launch, early-access, notify","1. Hero with countdown, 2. Product teaser/preview, 3. Email capture form, 4. Social proof (waitlist count)",Email form prominent (above fold) + Sticky form on scroll,Anticipation: Dark + accent highlights. Countdown in brand color. Urgency indicators.,"Countdown timer animation, email validation feedback, success confetti, social share buttons",Scarcity + exclusivity. Show waitlist count. Early access benefits. Referral program.
|
||||
13,Comparison Table Focus,"comparison, table, versus, compare, features","1. Hero (problem statement), 2. Comparison matrix (you vs competitors), 3. Feature deep-dive, 4. Winner CTA",After comparison table (highlighted row) + Bottom,Your product column highlighted (accent bg or green). Competitors neutral. Checkmarks green.,"Table row hover highlight, feature checkmark animations, sticky comparison header",Show value vs competitors. 35% higher conversion. Be factual. Include pricing if favorable.
|
||||
14,Pricing-Focused Landing,"pricing, price, cost, plans, subscription","1. Hero (value proposition), 2. Pricing cards (3 tiers), 3. Feature comparison, 4. FAQ, 5. Final CTA",Each pricing card + Sticky CTA in nav + Bottom,Popular plan highlighted (brand color border/bg). Free: grey. Enterprise: dark/premium.,"Price toggle monthly/annual animation, card hover lift, FAQ accordion smooth open",Annual discount 20-30%. Recommend mid-tier (most popular badge). Address objections in FAQ.
|
||||
15,App Store Style Landing,"app, mobile, download, store, install","1. Hero with device mockup, 2. Screenshots carousel, 3. Features with icons, 4. Reviews/ratings, 5. Download CTAs",Download buttons prominent (App Store + Play Store) throughout,Dark/light matching app store feel. Star ratings in gold. Screenshots with device frames.,"Device mockup rotations, screenshot slider, star rating animations, download button pulse",Show real screenshots. Include ratings (4.5+ stars). QR code for mobile. Platform-specific CTAs.
|
||||
16,FAQ/Documentation Landing,"faq, documentation, help, support, questions, faq/documentation, knowledge base","1. Hero with search bar, 2. Popular categories, 3. FAQ accordion, 4. Contact/support CTA",Search bar prominent + Contact CTA for unresolved questions,"Clean, high readability. Minimal color. Category icons in brand color. Success green for resolved.","Search autocomplete, smooth accordion open/close, category hover, helpful feedback buttons",Reduce support tickets. Track search analytics. Show related articles. Contact escalation path.
|
||||
17,Immersive/Interactive Experience,"immersive, interactive, experience, 3d, animation, immersive/interactive experience","1. Full-screen interactive element, 2. Guided product tour, 3. Key benefits revealed, 4. CTA after completion",After interaction complete + Skip option for impatient users,Immersive experience colors. Dark background for focus. Highlight interactive elements.,"WebGL, 3D interactions, gamification elements, progress indicators, reward animations",40% higher engagement. Performance trade-off. Provide skip option. Mobile fallback essential.
|
||||
18,Event/Conference Landing,"event, conference, meetup, registration, schedule, hero-centric design, hero-centric","1. Hero (date/location/countdown), 2. Speakers grid, 3. Agenda/schedule, 4. Sponsors, 5. Register CTA",Register CTA sticky + After speakers + Bottom,Urgency colors (countdown). Event branding. Speaker cards professional. Sponsor logos neutral.,"Countdown timer, speaker hover cards with bio, agenda tabs, early bird countdown",Early bird pricing with deadline. Social proof (past attendees). Speaker credibility. Multi-ticket discounts.
|
||||
19,Product Review/Ratings Focused,"reviews, ratings, testimonials, social-proof, social-proof-focused, stars","1. Hero (product + aggregate rating), 2. Rating breakdown, 3. Individual reviews, 4. Buy/CTA",After reviews summary + Buy button alongside reviews,Trust colors. Star ratings gold. Verified badge green. Review sentiment colors.,"Star fill animations, review filtering, helpful vote interactions, photo lightbox",User-generated content builds trust. Show verified purchases. Filter by rating. Respond to negative reviews.
|
||||
20,Community/Forum Landing,"community, forum, social, members, discussion","1. Hero (community value prop), 2. Popular topics/categories, 3. Active members showcase, 4. Join CTA",Join button prominent + After member showcase,"Warm, welcoming. Member photos add humanity. Topic badges in brand colors. Activity indicators green.","Member avatars animation, activity feed live updates, topic hover previews, join success celebration","Show active community (member count, posts today). Highlight benefits. Preview content. Easy onboarding."
|
||||
21,Before-After Transformation,"before-after, transformation, results, comparison","1. Hero (problem state), 2. Transformation slider/comparison, 3. How it works, 4. Results CTA",After transformation reveal + Bottom,Contrast: muted/grey (before) vs vibrant/colorful (after). Success green for results.,"Slider comparison interaction, before/after reveal animations, result counters, testimonial videos",Visual proof of value. 45% higher conversion. Real results. Specific metrics. Guarantee offer.
|
||||
22,Marketplace / Directory,"marketplace, directory, search, listing","1. Hero (Search focused), 2. Categories, 3. Featured Listings, 4. Trust/Safety, 5. CTA (Become a host/seller)",Hero Search Bar + Navbar 'List your item',"Search: High contrast. Categories: Visual icons. Trust: Blue/Green.","Search autocomplete animation, map hover pins, card carousel","Search bar is the CTA. Reduce friction to search. Popular searches suggestions."
|
||||
23,Newsletter / Content First,"newsletter, content, writer, blog, subscribe, minimal & direct, minimal-direct","1. Hero (Value Prop + Form), 2. Recent Issues/Archives, 3. Social Proof (Subscriber count), 4. About Author",Hero inline form + Sticky header form,"Minimalist. Paper-like background. Text focus. Accent color for Subscribe.","Text highlight animations, typewriter effect, subtle fade-in","Single field form (Email only). Show 'Join X, 000 readers'. Read sample link."
|
||||
24,Webinar Registration,"webinar, registration, event, training, live","1. Hero (Topic + Timer + Form), 2. What you'll learn, 3. Speaker Bio, 4. Urgency/Bonuses, 5. Form (again)",Hero (Right side form) + Bottom anchor,"Urgency: Red/Orange. Professional: Blue/Navy. Form: High contrast white.","Countdown timer, speaker avatar float, urgent ticker","Limited seats logic. 'Live' indicator. Auto-fill timezone."
|
||||
25,Enterprise Gateway,"enterprise, corporate, gateway, solutions, portal, trust, authority, trust & authority","1. Hero (Video/Mission), 2. Solutions by Industry, 3. Solutions by Role, 4. Client Logos, 5. Contact Sales",Contact Sales (Primary) + Login (Secondary),"Corporate: Navy/Grey. High integrity. Conservative accents.","Slow video background, logo carousel, tab switching for industries","Path selection (I am a...). Mega menu navigation. Trust signals prominent."
|
||||
26,Portfolio Grid,"portfolio, grid, showcase, gallery, masonry, portfolio grid + visuals","1. Hero (Name/Role), 2. Project Grid (Masonry), 3. About/Philosophy, 4. Contact",Project Card Hover + Footer Contact,"Neutral background (let work shine). Text: Black/White. Accent: Minimal.","Image lazy load reveal, hover overlay info, lightbox view","Visuals first. Filter by category. Fast loading essential."
|
||||
27,Horizontal Scroll Journey,"horizontal, scroll, journey, gallery, storytelling, panoramic, storytelling-driven","1. Intro (Vertical), 2. The Journey (Horizontal Track), 3. Detail Reveal, 4. Vertical Footer",Floating Sticky CTA or End of Horizontal Track,Continuous palette transition. Chapter colors. Progress bar #000000.,"Scroll-jacking (careful), parallax layers, horizontal slide, progress indicator","Immersive product discovery. High engagement. Keep navigation visible."
|
||||
28,Bento Grid Showcase,"bento, grid, features, modular, apple-style, showcase, feature-rich showcase","1. Hero, 2. Bento Grid (Key Features), 3. Detail Cards, 4. Tech Specs, 5. CTA",Floating Action Button or Bottom of Grid,"Card backgrounds: #F5F5F7 or Glass. Icons: Vibrant brand colors. Text: Dark.","Hover card scale (1.02), video inside cards, tilt effect, staggered reveal","Scannable value props. High information density without clutter. Mobile stack."
|
||||
29,Interactive 3D Configurator,"3d, configurator, customizer, interactive, product, interactive product demo","1. Hero (Configurator), 2. Feature Highlight (synced), 3. Price/Specs, 4. Purchase",Inside Configurator UI + Sticky Bottom Bar,"Neutral studio background. Product: Realistic materials. UI: Minimal overlay.","Real-time rendering, material swap animation, camera rotate/zoom, light reflection","Increases ownership feeling. 360 view reduces return rates. Direct add-to-cart."
|
||||
30,AI-Driven Dynamic Landing,"ai, dynamic, personalized, adaptive, generative","1. Prompt/Input Hero, 2. Generated Result Preview, 3. How it Works, 4. Value Prop","Input Field (Hero) + 'Try it' Buttons","Adaptive to user input. Dark mode for compute feel. Neon accents.","Typing text effects, shimmering generation loaders, morphing layouts","Immediate value demonstration. 'Show, don't tell'. Low friction start."
|
||||
31,Feature-Rich Showcase,"feature-rich, feature-rich showcase, features, showcase, product showcase","1. Hero (value prop), 2. Feature grid/cards (4-6), 3. Use cases or benefits, 4. Social proof or logos, 5. CTA",Hero (sticky) + After features + Bottom,Brand primary + card bg #FAFAFA. Feature icons accent. CTA contrasting.,"Feature card hover lift, scroll reveal, icon micro-interactions","Clear feature hierarchy. One key message per card. Strong CTA repetition."
|
||||
32,Hero-Centric Design,"hero-centric, hero-centric design, hero-first, hero above fold","1. Full-bleed Hero (headline + visual), 2. Single value prop strip, 3. Key benefit or proof, 4. Primary CTA",Hero dominant (center/bottom) + Sticky nav CTA,Hero: High-impact visual. Minimal text. CTA 7:1 contrast.,"Hero parallax or video, CTA pulse on scroll, minimal chrome","One primary CTA. Hero is 60-80% above fold. Mobile: same hierarchy."
|
||||
33,Trust & Authority + Conversion,"trust & authority, trust, authority, conversion, credibility, enterprise","1. Hero (mission/credibility), 2. Proof (logos, certs, stats), 3. Solution overview, 4. Clear CTA path",Contact Sales / Get Quote (primary) + Nav,"Navy/Grey corporate. Trust blue. Accent for CTA only.","Logo carousel, stat counters, testimonial strip","Security badges. Case studies. Transparent pricing. Low-friction form."
|
||||
34,Real-Time / Operations Landing,"real-time, real-time monitor, operations, dashboard, telemetry, live data","1. Hero (product + live preview or status), 2. Key metrics/indicators, 3. How it works, 4. CTA (Start trial / Contact)","Primary CTA in nav + After metrics",Dark or neutral. Status colors (green/amber/red). Data-dense but scannable.,"Live data ticker, status pulse, minimal decoration","For ops/security/iot products. Demo or sandbox link. Trust signals."
|
||||
|
|
|
@ -1,162 +0,0 @@
|
|||
No,Product Type,Keywords,Primary Style Recommendation,Secondary Styles,Landing Page Pattern,Dashboard Style (if applicable),Color Palette Focus,Key Considerations
|
||||
1,SaaS (General),"app, b2b, cloud, general, saas, software, subscription",Glassmorphism + Flat Design,"Soft UI Evolution, Minimalism",Hero + Features + CTA,Data-Dense + Real-Time Monitoring,Trust blue + accent contrast,Balance modern feel with clarity. Focus on CTAs.
|
||||
2,Micro SaaS,"app, b2b, cloud, indie, micro, micro-saas, niche, saas, small, software, solo, subscription",Flat Design + Vibrant & Block,"Motion-Driven, Micro-interactions",Minimal & Direct + Demo,Executive Dashboard,Vibrant primary + white space,"Keep simple, show product quickly. Speed is key."
|
||||
3,E-commerce,"buy, commerce, e, ecommerce, products, retail, sell, shop, store",Vibrant & Block-based,"Aurora UI, Motion-Driven",Feature-Rich Showcase,Sales Intelligence Dashboard,Brand primary + success green,Engagement & conversions. High visual hierarchy.
|
||||
4,E-commerce Luxury,"buy, commerce, e, ecommerce, elegant, exclusive, high-end, luxury, premium, products, retail, sell, shop, store",Liquid Glass + Glassmorphism,"3D & Hyperrealism, Aurora UI",Feature-Rich Showcase,Sales Intelligence Dashboard,Premium colors + minimal accent,Elegance & sophistication. Premium materials.
|
||||
5,B2B Service,"appointment, b, b2b, booking, business, consultation, corporate, enterprise, service",Trust & Authority + Minimal,"Feature-Rich, Conversion-Optimized",Feature-Rich Showcase,Sales Intelligence Dashboard,Professional blue + neutral grey,Credibility essential. Clear ROI messaging.
|
||||
6,Financial Dashboard,"admin, analytics, dashboard, data, financial, panel",Dark Mode (OLED) + Data-Dense,"Minimalism, Accessible & Ethical",N/A - Dashboard focused,Financial Dashboard,Dark bg + red/green alerts + trust blue,"High contrast, real-time updates, accuracy paramount."
|
||||
7,Analytics Dashboard,"admin, analytics, dashboard, data, panel",Data-Dense + Heat Map & Heatmap,"Minimalism, Dark Mode (OLED)",N/A - Analytics focused,Drill-Down Analytics + Comparative,Cool→Hot gradients + neutral grey,Clarity > aesthetics. Color-coded data priority.
|
||||
8,Healthcare App,"app, clinic, health, healthcare, medical, patient",Neumorphism + Accessible & Ethical,"Soft UI Evolution, Claymorphism (for patients)",Social Proof-Focused,User Behavior Analytics,Calm blue + health green + trust,Accessibility mandatory. Calming aesthetic.
|
||||
9,Educational App,"app, course, education, educational, learning, school, training",Claymorphism + Micro-interactions,"Vibrant & Block-based, Flat Design",Storytelling-Driven,User Behavior Analytics,Playful colors + clear hierarchy,Engagement & ease of use. Age-appropriate design.
|
||||
10,Creative Agency,"agency, creative, design, marketing, studio",Brutalism + Motion-Driven,"Retro-Futurism, Storytelling-Driven",Storytelling-Driven,N/A - Portfolio focused,Bold primaries + artistic freedom,Differentiation key. Wow-factor necessary.
|
||||
11,Portfolio/Personal,"creative, personal, portfolio, projects, showcase, work",Motion-Driven + Minimalism,"Brutalism, Aurora UI",Storytelling-Driven,N/A - Personal branding,Brand primary + artistic interpretation,Showcase work. Personality shine through.
|
||||
12,Gaming,"entertainment, esports, game, gaming, play",3D & Hyperrealism + Retro-Futurism,"Motion-Driven, Vibrant & Block",Feature-Rich Showcase,N/A - Game focused,Vibrant + neon + immersive colors,Immersion priority. Performance critical.
|
||||
13,Government/Public Service,"appointment, booking, consultation, government, public, service",Accessible & Ethical + Minimalism,"Flat Design, Inclusive Design",Minimal & Direct,Executive Dashboard,Professional blue + high contrast,WCAG AAA mandatory. Trust paramount.
|
||||
14,Fintech/Crypto,"banking, blockchain, crypto, defi, finance, fintech, money, nft, payment, web3",Glassmorphism + Dark Mode (OLED),"Retro-Futurism, Motion-Driven",Conversion-Optimized,Real-Time Monitoring + Predictive,Dark tech colors + trust + vibrant accents,Security perception. Real-time data critical.
|
||||
15,Social Media App,"app, community, content, entertainment, media, network, sharing, social, streaming, users, video",Vibrant & Block-based + Motion-Driven,"Aurora UI, Micro-interactions",Feature-Rich Showcase,User Behavior Analytics,Vibrant + engagement colors,Engagement & retention. Addictive design ethics.
|
||||
16,Productivity Tool,"collaboration, productivity, project, task, tool, workflow",Flat Design + Micro-interactions,"Minimalism, Soft UI Evolution",Interactive Product Demo,Drill-Down Analytics,Clear hierarchy + functional colors,Ease of use. Speed & efficiency focus.
|
||||
17,Design System/Component Library,"component, design, library, system",Minimalism + Accessible & Ethical,"Flat Design, Zero Interface",Feature-Rich Showcase,N/A - Dev focused,Clear hierarchy + code-like structure,Consistency. Developer-first approach.
|
||||
18,AI/Chatbot Platform,"ai, artificial-intelligence, automation, chatbot, machine-learning, ml, platform",AI-Native UI + Minimalism,"Zero Interface, Glassmorphism",Interactive Product Demo,AI/ML Analytics Dashboard,Neutral + AI Purple (#6366F1),Conversational UI. Streaming text. Context awareness. Minimal chrome.
|
||||
19,NFT/Web3 Platform,"nft, platform, web",Cyberpunk UI + Glassmorphism,"Aurora UI, 3D & Hyperrealism",Feature-Rich Showcase,Crypto/Blockchain Dashboard,Dark + Neon + Gold (#FFD700),Wallet integration. Transaction feedback. Gas fees display. Dark mode essential.
|
||||
20,Creator Economy Platform,"creator, economy, platform",Vibrant & Block-based + Bento Box Grid,"Motion-Driven, Aurora UI",Social Proof-Focused,User Behavior Analytics,Vibrant + Brand colors,Creator profiles. Monetization display. Engagement metrics. Social proof.
|
||||
21,Remote Work/Collaboration Tool,"collaboration, remote, tool, work",Soft UI Evolution + Minimalism,"Glassmorphism, Micro-interactions",Feature-Rich Showcase,Drill-Down Analytics,Calm Blue + Neutral grey,Real-time collaboration. Status indicators. Video integration. Notification management.
|
||||
22,Mental Health App,"app, health, mental",Neumorphism + Accessible & Ethical,"Claymorphism, Soft UI Evolution",Social Proof-Focused,Healthcare Analytics,Calm Pastels + Trust colors,Calming aesthetics. Privacy-first. Crisis resources. Progress tracking. Accessibility mandatory.
|
||||
23,Pet Tech App,"app, pet, tech",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Storytelling-Driven,User Behavior Analytics,Playful + Warm colors,Pet profiles. Health tracking. Playful UI. Photo galleries. Vet integration.
|
||||
24,Smart Home/IoT Dashboard,"admin, analytics, dashboard, data, home, iot, panel, smart",Glassmorphism + Dark Mode (OLED),"Minimalism, AI-Native UI",Interactive Product Demo,Real-Time Monitoring,Dark + Status indicator colors,Device status. Real-time controls. Energy monitoring. Automation rules. Quick actions.
|
||||
25,EV/Charging Ecosystem,"charging, ecosystem, ev",Minimalism + Aurora UI,"Glassmorphism, Organic Biophilic",Hero-Centric Design,Energy/Utilities Dashboard,Electric Blue (#009CD1) + Green,Charging station maps. Range estimation. Cost calculation. Environmental impact.
|
||||
26,Subscription Box Service,"appointment, booking, box, consultation, membership, plan, recurring, service, subscription",Vibrant & Block-based + Motion-Driven,"Claymorphism, Aurora UI",Feature-Rich Showcase,E-commerce Analytics,Brand + Excitement colors,Unboxing experience. Personalization quiz. Subscription management. Product reveals.
|
||||
27,Podcast Platform,"platform, podcast",Dark Mode (OLED) + Minimalism,"Motion-Driven, Vibrant & Block-based",Storytelling-Driven,Media/Entertainment Dashboard,Dark + Audio waveform accents,Audio player UX. Episode discovery. Creator tools. Analytics for podcasters.
|
||||
28,Dating App,"app, dating",Vibrant & Block-based + Motion-Driven,"Aurora UI, Glassmorphism",Social Proof-Focused,User Behavior Analytics,Warm + Romantic (Pink/Red gradients),Profile cards. Swipe interactions. Match animations. Safety features. Video chat.
|
||||
29,Micro-Credentials/Badges Platform,"badges, credentials, micro, platform",Minimalism + Flat Design,"Accessible & Ethical, Swiss Modernism 2.0",Trust & Authority,Education Dashboard,Trust Blue + Gold (#FFD700),Credential verification. Badge display. Progress tracking. Issuer trust. LinkedIn integration.
|
||||
30,Knowledge Base/Documentation,"base, documentation, knowledge",Minimalism + Accessible & Ethical,"Swiss Modernism 2.0, Flat Design",FAQ/Documentation,N/A - Documentation focused,Clean hierarchy + minimal color,Search-first. Clear navigation. Code highlighting. Version switching. Feedback system.
|
||||
31,Hyperlocal Services,"appointment, booking, consultation, hyperlocal, service, services",Minimalism + Vibrant & Block-based,"Micro-interactions, Flat Design",Conversion-Optimized,Drill-Down Analytics + Map,Location markers + Trust colors,Map integration. Service categories. Provider profiles. Booking system. Reviews.
|
||||
32,Beauty/Spa/Wellness Service,"appointment, beauty, booking, consultation, service, spa, wellness",Soft UI Evolution + Neumorphism,"Glassmorphism, Minimalism",Hero-Centric Design + Social Proof,User Behavior Analytics,Soft pastels (Pink #FFB6C1 Sage #90EE90) + Cream + Gold accents,Calming aesthetic. Booking system. Service menu. Before/after gallery. Testimonials. Relaxing imagery.
|
||||
33,Luxury/Premium Brand,"brand, elegant, exclusive, high-end, luxury, premium",Liquid Glass + Glassmorphism,"Minimalism, 3D & Hyperrealism",Storytelling-Driven + Feature-Rich,Sales Intelligence Dashboard,Black + Gold (#FFD700) + White + Minimal accent,Elegance paramount. Premium imagery. Storytelling. High-quality visuals. Exclusive feel.
|
||||
34,Restaurant/Food Service,"appointment, booking, consultation, delivery, food, menu, order, restaurant, service",Vibrant & Block-based + Motion-Driven,"Claymorphism, Flat Design",Hero-Centric Design + Conversion,N/A - Booking focused,Warm colors (Orange Red Brown) + appetizing imagery,Menu display. Online ordering. Reservation system. Food photography. Location/hours prominent.
|
||||
35,Fitness/Gym App,"app, exercise, fitness, gym, health, workout",Vibrant & Block-based + Dark Mode (OLED),"Motion-Driven, Neumorphism",Feature-Rich Showcase,User Behavior Analytics,Energetic (Orange #FF6B35 Electric Blue) + Dark bg,Progress tracking. Workout plans. Community features. Achievements. Motivational design.
|
||||
36,Real Estate/Property,"buy, estate, housing, property, real, real-estate, rent",Glassmorphism + Minimalism,"Motion-Driven, 3D & Hyperrealism",Hero-Centric Design + Feature-Rich,Sales Intelligence Dashboard,Trust Blue (#0077B6) + Gold accents + White,Property listings. Virtual tours. Map integration. Agent profiles. Mortgage calculator. High-quality imagery.
|
||||
37,Travel/Tourism Agency,"agency, booking, creative, design, flight, hotel, marketing, studio, tourism, travel, vacation",Aurora UI + Motion-Driven,"Vibrant & Block-based, Glassmorphism",Storytelling-Driven + Hero-Centric,Booking Analytics,Vibrant destination colors + Sky Blue + Warm accents,Destination showcase. Booking system. Itinerary builder. Reviews. Inspiration galleries. Mobile-first.
|
||||
38,Hotel/Hospitality,"hospitality, hotel",Liquid Glass + Minimalism,"Glassmorphism, Soft UI Evolution",Hero-Centric Design + Social Proof,Revenue Management Dashboard,Warm neutrals + Gold (#D4AF37) + Brand accent,Room booking. Amenities showcase. Location maps. Guest reviews. Seasonal pricing. Luxury imagery.
|
||||
39,Wedding/Event Planning,"conference, event, meetup, planning, registration, ticket, wedding",Soft UI Evolution + Aurora UI,"Glassmorphism, Motion-Driven",Storytelling-Driven + Social Proof,N/A - Planning focused,Soft Pink (#FFD6E0) + Gold + Cream + Sage,Portfolio gallery. Vendor directory. Planning tools. Timeline. Budget tracker. Romantic aesthetic.
|
||||
40,Legal Services,"appointment, attorney, booking, compliance, consultation, contract, law, legal, service, services",Trust & Authority + Minimalism,"Accessible & Ethical, Swiss Modernism 2.0",Trust & Authority + Minimal,Case Management Dashboard,Navy Blue (#1E3A5F) + Gold + White,Credibility paramount. Practice areas. Attorney profiles. Case results. Contact forms. Professional imagery.
|
||||
41,Insurance Platform,"insurance, platform",Trust & Authority + Flat Design,"Accessible & Ethical, Minimalism",Conversion-Optimized + Trust,Claims Analytics Dashboard,Trust Blue (#0066CC) + Green (security) + Neutral,Quote calculator. Policy comparison. Claims process. Trust signals. Clear pricing. Security badges.
|
||||
42,Banking/Traditional Finance,"banking, finance, traditional",Minimalism + Accessible & Ethical,"Trust & Authority, Dark Mode (OLED)",Trust & Authority + Feature-Rich,Financial Dashboard,Navy (#0A1628) + Trust Blue + Gold accents,Security-first. Account overview. Transaction history. Mobile banking. Accessibility critical. Trust paramount.
|
||||
43,Online Course/E-learning,"course, e, learning, online",Claymorphism + Vibrant & Block-based,"Motion-Driven, Flat Design",Feature-Rich Showcase + Social Proof,Education Dashboard,Vibrant learning colors + Progress green,Course catalog. Progress tracking. Video player. Quizzes. Certificates. Community forums. Gamification.
|
||||
44,Non-profit/Charity,"charity, non, profit",Accessible & Ethical + Organic Biophilic,"Minimalism, Storytelling-Driven",Storytelling-Driven + Trust,Donation Analytics Dashboard,Cause-related colors + Trust + Warm,Impact stories. Donation flow. Transparency reports. Volunteer signup. Event calendar. Emotional connection.
|
||||
45,Music Streaming,"music, streaming",Dark Mode (OLED) + Vibrant & Block-based,"Motion-Driven, Aurora UI",Feature-Rich Showcase,Media/Entertainment Dashboard,Dark (#121212) + Vibrant accents + Album art colors,Audio player. Playlist management. Artist pages. Personalization. Social features. Waveform visualizations.
|
||||
46,Video Streaming/OTT,"ott, streaming, video",Dark Mode (OLED) + Motion-Driven,"Glassmorphism, Vibrant & Block-based",Hero-Centric Design + Feature-Rich,Media/Entertainment Dashboard,Dark bg + Content poster colors + Brand accent,Video player. Content discovery. Watchlist. Continue watching. Personalized recommendations. Thumbnail-heavy.
|
||||
47,Job Board/Recruitment,"board, job, recruitment",Flat Design + Minimalism,"Vibrant & Block-based, Accessible & Ethical",Conversion-Optimized + Feature-Rich,HR Analytics Dashboard,Professional Blue + Success Green + Neutral,Job listings. Search/filter. Company profiles. Application tracking. Resume upload. Salary insights.
|
||||
48,Marketplace (P2P),"buyers, listings, marketplace, p, platform, sellers",Vibrant & Block-based + Flat Design,"Micro-interactions, Trust & Authority",Feature-Rich Showcase + Social Proof,E-commerce Analytics,Trust colors + Category colors + Success green,Seller/buyer profiles. Listings. Reviews/ratings. Secure payment. Messaging. Search/filter. Trust badges.
|
||||
49,Logistics/Delivery,"delivery, logistics",Minimalism + Flat Design,"Dark Mode (OLED), Micro-interactions",Feature-Rich Showcase + Conversion,Real-Time Monitoring + Route Analytics,Blue (#2563EB) + Orange (tracking) + Green (delivered),Real-time tracking. Delivery scheduling. Route optimization. Driver management. Status updates. Map integration.
|
||||
50,Agriculture/Farm Tech,"agriculture, farm, tech",Organic Biophilic + Flat Design,"Minimalism, Accessible & Ethical",Feature-Rich Showcase + Trust,IoT Sensor Dashboard,Earth Green (#4A7C23) + Brown + Sky Blue,Crop monitoring. Weather data. IoT sensors. Yield tracking. Market prices. Sustainable imagery.
|
||||
51,Construction/Architecture,"architecture, construction",Minimalism + 3D & Hyperrealism,"Brutalism, Swiss Modernism 2.0",Hero-Centric Design + Feature-Rich,Project Management Dashboard,Grey (#4A4A4A) + Orange (safety) + Blueprint Blue,Project portfolio. 3D renders. Timeline. Material specs. Team collaboration. Blueprint aesthetic.
|
||||
52,Automotive/Car Dealership,"automotive, car, dealership",Motion-Driven + 3D & Hyperrealism,"Dark Mode (OLED), Glassmorphism",Hero-Centric Design + Feature-Rich,Sales Intelligence Dashboard,Brand colors + Metallic accents + Dark/Light,Vehicle showcase. 360° views. Comparison tools. Financing calculator. Test drive booking. High-quality imagery.
|
||||
53,Photography Studio,"photography, studio",Motion-Driven + Minimalism,"Aurora UI, Glassmorphism",Storytelling-Driven + Hero-Centric,N/A - Portfolio focused,Black + White + Minimal accent,Portfolio gallery. Before/after. Service packages. Booking system. Client galleries. Full-bleed imagery.
|
||||
54,Coworking Space,"coworking, space",Vibrant & Block-based + Glassmorphism,"Minimalism, Motion-Driven",Hero-Centric Design + Feature-Rich,Occupancy Dashboard,Energetic colors + Wood tones + Brand accent,Space tour. Membership plans. Booking system. Amenities. Community events. Virtual tour.
|
||||
55,Home Services (Plumber/Electrician),"appointment, booking, consultation, electrician, home, plumber, service, services",Flat Design + Trust & Authority,"Minimalism, Accessible & Ethical",Conversion-Optimized + Trust,Service Analytics,Trust Blue + Safety Orange + Professional grey,Service list. Emergency contact. Booking. Price transparency. Certifications. Local trust signals.
|
||||
56,Childcare/Daycare,"childcare, daycare",Claymorphism + Vibrant & Block-based,"Soft UI Evolution, Accessible & Ethical",Social Proof-Focused + Trust,Parent Dashboard,Playful pastels + Safe colors + Warm accents,Programs. Staff profiles. Safety certifications. Parent portal. Activity updates. Cheerful imagery.
|
||||
57,Senior Care/Elderly,"care, elderly, senior",Accessible & Ethical + Soft UI Evolution,"Minimalism, Neumorphism",Trust & Authority + Social Proof,Healthcare Analytics,Calm Blue + Warm neutrals + Large text,Care services. Staff qualifications. Facility tour. Family portal. Large touch targets. High contrast. Accessibility-first.
|
||||
58,Medical Clinic,"clinic, medical",Accessible & Ethical + Minimalism,"Neumorphism, Trust & Authority",Trust & Authority + Conversion,Healthcare Analytics,Medical Blue (#0077B6) + Trust White + Calm Green,Services. Doctor profiles. Online booking. Patient portal. Insurance info. HIPAA compliant. Trust signals.
|
||||
59,Pharmacy/Drug Store,"drug, pharmacy, store",Flat Design + Accessible & Ethical,"Minimalism, Trust & Authority",Conversion-Optimized + Trust,Inventory Dashboard,Pharmacy Green + Trust Blue + Clean White,Product catalog. Prescription upload. Refill reminders. Health info. Store locator. Safety certifications.
|
||||
60,Dental Practice,"dental, practice",Soft UI Evolution + Minimalism,"Accessible & Ethical, Trust & Authority",Social Proof-Focused + Conversion,Patient Analytics,Fresh Blue + White + Smile Yellow accent,Services. Dentist profiles. Before/after. Online booking. Insurance. Patient testimonials. Friendly imagery.
|
||||
61,Veterinary Clinic,"clinic, veterinary",Claymorphism + Accessible & Ethical,"Soft UI Evolution, Flat Design",Social Proof-Focused + Trust,Pet Health Dashboard,Caring Blue + Pet-friendly colors + Warm accents,Pet services. Vet profiles. Online booking. Pet portal. Emergency info. Friendly animal imagery.
|
||||
62,Florist/Plant Shop,"florist, plant, shop",Organic Biophilic + Vibrant & Block-based,"Aurora UI, Motion-Driven",Hero-Centric Design + Conversion,E-commerce Analytics,Natural Green + Floral pinks/purples + Earth tones,Product catalog. Occasion categories. Delivery scheduling. Care guides. Seasonal collections. Beautiful imagery.
|
||||
63,Bakery/Cafe,"bakery, cafe",Vibrant & Block-based + Soft UI Evolution,"Claymorphism, Motion-Driven",Hero-Centric Design + Conversion,N/A - Order focused,Warm Brown + Cream + Appetizing accents,Menu display. Online ordering. Location/hours. Catering. Seasonal specials. Appetizing photography.
|
||||
64,Brewery/Winery,"brewery, winery",Motion-Driven + Storytelling-Driven,"Dark Mode (OLED), Organic Biophilic",Storytelling-Driven + Hero-Centric,N/A - E-commerce focused,Deep amber/burgundy + Gold + Craft aesthetic,Product showcase. Story/heritage. Tasting notes. Events. Club membership. Artisanal imagery.
|
||||
65,Airline,"airline, aviation, flight, travel, booking, airport, flying",Minimalism + Glassmorphism,"Motion-Driven, Accessible & Ethical",Conversion-Optimized + Feature-Rich,Operations Dashboard,Sky Blue + Brand colors + Trust accents,Flight search. Booking. Check-in. Boarding pass. Loyalty program. Route maps. Mobile-first.
|
||||
66,News/Media Platform,"content, entertainment, media, news, platform, streaming, video",Minimalism + Flat Design,"Dark Mode (OLED), Accessible & Ethical",Hero-Centric Design + Feature-Rich,Media Analytics Dashboard,Brand colors + High contrast + Category colors,Article layout. Breaking news. Categories. Search. Subscription. Mobile reading. Fast loading.
|
||||
67,Magazine/Blog,"articles, blog, content, magazine, posts, writing",Swiss Modernism 2.0 + Motion-Driven,"Minimalism, Aurora UI",Storytelling-Driven + Hero-Centric,Content Analytics,Editorial colors + Brand primary + Clean white,Article showcase. Category navigation. Author profiles. Newsletter signup. Related content. Typography-focused.
|
||||
68,Freelancer Platform,"freelancer, platform",Flat Design + Minimalism,"Vibrant & Block-based, Micro-interactions",Feature-Rich Showcase + Conversion,Marketplace Analytics,Professional Blue + Success Green + Neutral,Profile creation. Portfolio. Skill matching. Messaging. Payment. Reviews. Project management.
|
||||
69,Marketing Agency,"agency, creative, design, marketing, studio",Brutalism + Motion-Driven,"Vibrant & Block-based, Aurora UI",Storytelling-Driven + Feature-Rich,Campaign Analytics,Bold brand colors + Creative freedom,Portfolio. Case studies. Services. Team. Creative showcase. Results-focused. Bold aesthetic.
|
||||
70,Event Management,"conference, event, management, meetup, registration, ticket",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Aurora UI",Hero-Centric Design + Feature-Rich,Event Analytics,Event theme colors + Excitement accents,Event showcase. Registration. Agenda. Speakers. Sponsors. Ticket sales. Countdown timer.
|
||||
71,Membership/Community,"community, membership",Vibrant & Block-based + Soft UI Evolution,"Bento Box Grid, Micro-interactions",Social Proof-Focused + Conversion,Community Analytics,Community brand colors + Engagement accents,Member benefits. Pricing tiers. Community showcase. Events. Member directory. Exclusive content.
|
||||
72,Newsletter Platform,"newsletter, platform",Minimalism + Flat Design,"Swiss Modernism 2.0, Accessible & Ethical",Minimal & Direct + Conversion,Email Analytics,Brand primary + Clean white + CTA accent,Subscribe form. Archive. About. Social proof. Sample content. Simple conversion.
|
||||
73,Digital Products/Downloads,"digital, downloads, products",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Bento Box Grid",Feature-Rich Showcase + Conversion,E-commerce Analytics,Product category colors + Brand + Success green,Product showcase. Preview. Pricing. Instant delivery. License management. Customer reviews.
|
||||
74,Church/Religious Organization,"church, organization, religious",Accessible & Ethical + Soft UI Evolution,"Minimalism, Trust & Authority",Hero-Centric Design + Social Proof,N/A - Community focused,Warm Gold + Deep Purple/Blue + White,Service times. Events. Sermons. Community. Giving. Location. Welcoming imagery.
|
||||
75,Sports Team/Club,"club, sports, team",Vibrant & Block-based + Motion-Driven,"Dark Mode (OLED), 3D & Hyperrealism",Hero-Centric Design + Feature-Rich,Performance Analytics,Team colors + Energetic accents,Schedule. Roster. News. Tickets. Merchandise. Fan engagement. Action imagery.
|
||||
76,Museum/Gallery,"gallery, museum",Minimalism + Motion-Driven,"Swiss Modernism 2.0, 3D & Hyperrealism",Storytelling-Driven + Feature-Rich,Visitor Analytics,Art-appropriate neutrals + Exhibition accents,Exhibitions. Collections. Tickets. Events. Virtual tours. Educational content. Art-focused design.
|
||||
77,Theater/Cinema,"cinema, theater",Dark Mode (OLED) + Motion-Driven,"Vibrant & Block-based, Glassmorphism",Hero-Centric Design + Conversion,Booking Analytics,Dark + Spotlight accents + Gold,Showtimes. Seat selection. Trailers. Coming soon. Membership. Dramatic imagery.
|
||||
78,Language Learning App,"app, language, learning",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Feature-Rich Showcase + Social Proof,Learning Analytics,Playful colors + Progress indicators + Country flags,Lesson structure. Progress tracking. Gamification. Speaking practice. Community. Achievement badges.
|
||||
79,Coding Bootcamp,"bootcamp, coding",Dark Mode (OLED) + Minimalism,"Cyberpunk UI, Flat Design",Feature-Rich Showcase + Social Proof,Student Analytics,Code editor colors + Brand + Success green,Curriculum. Projects. Career outcomes. Alumni. Pricing. Application. Terminal aesthetic.
|
||||
80,Cybersecurity Platform,"cyber, security, platform",Cyberpunk UI + Dark Mode (OLED),"Neubrutalism, Minimal & Direct",Trust & Authority + Real-Time,Real-Time Monitoring + Heat Map,Matrix Green + Deep Black + Terminal feel,Data density. Threat visualization. Dark mode default.
|
||||
81,Developer Tool / IDE,"dev, developer, tool, ide",Dark Mode (OLED) + Minimalism,"Flat Design, Bento Box Grid",Minimal & Direct + Documentation,Real-Time Monitor + Terminal,Dark syntax theme colors + Blue focus,Keyboard shortcuts. Syntax highlighting. Fast performance.
|
||||
82,Biotech / Life Sciences,"biotech, biology, science",Glassmorphism + Clean Science,"Minimalism, Organic Biophilic",Storytelling-Driven + Research,Data-Dense + Predictive,Sterile White + DNA Blue + Life Green,Data accuracy. Cleanliness. Complex data viz.
|
||||
83,Space Tech / Aerospace,"aerospace, space, tech",Holographic / HUD + Dark Mode,"Glassmorphism, 3D & Hyperrealism",Immersive Experience + Hero,Real-Time Monitoring + 3D,Deep Space Black + Star White + Metallic,High-tech feel. Precision. Telemetry data.
|
||||
84,Architecture / Interior,"architecture, design, interior",Exaggerated Minimalism + High Imagery,"Swiss Modernism 2.0, Parallax",Portfolio Grid + Visuals,Project Management + Gallery,Monochrome + Gold Accent + High Imagery,High-res images. Typography. Space.
|
||||
85,Quantum Computing Interface,"quantum, computing, physics, qubit, future, science",Holographic / HUD + Dark Mode,"Glassmorphism, Spatial UI",Immersive/Interactive Experience,3D Spatial Data + Real-Time Monitor,Quantum Blue #00FFFF + Deep Black + Interference patterns,Visualize complexity. Qubit states. Probability clouds. High-tech trust.
|
||||
86,Biohacking / Longevity App,"biohacking, health, longevity, tracking, wellness, science",Biomimetic / Organic 2.0,"Minimalism, Dark Mode (OLED)",Data-Dense + Storytelling,Real-Time Monitor + Biological Data,Cellular Pink/Red + DNA Blue + Clean White,Personal data privacy. Scientific credibility. Biological visualizations.
|
||||
87,Autonomous Drone Fleet Manager,"drone, autonomous, fleet, aerial, logistics, robotics",HUD / Sci-Fi FUI,"Real-Time Monitor, Spatial UI",Real-Time Monitor,Geographic + Real-Time,Tactical Green #00FF00 + Alert Red + Map Dark,Real-time telemetry. 3D spatial awareness. Latency indicators. Safety alerts.
|
||||
88,Generative Art Platform,"art, generative, ai, creative, platform, gallery",Minimalism (Frame) + Gen Z Chaos,"Masonry Grid, Dark Mode",Bento Grid Showcase,Gallery / Portfolio,Neutral #F5F5F5 (Canvas) + User Content,Content is king. Fast loading. Creator attribution. Minting flow.
|
||||
89,Spatial Computing OS / App,"spatial, vr, ar, vision, os, immersive, mixed-reality",Spatial UI (VisionOS),"Glassmorphism, 3D & Hyperrealism",Immersive/Interactive Experience,Spatial Dashboard,Frosted Glass + System Colors + Depth,Gaze/Pinch interaction. Depth hierarchy. Environment awareness.
|
||||
90,Sustainable Energy / Climate Tech,"climate, energy, sustainable, green, tech, carbon",Organic Biophilic + E-Ink / Paper,"Data-Dense, Swiss Modernism",Interactive Demo + Data,Energy/Utilities Dashboard,Earth Green + Sky Blue + Solar Yellow,Data transparency. Impact visualization. Low-carbon web design.
|
||||
91,Personal Finance Tracker,"budget, expense, money, finance, spending, savings, tracker, personal, wallet",Glassmorphism + Dark Mode (OLED),"Minimalism, Flat Design",Interactive Product Demo,Financial Dashboard,Calm blue + success green + alert red + chart accents,Category pie/donut charts. Monthly trend lines. Budget progress bars. Transaction list with swipe actions. Receipt camera. Currency formatting. Recurring entries.
|
||||
92,Chat & Messaging App,"chat, message, messenger, im, realtime, conversation, inbox, dm, whatsapp, telegram",Minimalism + Micro-interactions,"Glassmorphism, Flat Design",Feature-Rich Showcase + Demo,User Behavior Analytics,Brand primary + bubble contrast (sender/receiver) + typing grey,Bubble UI (left/right alignment). Typing indicators. Read receipts (✓✓). Image/file preview. Emoji reactions. Group avatars. Online status dots. Swipe-to-reply.
|
||||
93,Notes & Writing App,"notes, memo, writing, editor, notebook, markdown, journal, notion, obsidian",Minimalism + Flat Design,"Swiss Modernism 2.0, Soft UI Evolution",Minimal & Direct,N/A - Editor focused,Clean white/cream + minimal accent + editor syntax colors,WYSIWYG or Markdown toggle. Folder/tag organization. Full-text search. Cloud sync. Typography-first. Distraction-free zen mode. Slash-command palette.
|
||||
94,Habit Tracker,"habit, streak, routine, daily, tracker, goals, consistency, discipline",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Social Proof-Focused + Demo,User Behavior Analytics,Streak warm (amber/orange) + progress green + motivational accents,Streak calendar heatmap. Daily check-in interaction. Gamification (badges/levels/fire). Reminder push. Progress ring charts. Weekly/monthly stats. Motivational micro-copy.
|
||||
95,Food Delivery / On-Demand,"delivery, food, order, uber-eats, doordash, takeout, on-demand, courier",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Flat Design",Hero-Centric Design + Feature-Rich,Real-Time Monitoring + Map,Appetizing warm (orange/red) + trust blue + map accent,Restaurant cards with ratings. Menu category horizontal scroll. Cart bottom sheet. Real-time map tracking + driver ETA. Order status stepper. Rating post-delivery.
|
||||
96,Ride Hailing / Transportation,"ride, taxi, uber, lyft, transport, carpool, driver, trip, fare",Minimalism + Glassmorphism,"Dark Mode (OLED), Motion-Driven",Conversion-Optimized + Demo,Real-Time Monitoring + Map,Brand primary + map neutral + status indicator colors,Map-centric full-screen UI. Pickup/dropoff pins + route polyline. Driver card (photo/rating/vehicle). Fare estimate. Trip timer. Safety SOS button. Payment sheet.
|
||||
97,Recipe & Cooking App,"recipe, cooking, food, kitchen, cookbook, meal, ingredient, chef",Claymorphism + Vibrant & Block-based,"Soft UI Evolution, Organic Biophilic",Hero-Centric Design + Feature-Rich,N/A - Content focused,Warm food tones (terracotta/sage/cream) + appetizing imagery,Step-by-step with checkable instructions. Ingredient list with serving adjuster. Built-in timer per step. Cooking mode (screen-awake + large text). Save/bookmark. Share.
|
||||
98,Meditation & Mindfulness,"meditation, mindfulness, calm, breathe, wellness, relaxation, sleep, headspace",Neumorphism + Soft UI Evolution,"Aurora UI, Glassmorphism",Storytelling-Driven + Social Proof,User Behavior Analytics,Ultra-calm pastels (lavender/sage/sky) + breathing animation gradient,Breathing circle animation. Session duration picker. Ambient sound mixer. Streak/consistency tracking. Guided audio player. Sleep timer. Minimal chrome. Slow easing transitions only.
|
||||
99,Weather App,"weather, forecast, temperature, climate, rain, sun, location, humidity",Glassmorphism + Aurora UI,"Motion-Driven, Minimalism",Hero-Centric Design,N/A - Utility focused,Atmospheric gradients (sky blue → sunset → storm grey) + temp scale,Location auto-detect. Hourly horizontal scroll + daily/weekly list. Animated weather icons. Air quality index. UV/wind/humidity chips. Radar map overlay. Widget-friendly layout.
|
||||
100,Diary & Journal App,"diary, journal, personal, daily, reflection, mood, gratitude, writing",Soft UI Evolution + Minimalism,"Neumorphism, Sketch Hand-Drawn",Storytelling-Driven,N/A - Personal focused,Warm paper tones (cream/linen) + muted ink + mood-coded accents,Calendar month-view entry. Mood tag selector (emoji/color). Photo/voice attachment. Writing prompts. Privacy lock (FaceID/PIN). Search across entries. Export to PDF.
|
||||
101,CRM & Client Management,"crm, client, customer, sales, pipeline, contact, lead, deal, hubspot",Flat Design + Minimalism,"Soft UI Evolution, Micro-interactions",Feature-Rich Showcase + Demo,Sales Intelligence Dashboard,Professional blue + pipeline stage colors + closed-won green,Contact card list with avatar. Pipeline kanban board. Activity timeline. Quick-log (call/email/meeting). Deal amount + probability. Tag/segment filter. Mobile quick-actions.
|
||||
102,Inventory & Stock Management,"inventory, stock, warehouse, product, barcode, supply, sku, management",Flat Design + Minimalism,"Dark Mode (OLED), Accessible & Ethical",Feature-Rich Showcase,Real-Time Monitoring + Data-Dense,Functional neutral + status traffic-light (green/amber/red) + scanner accent,Product list/grid with thumbnails. Barcode/QR scanner. Stock level badges. Low-stock alert banner. Category/location filter. Batch edit. Reorder trigger. Audit log.
|
||||
103,Flashcard & Study Tool,"flashcard, quiz, study, spaced-repetition, anki, learn, memory, exam",Claymorphism + Micro-interactions,"Vibrant & Block-based, Flat Design",Feature-Rich Showcase + Demo,Learning Analytics,Playful primary + correct green + incorrect red + progress blue,3D card flip animation. Spaced repetition algorithm. Deck browser. Session progress bar. Streak tracking. Timed quiz mode. Share/import decks. Rich text + image cards.
|
||||
104,Booking & Appointment App,"booking, appointment, schedule, calendar, reservation, slot, service",Soft UI Evolution + Flat Design,"Minimalism, Micro-interactions",Conversion-Optimized,Drill-Down Analytics,Trust blue + available green + booked grey + confirm accent,Calendar strip or month picker. Available time-slot grid. Service + staff selector. Confirmation summary. Reminder push. Reschedule/cancel flow. Two-sided (provider ↔ client).
|
||||
105,Invoice & Billing Tool,"invoice, billing, payment, receipt, freelance, estimate, quote, accounting",Minimalism + Flat Design,"Swiss Modernism 2.0, Accessible & Ethical",Conversion-Optimized + Trust,Financial Dashboard,Professional navy + paid green + overdue red + neutral grey,Invoice template with line items. Tax/discount calculation. Status badges (Draft/Sent/Paid/Overdue). PDF export + share. Payment link generation. Client address book. Recurring invoices.
|
||||
106,Grocery & Shopping List,"grocery, shopping, list, supermarket, checklist, pantry, meal-plan, buy",Flat Design + Vibrant & Block-based,"Claymorphism, Micro-interactions",Minimal & Direct + Demo,N/A - List focused,Fresh green + food-category colors + checkmark accent,Category-grouped list. Tap-to-check interaction (with strikethrough). Quantity stepper. Share list with family. Store aisle sorting. Barcode scan to add. Frequently bought suggestions.
|
||||
107,Timer & Pomodoro,"timer, pomodoro, countdown, stopwatch, focus, clock, productivity, interval",Minimalism + Neumorphism,"Dark Mode (OLED), Micro-interactions",Minimal & Direct,N/A - Utility focused,High-contrast on dark + focus red/amber + break green,Large centered countdown digits. Circular progress ring. Session/break auto-switch. Session history log. Custom interval settings. Sound + haptic alerts. Focus stats chart.
|
||||
108,Parenting & Baby Tracker,"baby, parenting, child, feeding, sleep, diaper, milestone, family, newborn",Claymorphism + Soft UI Evolution,"Vibrant & Block-based, Accessible & Ethical",Social Proof-Focused + Trust,User Behavior Analytics,Soft pastels (baby pink/sky blue/mint/peach) + warm accents,Feed/sleep/diaper quick-log buttons. Growth percentile chart. Milestone timeline with photos. Multiple child profiles. Partner invite + shared access. Pediatric reference. One-handed operation.
|
||||
109,Scanner & Document Manager,"scanner, document, ocr, pdf, scan, camera, file, archive, digitize",Minimalism + Flat Design,"Dark Mode (OLED), Accessible & Ethical",Feature-Rich Showcase + Demo,N/A - Tool focused,Clean white + camera viewfinder accent + file-type color coding,Camera capture with auto-edge detection. Crop/rotate/enhance. OCR text extraction overlay. PDF multi-page creation. Folder tree organization. Cloud sync. Share/export. Batch scan mode.
|
||||
110,Calendar & Scheduling App,"calendar, scheduling, planner, agenda, events, reminder, appointment, organize, date, sync",Flat Design + Micro-interactions,"Minimalism, Soft UI Evolution",Feature-Rich Showcase + Demo,N/A - Calendar focused,Clean blue + event category accent colors + success green,Event color coding. Week/month/day views. Recurring events. Conflict detection. Multi-calendar sync.
|
||||
111,Password Manager,"password, security, vault, credentials, login, secure, encrypt, keychain, 2fa, biometric",Minimalism + Accessible & Ethical,"Dark Mode (OLED), Trust & Authority",Trust & Authority + Feature-Rich,N/A - Vault focused,Trust blue + security green + dark neutral,Security-first. Zero-knowledge architecture. Biometric unlock. Breach alert dashboard. Password generator.
|
||||
112,Expense Splitter / Bill Split,"split, expense, bill, aa, share, friends, group, settle, debt, payment, owe",Flat Design + Vibrant & Block-based,"Minimalism, Micro-interactions",Minimal & Direct + Demo,N/A - Balance focused,Success green + alert red + neutral grey + avatar accent colors,Group expense tracking. Debt simplification algorithm. Payment reminders. Multi-currency. Receipt photo import.
|
||||
113,Voice Recorder & Memo,"voice, recorder, memo, audio, transcription, dictate, recording, microphone, note, otter",Minimalism + AI-Native UI,"Flat Design, Dark Mode (OLED)",Interactive Product Demo + Minimal,N/A - Recording focused,Clean white + recording red + waveform accent,Waveform display. Background recording. Auto-transcription (AI). Tag/organize. Cloud sync.
|
||||
114,Bookmark & Read-Later,"bookmark, read-later, save, article, pocket, link, reading, archive, collection, raindrop",Minimalism + Flat Design,"Editorial Grid, Swiss Modernism 2.0",Minimal & Direct + Demo,N/A - List focused,Paper warm white + ink neutral + minimal accent + tag colors,Fast save via share sheet. Article distraction-free view. Tags and collections. Offline sync. Reading progress.
|
||||
115,Translator App,"translate, language, text, voice, ocr, dictionary, multilingual, real-time, detect, deepl",Flat Design + AI-Native UI,"Minimalism, Micro-interactions",Feature-Rich Showcase + Interactive Demo,N/A - Utility focused,Global blue + neutral grey + language flag accent,Real-time camera translation (OCR). Voice input and output. Offline mode. Conversation mode. Phrasebook.
|
||||
116,Calculator & Unit Converter,"calculator, converter, unit, math, currency, measurement, scientific, formula, percentage",Neumorphism + Minimalism,"Flat Design, Dark Mode (OLED)",Minimal & Direct,N/A - Utility focused,Dark functional + orange operation keys + clear button hierarchy,Scientific mode toggle. Live currency rates. Calculation history. Widget support. Gesture input.
|
||||
117,Alarm & World Clock,"alarm, clock, world, timezone, timer, wake, sleep, schedule, reminder, bedtime",Dark Mode (OLED) + Minimalism,"Neumorphism, Flat Design",Minimal & Direct,N/A - Utility focused,Deep dark + ambient glow accent + timezone gradient,Gentle wake (gradual volume). Timezone visualizer. Sleep tracking integration. Smart alarm skip. Bedtime mode.
|
||||
118,File Manager & Transfer,"file, manager, transfer, folder, document, storage, cloud, share, organize, compress",Flat Design + Minimalism,"Accessible & Ethical, Dark Mode (OLED)",Feature-Rich Showcase + Demo,N/A - File tree focused,"Functional neutral + file type color coding (PDF orange, doc blue, image purple)",Folder tree navigation. File type preview. Wireless P2P transfer. Cloud integration. Compress and extract.
|
||||
119,Email Client,"email, mail, inbox, compose, thread, newsletter, filter, reply, gmail, spark, superhuman",Flat Design + Minimalism,"Micro-interactions, Soft UI Evolution",Feature-Rich Showcase + Demo,N/A - Inbox focused,Clean white + brand primary + priority red + snooze amber,Unified inbox. Swipe actions (archive/delete/snooze). Priority sorting. Smart reply. Unsubscribe tool.
|
||||
120,Casual Puzzle Game,"puzzle, casual, match, brain, game, relaxing, level, tiles, logic, block, three",Claymorphism + Vibrant & Block-based,"Micro-interactions, Motion-Driven",Feature-Rich Showcase + Social Proof,N/A - Game focused,Cheerful pastels + progression gradient + reward gold + bright accent,Satisfying match/clear animations. Progressive difficulty. Daily challenges. No-skip tutorials. Offline play.
|
||||
121,Trivia & Quiz Game,"trivia, quiz, knowledge, question, answer, challenge, leaderboard, fact, brain, compete",Vibrant & Block-based + Micro-interactions,"Claymorphism, Flat Design",Feature-Rich Showcase + Social Proof,Leaderboard Analytics,Energetic blue + correct green + incorrect red + leaderboard gold,Timer pressure UX. Category selection. Streak system. Real-time multiplayer. Daily quiz mode.
|
||||
122,Card & Board Game,"card, board, chess, checkers, poker, strategy, turn-based, multiplayer, classic, tabletop",3D & Hyperrealism + Flat Design,"Motion-Driven, Dark Mode (OLED)",Feature-Rich Showcase,N/A - Game focused,Game-theme felt green + dark wood + card back patterns,Real-time or async multiplayer. Game state sync. Tutorial mode. Match history. ELO rating system.
|
||||
123,Idle & Clicker Game,"idle, clicker, incremental, passive, cookie, adventure, progress, offline, collect, prestige",Vibrant & Block-based + Motion-Driven,"Claymorphism, 3D & Hyperrealism",Feature-Rich Showcase,N/A - Progress focused,Coin gold + upgrade blue + prestige purple + progress green,Offline progress calculation. Satisfying number animations. Upgrade tree clarity. Prestige system. Optional ads.
|
||||
124,Word & Crossword Game,"word, crossword, wordle, spelling, vocabulary, letters, grid, puzzle, dictionary, daily",Minimalism + Flat Design,"Swiss Modernism 2.0, Micro-interactions",Minimal & Direct + Demo,N/A - Game focused,Clean white + warm letter tiles + success green + shake red,Daily challenge with shareable results. Physical keyboard feel. Difficulty levels. Dictionary hints. Streak stats.
|
||||
125,Arcade & Retro Game,"arcade, retro, 8bit, action, shoot, runner, tap, reflex, endless, pixel, classic, score",Pixel Art + Retro-Futurism,"Vibrant & Block-based, Motion-Driven",Feature-Rich Showcase + Hero-Centric,N/A - Score focused,Neon on black + pixel palette + score gold + danger red,Instant play with no login. Game Center leaderboards. Haptic feedback on collision. Offline. Controller support.
|
||||
126,Photo Editor & Filters,"photo, edit, filter, vsco, snapseed, enhance, crop, retouch, adjust, luts, preset, adjust",Minimalism + Dark Mode (OLED),"Motion-Driven, Flat Design",Feature-Rich Showcase + Interactive Demo,N/A - Editor focused,Dark editor background + vibrant filter preview strip + tool icon accent,Non-destructive editing. Filter preview carousel. Histogram. RAW support. Batch export. Social share direct.
|
||||
127,Short Video Editor,"video, edit, capcut, inshot, clip, reel, tiktok, trim, effects, transitions, music, timeline",Dark Mode (OLED) + Motion-Driven,"Vibrant & Block-based, Glassmorphism",Feature-Rich Showcase + Hero-Centric,N/A - Timeline editor focused,Dark background + timeline track accent colors + effect preview vivid,Multi-track timeline. Licensed music library. Text overlays. Auto-captions. Export 9:16 / 16:9 / 1:1.
|
||||
128,Drawing & Sketching Canvas,"drawing, sketch, procreate, canvas, paint, illustration, digital, brush, layers, art, stylus",Minimalism + Dark Mode (OLED),"Anti-Polish Raw, Motion-Driven",Interactive Product Demo + Storytelling,N/A - Canvas focused,Neutral canvas + full-spectrum color picker + tool panel dark,Pressure sensitivity. Infinite canvas (pan/zoom). Layer management. Undo history. Export PNG/PSD/SVG.
|
||||
129,Music Creation & Beat Maker,"music, beat, daw, garageband, create, loop, sample, instrument, track, compose, record, midi",Dark Mode (OLED) + Motion-Driven,"Cyberpunk UI, Glassmorphism",Interactive Product Demo + Storytelling,N/A - DAW focused,Dark studio background + track colors rainbow + waveform accent + BPM pulse,Touch piano and drum pad. Loop browser. MIDI support. Export MP3/WAV. Low-latency audio engine.
|
||||
130,Meme & Sticker Maker,"meme, sticker, maker, funny, caption, template, edit, share, viral, emoji, creator, reaction",Vibrant & Block-based + Flat Design,"Gen Z Chaos, Claymorphism",Feature-Rich Showcase + Social Proof,N/A - Creator focused,Bold primary + comedic yellow + viral red + high saturation accent,Template library. Caption text overlay. Font variety. Reaction sticker packs. Share to all platforms. Fast creation.
|
||||
131,AI Photo & Avatar Generator,"ai, photo, avatar, lensa, portrait, generate, selfie, style, filter, prisma, art",AI-Native UI + Aurora UI,"Glassmorphism, Minimalism",Feature-Rich Showcase + Social Proof,N/A - Generation focused,AI purple + aurora gradients + before/after neutral,Style selection. Multiple output variations. Privacy policy prominent. Fast generation. Credits/subscription system.
|
||||
132,Link-in-Bio Page Builder,"bio, link, linktree, personal, page, creator, social, portfolio, profile, landing, custom",Vibrant & Block-based + Bento Box Grid,"Minimalism, Glassmorphism",Conversion-Optimized + Social Proof,Analytics (click tracking),Brand-customizable + accent link color + clean white canvas,Drag-drop builder. Theme templates. Click analytics. Custom domain. Social icon integration. QR code export.
|
||||
133,Wardrobe & Outfit Planner,"wardrobe, outfit, fashion, clothes, closet, style, wear, plan, capsule, ootd, lookbook",Minimalism + Motion-Driven,"Aurora UI, Soft UI Evolution",Storytelling-Driven + Feature-Rich,N/A - Wardrobe focused,Clean fashion neutral + full clothes color palette + accent,Photo catalog of clothes. AI outfit suggestions. Calendar integration. Capsule wardrobe. Season filtering.
|
||||
134,Plant Care Tracker,"plant, care, water, garden, tracker, reminder, species, photo, grow, health, planta",Organic Biophilic + Soft UI Evolution,"Claymorphism, Flat Design",Storytelling-Driven + Social Proof,N/A - Plant collection focused,Nature greens + earth brown + sunny yellow reminder + water blue,Plant database with care guides. Watering reminders. Growth photo timeline. AI health diagnosis. Collection sharing.
|
||||
135,Book & Reading Tracker,"book, reading, tracker, goodreads, library, shelf, progress, review, notes, goal, literature",Swiss Modernism 2.0 + Minimalism,"E-Ink Paper, Soft UI Evolution",Social Proof-Focused + Feature-Rich,N/A - Library focused,Warm paper white + ink brown + reading progress green + book cover colors,Barcode scan to add. Progress percentage. Annual reading goal. Notes and quotes. Friends activity. Genre stats.
|
||||
136,Couple & Relationship App,"couple, relationship, partner, love, date, anniversary, memory, shared, intimate, between",Aurora UI + Soft UI Evolution,"Claymorphism, Glassmorphism",Storytelling-Driven + Social Proof,N/A - Couple focused,Warm romantic pink/rose + soft gradient + memory photo tones,Shared timeline. Anniversary countdowns. Secret chat. Photo albums. Love language quiz. Date night ideas.
|
||||
137,Family Calendar & Chores,"family, calendar, chores, tasks, household, shared, kids, schedule, cozi, organize, member",Flat Design + Claymorphism,"Accessible & Ethical, Vibrant & Block-based",Feature-Rich Showcase + Social Proof,N/A - Family hub focused,Warm playful + member color coding + chore completion green,Member color coding. Chore assignment rotation. Recurring events. Shared shopping list. Allowance tracking.
|
||||
138,Mood Tracker,"mood, emotion, feeling, mental, daily, journal, wellbeing, check-in, log, track, daylio",Soft UI Evolution + Minimalism,"Aurora UI, Neumorphism",Storytelling-Driven + Social Proof,N/A - Mood chart focused,Emotion gradient (blue sad to yellow happy) + pastel per mood + insight accent,One-tap daily check-in. Emotion wheel selector. Mood calendar heatmap. Pattern insights. Export and share.
|
||||
139,Gift & Wishlist,"gift, wishlist, present, birthday, occasion, registry, idea, shop, list, share, surprise",Vibrant & Block-based + Soft UI Evolution,"Claymorphism, Flat Design",Minimal & Direct + Conversion,N/A - List focused,Celebration warm pink/gold/red + category colors + surprise accent,Add from any URL. Price range filter. Reserved-by-others system. Occasion calendar. Collaborative list. Surprise mode.
|
||||
140,Running & Cycling GPS,"running, cycling, gps, strava, track, route, speed, distance, cadence, pace, workout, sport",Dark Mode (OLED) + Vibrant & Block-based,"Motion-Driven, Glassmorphism",Feature-Rich Showcase + Social Proof,Performance Analytics,Energetic orange + map accent + pace zones (green/yellow/red),Live GPS tracking. Route map. Auto-pause detection. Segment leaderboards. Training zones. Social feed. Garmin sync.
|
||||
141,Yoga & Stretching Guide,"yoga, stretch, flexibility, pose, asana, guided, session, calm, routine, wellness, down-dog",Organic Biophilic + Soft UI Evolution,"Neumorphism, Minimalism",Storytelling-Driven + Social Proof,N/A - Session focused,Earth calming sage/terracotta/cream + breathing gradient + warm accent,Pose library with illustrations. Guided sessions with audio. Breathing exercises. Progress calendar. Beginner to advanced.
|
||||
142,Sleep Tracker,"sleep, tracker, alarm, cycle, quality, snore, analysis, rem, deep, smart, wake, insomnia",Dark Mode (OLED) + Neumorphism,"Glassmorphism, Minimalism",Feature-Rich Showcase + Social Proof,Healthcare Analytics,Deep midnight blue + stars/moon accent + sleep quality gradient (poor red to great green),Sleep cycle detection. Smart alarm wakes at light sleep. Snore detection. Weekly trends. Apple Health integration.
|
||||
143,Calorie & Nutrition Counter,"calorie, nutrition, food, diet, macro, protein, carb, fat, log, fitness, myfitnesspal",Flat Design + Vibrant & Block-based,"Minimalism, Claymorphism",Feature-Rich Showcase + Social Proof,Healthcare Analytics,"Healthy green + macro colors (protein blue, carb orange, fat yellow) + progress circle",Barcode scanner food log. Large database. Macro goals. Restaurant lookup. Recipe builder. AI photo food logging.
|
||||
144,Period & Cycle Tracker,"period, cycle, menstrual, fertility, ovulation, pms, log, women, health, flo, clue, hormone",Soft UI Evolution + Aurora UI,"Accessible & Ethical, Claymorphism",Social Proof-Focused + Trust,Healthcare Analytics,Rose/blush + lavender + fertility green + soft calendar tones,Cycle prediction. Symptom logging. Fertility window. Personalized insights. Privacy-first. Partner sharing option.
|
||||
145,Medication & Pill Reminder,"medication, pill, reminder, dose, schedule, prescription, drug, health, medisafe, refill",Accessible & Ethical + Flat Design,"Minimalism, Trust & Authority",Trust & Authority + Feature-Rich,N/A - Schedule focused,Medical trust blue + missed alert red + taken green + clean white,Multi-medication schedule. Caregiver sharing. Refill reminders. Drug interaction warnings. Large touch targets.
|
||||
146,Water & Hydration Reminder,"water, hydration, drink, reminder, daily, tracker, glasses, intake, health, cup, aqua",Claymorphism + Vibrant & Block-based,"Flat Design, Micro-interactions",Minimal & Direct + Demo,N/A - Daily goal focused,Refreshing blue + water wave animation + goal progress accent,Tap to log quickly. Animated fill visualization. Custom reminders. Goal by weight/weather. Streak system. Widget.
|
||||
147,Fasting & Intermittent Timer,"fasting, intermittent, 16:8, timer, fast, eating, window, keto, diet, zero, weight, protocol",Minimalism + Dark Mode (OLED),"Neumorphism, Flat Design",Feature-Rich Showcase + Social Proof,N/A - Timer focused,Fasting deep blue/purple + eating window green + timeline neutral,"Protocol selector (16:8, 18:6, OMAD). Circular countdown timer. Fasting history log. Tips during fast. Electrolytes."
|
||||
148,Anonymous Community / Confession,"anonymous, community, confess, whisper, secret, vent, share, safe, private, social, yikyak",Dark Mode (OLED) + Minimalism,"Glassmorphism, Soft UI Evolution",Social Proof-Focused + Feature-Rich,User Behavior Analytics,Dark protective + subtle gradient + upvote green + empathy warm accent,Anonymous posting with moderation. Safety reporting. Reaction system. Trending topics. Mental health resources link.
|
||||
149,Local Events & Discovery,"local, events, discovery, meetup, nearby, social, city, activities, calendar, community, explore",Vibrant & Block-based + Motion-Driven,"Glassmorphism, Flat Design",Hero-Centric Design + Feature-Rich,Event Analytics,City vibrant + event category colors + map accent + date highlight,Location-based discovery. Category filters. RSVP flow. Map view. Friend attendance. Organizer tools. Reminders.
|
||||
150,Study Together / Virtual Coworking,"study, focus, cowork, pomodoro, virtual, together, session, accountability, live, stream, room",Minimalism + Soft UI Evolution,"Flat Design, Dark Mode (OLED)",Social Proof-Focused + Feature-Rich,User Behavior Analytics,Calm focus blue + session progress indicator + ambient warm neutrals,Live study rooms with video/avatar presence. Shared focus timer. Ambient music. Goals sharing. Streak accountability.
|
||||
151,Coding Challenge & Practice,"coding, leetcode, challenge, algorithm, practice, programming, competitive, skill, interview, problem",Dark Mode (OLED) + Cyberpunk UI,"Minimalism, Flat Design",Feature-Rich Showcase + Social Proof,Student Analytics,Code editor dark + success green + difficulty gradient (easy green / medium amber / hard red),Code editor with syntax highlight. Multiple languages. Hint system. Solution explanation. Company tags. Contest mode.
|
||||
152,Kids Learning (ABC & Math),"kids, children, learning, abc, math, phonics, numbers, education, games, preschool, early",Claymorphism + Vibrant & Block-based,"Micro-interactions, Flat Design",Social Proof-Focused + Trust,Parent Dashboard,Bright primary + child-safe pastels + reward gold + interactive accent,Age-appropriate UI for 2-8. No ads. No dark patterns. Curriculum aligned. Parent progress reports. Reward system.
|
||||
153,Music Instrument Learning,"music, instrument, piano, guitar, learn, lesson, tutorial, notes, play, chord, practice, simply",Vibrant & Block-based + Motion-Driven,"Dark Mode (OLED), Soft UI Evolution",Interactive Product Demo + Social Proof,Learning Analytics,Musical warm deep red/brown + note color system + skill progress bar,Interactive instrument on-screen. Sheet music display. Song library. Slow-tempo practice. Recording and playback. Teacher mode.
|
||||
154,Parking Finder,"parking, spot, finder, map, pay, meter, garage, location, car, reserve, spothero",Minimalism + Glassmorphism,"Flat Design, Micro-interactions",Conversion-Optimized + Feature-Rich,Real-Time Monitoring + Map,Trust blue + available green + occupied red + map neutral,Real-time availability. In-app navigation. Payment integration. Parking timer alert. Favorite spots. Street vs garage.
|
||||
155,Public Transit Guide,"transit, bus, metro, subway, train, route, schedule, map, city, commute, trip, citymapper",Flat Design + Accessible & Ethical,"Minimalism, Motion-Driven",Feature-Rich Showcase + Interactive Demo,Real-Time Monitoring + Map,Transit brand line colors + real-time indicator green/red + map neutral,Real-time arrivals. Offline maps. Disruption alerts. Multi-modal routing. Fare calculation. Accessibility features.
|
||||
156,Road Trip Planner,"road, trip, drive, route, planner, travel, stop, map, adventure, scenic, car, wanderlog",Aurora UI + Organic Biophilic,"Motion-Driven, Vibrant & Block-based",Storytelling-Driven + Hero-Centric,N/A - Trip focused,Adventure warm sunset orange + map teal + stop markers + road neutral,Route planning with stops. Point-of-interest discovery. Gas/food/hotel along route. Offline maps. Trip sharing.
|
||||
157,VPN & Privacy Tool,"vpn, privacy, secure, anonymous, encrypt, proxy, ip, protect, shield, network, nordvpn",Minimalism + Dark Mode (OLED),"Cyberpunk UI, Trust & Authority",Trust & Authority + Conversion-Optimized,N/A - Connection focused,Dark shield blue + connected green + disconnected red + trust accent,One-tap connect. Server selection by country. No-log policy prominent. Speed indicator. Kill switch. Protocol choice.
|
||||
158,Emergency SOS & Safety,"emergency, sos, safety, alert, location, help, danger, crisis, first-aid, guard, bsafe",Accessible & Ethical + Flat Design,"Dark Mode (OLED), Minimalism",Trust & Authority + Social Proof,N/A - Safety focused,Alert red + safety blue + location green + high contrast critical,One-tap SOS. Emergency contacts auto-notify. Live location sharing. Fake call feature. Safe walk mode. Local emergency numbers.
|
||||
159,Wallpaper & Theme App,"wallpaper, theme, background, customize, aesthetic, home-screen, lock-screen, widget, design, zedge",Vibrant & Block-based + Aurora UI,"Glassmorphism, Motion-Driven",Feature-Rich Showcase + Social Proof,N/A - Gallery focused,Content-driven + trending aesthetic palettes + download accent,Category browsing. Preview on device. Daily wallpaper auto-set. Widget matching. Creator uploads. Resolution auto-fit.
|
||||
160,White Noise & Ambient Sound,"white noise, ambient, sound, sleep, focus, rain, nature, relax, concentration, background, noisli",Minimalism + Dark Mode (OLED),"Neumorphism, Organic Biophilic",Minimal & Direct + Social Proof,N/A - Player focused,Calming dark + ambient texture visual + subtle sound wave + sleep blue,Sound mixer with multiple simultaneous layers. Sleep timer with fade. Custom soundscapes. Offline. Background audio.
|
||||
161,Home Decoration & Interior Design,"home, interior, decor, design, furniture, room, renovation, ar, plan, inspire, 3d, houzz",Minimalism + 3D Product Preview,"Organic Biophilic, Aurora UI",Storytelling-Driven + Feature-Rich,N/A - Project focused,Neutral interior palette + material texture accent + AR blue,AR room visualization. Style quiz. Product catalog with purchase links. 3D room planner. Mood board. Before/after.
|
||||
|
|
|
@ -1,45 +0,0 @@
|
|||
No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
|
||||
1,Async Waterfall,Defer Await,async await defer branch,React/Next.js,Move await into branches where actually used to avoid blocking unused code paths,Move await operations into branches where they're needed,Await at top of function blocking all branches,"if (skip) return { skipped: true }; const data = await fetch()","const data = await fetch(); if (skip) return { skipped: true }",Critical
|
||||
2,Async Waterfall,Promise.all Parallel,promise all parallel concurrent,React/Next.js,Execute independent async operations concurrently using Promise.all(),Use Promise.all() for independent operations,Sequential await for independent operations,"const [user, posts] = await Promise.all([fetchUser(), fetchPosts()])","const user = await fetchUser(); const posts = await fetchPosts()",Critical
|
||||
3,Async Waterfall,Dependency Parallelization,better-all dependency parallel,React/Next.js,Use better-all for operations with partial dependencies to maximize parallelism,Use better-all to start each task at earliest possible moment,Wait for unrelated data before starting dependent fetch,"await all({ user() {}, config() {}, profile() { return fetch((await this.$.user).id) } })","const [user, config] = await Promise.all([...]); const profile = await fetchProfile(user.id)",Critical
|
||||
4,Async Waterfall,API Route Optimization,api route waterfall promise,React/Next.js,In API routes start independent operations immediately even if not awaited yet,Start promises early and await late,Sequential awaits in API handlers,"const sessionP = auth(); const configP = fetchConfig(); const session = await sessionP","const session = await auth(); const config = await fetchConfig()",Critical
|
||||
5,Async Waterfall,Suspense Boundaries,suspense streaming boundary,React/Next.js,Use Suspense to show wrapper UI faster while data loads,Wrap async components in Suspense boundaries,Await data blocking entire page render,"<Suspense fallback={<Skeleton />}><DataDisplay /></Suspense>","const data = await fetchData(); return <DataDisplay data={data} />",High
|
||||
6,Bundle Size,Barrel Imports,barrel import direct path,React/Next.js,Import directly from source files instead of barrel files to avoid loading unused modules,Import directly from source path,Import from barrel/index files,"import Check from 'lucide-react/dist/esm/icons/check'","import { Check } from 'lucide-react'",Critical
|
||||
7,Bundle Size,Dynamic Imports,dynamic import lazy next,React/Next.js,Use next/dynamic to lazy-load large components not needed on initial render,Use dynamic() for heavy components,Import heavy components at top level,"const Monaco = dynamic(() => import('./monaco'), { ssr: false })","import { MonacoEditor } from './monaco-editor'",Critical
|
||||
8,Bundle Size,Defer Third Party,analytics defer third-party,React/Next.js,Load analytics and logging after hydration since they don't block interaction,Load non-critical scripts after hydration,Include analytics in main bundle,"const Analytics = dynamic(() => import('@vercel/analytics'), { ssr: false })","import { Analytics } from '@vercel/analytics/react'",Medium
|
||||
9,Bundle Size,Conditional Loading,conditional module lazy,React/Next.js,Load large data or modules only when a feature is activated,Dynamic import when feature enabled,Import large modules unconditionally,"useEffect(() => { if (enabled) import('./heavy.js') }, [enabled])","import { heavyData } from './heavy.js'",High
|
||||
10,Bundle Size,Preload Intent,preload hover focus intent,React/Next.js,Preload heavy bundles on hover/focus before they're needed,Preload on user intent signals,Load only on click,"onMouseEnter={() => import('./editor')}","onClick={() => import('./editor')}",Medium
|
||||
11,Server,React.cache Dedup,react cache deduplicate request,React/Next.js,Use React.cache() for server-side request deduplication within single request,Wrap data fetchers with cache(),Fetch same data multiple times in tree,"export const getUser = cache(async () => await db.user.find())","export async function getUser() { return await db.user.find() }",Medium
|
||||
12,Server,LRU Cache Cross-Request,lru cache cross request,React/Next.js,Use LRU cache for data shared across sequential requests,Use LRU for cross-request caching,Refetch same data on every request,"const cache = new LRUCache({ max: 1000, ttl: 5*60*1000 })","Always fetch from database",High
|
||||
13,Server,Minimize Serialization,serialization rsc boundary,React/Next.js,Only pass fields that client actually uses across RSC boundaries,Pass only needed fields to client components,Pass entire objects to client,"<Profile name={user.name} />","<Profile user={user} /> // 50 fields serialized",High
|
||||
14,Server,Parallel Fetching,parallel fetch component composition,React/Next.js,Restructure components to parallelize data fetching in RSC,Use component composition for parallel fetches,Sequential fetches in parent component,"<Header /><Sidebar /> // both fetch in parallel","const header = await fetchHeader(); return <><div>{header}</div><Sidebar /></>",Critical
|
||||
15,Server,After Non-blocking,after non-blocking logging,React/Next.js,Use Next.js after() to schedule work after response is sent,Use after() for logging/analytics,Block response for non-critical operations,"after(async () => { await logAction() }); return Response.json(data)","await logAction(); return Response.json(data)",Medium
|
||||
16,Client,SWR Deduplication,swr dedup cache revalidate,React/Next.js,Use SWR for automatic request deduplication and caching,Use useSWR for client data fetching,Manual fetch in useEffect,"const { data } = useSWR('/api/users', fetcher)","useEffect(() => { fetch('/api/users').then(setUsers) }, [])",Medium-High
|
||||
17,Client,Event Listener Dedup,event listener deduplicate global,React/Next.js,Share global event listeners across component instances,Use useSWRSubscription for shared listeners,Register listener per component instance,"useSWRSubscription('global-keydown', () => { window.addEventListener... })","useEffect(() => { window.addEventListener('keydown', handler) }, [])",Low
|
||||
18,Rerender,Defer State Reads,state read callback subscription,React/Next.js,Don't subscribe to state only used in callbacks,Read state on-demand in callbacks,Subscribe to state used only in handlers,"const handleClick = () => { const params = new URLSearchParams(location.search) }","const params = useSearchParams(); const handleClick = () => { params.get('ref') }",Medium
|
||||
19,Rerender,Memoized Components,memo extract expensive,React/Next.js,Extract expensive work into memoized components for early returns,Extract to memo() components,Compute expensive values before early return,"const UserAvatar = memo(({ user }) => ...); if (loading) return <Skeleton />","const avatar = useMemo(() => compute(user)); if (loading) return <Skeleton />",Medium
|
||||
20,Rerender,Narrow Dependencies,effect dependency primitive,React/Next.js,Specify primitive dependencies instead of objects in effects,Use primitive values in dependency arrays,Use object references as dependencies,"useEffect(() => { console.log(user.id) }, [user.id])","useEffect(() => { console.log(user.id) }, [user])",Low
|
||||
21,Rerender,Derived State,derived boolean subscription,React/Next.js,Subscribe to derived booleans instead of continuous values,Use derived boolean state,Subscribe to continuous values,"const isMobile = useMediaQuery('(max-width: 767px)')","const width = useWindowWidth(); const isMobile = width < 768",Medium
|
||||
22,Rerender,Functional setState,functional setstate callback,React/Next.js,Use functional setState updates for stable callbacks and no stale closures,Use functional form: setState(curr => ...),Reference state directly in setState,"setItems(curr => [...curr, newItem])","setItems([...items, newItem]) // items in deps",Medium
|
||||
23,Rerender,Lazy State Init,usestate lazy initialization,React/Next.js,Pass function to useState for expensive initial values,Use function form for expensive init,Compute expensive value directly,"useState(() => buildSearchIndex(items))","useState(buildSearchIndex(items)) // runs every render",Medium
|
||||
24,Rerender,Transitions,starttransition non-urgent,React/Next.js,Mark frequent non-urgent state updates as transitions,Use startTransition for non-urgent updates,Block UI on every state change,"startTransition(() => setScrollY(window.scrollY))","setScrollY(window.scrollY) // blocks on every scroll",Medium
|
||||
25,Rendering,SVG Animation Wrapper,svg animation wrapper div,React/Next.js,Wrap SVG in div and animate wrapper for hardware acceleration,Animate div wrapper around SVG,Animate SVG element directly,"<div class='animate-spin'><svg>...</svg></div>","<svg class='animate-spin'>...</svg>",Low
|
||||
26,Rendering,Content Visibility,content-visibility auto,React/Next.js,Apply content-visibility: auto to defer off-screen rendering,Use content-visibility for long lists,Render all list items immediately,".item { content-visibility: auto; contain-intrinsic-size: 0 80px }","Render 1000 items without optimization",High
|
||||
27,Rendering,Hoist Static JSX,hoist static jsx element,React/Next.js,Extract static JSX outside components to avoid re-creation,Hoist static elements to module scope,Create static elements inside components,"const skeleton = <div class='animate-pulse' />; function C() { return skeleton }","function C() { return <div class='animate-pulse' /> }",Low
|
||||
28,Rendering,Hydration No Flicker,hydration mismatch flicker,React/Next.js,Use inline script to set client-only data before hydration,Inject sync script for client-only values,Use useEffect causing flash,"<script dangerouslySetInnerHTML={{ __html: 'el.className = localStorage.theme' }} />","useEffect(() => setTheme(localStorage.theme), []) // flickers",Medium
|
||||
29,Rendering,Conditional Render,conditional render ternary,React/Next.js,Use ternary instead of && when condition can be 0 or NaN,Use explicit ternary for conditionals,Use && with potentially falsy numbers,"{count > 0 ? <Badge>{count}</Badge> : null}","{count && <Badge>{count}</Badge>} // renders '0'",Low
|
||||
30,Rendering,Activity Component,activity show hide preserve,React/Next.js,Use Activity component to preserve state/DOM for toggled components,Use Activity for expensive toggle components,Unmount/remount on visibility toggle,"<Activity mode={isOpen ? 'visible' : 'hidden'}><Menu /></Activity>","{isOpen && <Menu />} // loses state",Medium
|
||||
31,JS Perf,Batch DOM CSS,batch dom css reflow,React/Next.js,Group CSS changes via classes or cssText to minimize reflows,Use class toggle or cssText,Change styles one property at a time,"element.classList.add('highlighted')","el.style.width='100px'; el.style.height='200px'",Medium
|
||||
32,JS Perf,Index Map Lookup,map index lookup find,React/Next.js,Build Map for repeated lookups instead of multiple .find() calls,Build index Map for O(1) lookups,Use .find() in loops,"const byId = new Map(users.map(u => [u.id, u])); byId.get(id)","users.find(u => u.id === order.userId) // O(n) each time",Low-Medium
|
||||
33,JS Perf,Cache Property Access,cache property loop,React/Next.js,Cache object property lookups in hot paths,Cache values before loops,Access nested properties in loops,"const val = obj.config.settings.value; for (...) process(val)","for (...) process(obj.config.settings.value)",Low-Medium
|
||||
34,JS Perf,Cache Function Results,memoize cache function,React/Next.js,Use module-level Map to cache repeated function results,Use Map cache for repeated calls,Recompute same values repeatedly,"const cache = new Map(); if (cache.has(x)) return cache.get(x)","slugify(name) // called 100 times same input",Medium
|
||||
35,JS Perf,Cache Storage API,localstorage cache read,React/Next.js,Cache localStorage/sessionStorage reads in memory,Cache storage reads in Map,Read storage on every call,"if (!cache.has(key)) cache.set(key, localStorage.getItem(key))","localStorage.getItem('theme') // every call",Low-Medium
|
||||
36,JS Perf,Combine Iterations,combine filter map loop,React/Next.js,Combine multiple filter/map into single loop,Single loop for multiple categorizations,Chain multiple filter() calls,"for (u of users) { if (u.isAdmin) admins.push(u); if (u.isTester) testers.push(u) }","users.filter(admin); users.filter(tester); users.filter(inactive)",Low-Medium
|
||||
37,JS Perf,Length Check First,length check array compare,React/Next.js,Check array lengths before expensive comparisons,Early return if lengths differ,Always run expensive comparison,"if (a.length !== b.length) return true; // then compare","a.sort().join() !== b.sort().join() // even when lengths differ",Medium-High
|
||||
38,JS Perf,Early Return,early return exit function,React/Next.js,Return early when result is determined to skip processing,Return immediately on first error,Process all items then check errors,"for (u of users) { if (!u.email) return { error: 'Email required' } }","let hasError; for (...) { if (!email) hasError=true }; if (hasError)...",Low-Medium
|
||||
39,JS Perf,Hoist RegExp,regexp hoist module,React/Next.js,Don't create RegExp inside render - hoist or memoize,Hoist RegExp to module scope,Create RegExp every render,"const EMAIL_RE = /^[^@]+@[^@]+$/; function validate() { EMAIL_RE.test(x) }","function C() { const re = new RegExp(pattern); re.test(x) }",Low-Medium
|
||||
40,JS Perf,Loop Min Max,loop min max sort,React/Next.js,Use loop for min/max instead of sort - O(n) vs O(n log n),Single pass loop for min/max,Sort array to find min/max,"let max = arr[0]; for (x of arr) if (x > max) max = x","arr.sort((a,b) => b-a)[0] // O(n log n)",Low
|
||||
41,JS Perf,Set Map Lookups,set map includes has,React/Next.js,Use Set/Map for O(1) lookups instead of array.includes(),Convert to Set for membership checks,Use .includes() for repeated checks,"const allowed = new Set(['a','b']); allowed.has(id)","const allowed = ['a','b']; allowed.includes(id)",Low-Medium
|
||||
42,JS Perf,toSorted Immutable,tosorted sort immutable,React/Next.js,Use toSorted() instead of sort() to avoid mutating arrays,Use toSorted() for immutability,Mutate arrays with sort(),"users.toSorted((a,b) => a.name.localeCompare(b.name))","users.sort((a,b) => a.name.localeCompare(b.name)) // mutates",Medium-High
|
||||
43,Advanced,Event Handler Refs,useeffectevent ref handler,React/Next.js,Store callbacks in refs for stable effect subscriptions,Use useEffectEvent for stable handlers,Re-subscribe on every callback change,"const onEvent = useEffectEvent(handler); useEffect(() => { listen(onEvent) }, [])","useEffect(() => { listen(handler) }, [handler]) // re-subscribes",Low
|
||||
44,Advanced,useLatest Hook,uselatest ref callback,React/Next.js,Access latest values in callbacks without adding to dependency arrays,Use useLatest for fresh values in stable callbacks,Add callback to effect dependencies,"const cbRef = useLatest(cb); useEffect(() => { setTimeout(() => cbRef.current()) }, [])","useEffect(() => { setTimeout(() => cb()) }, [cb]) // re-runs",Low
|
||||
|
|
|
@ -1,51 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Components,Use standalone components,Angular 17+ default; no NgModule needed,Standalone components for all new code,NgModule-based components for new projects,"@Component({ standalone: true imports: [CommonModule] })","@NgModule({ declarations: [MyComp] })",High,https://angular.dev/guide/components/importing
|
||||
2,Components,Use signals for state,Signals are Angular's reactive primitive for fine-grained reactivity,Signals for component state over class properties,Mutable class properties without signals,"count = signal(0); increment() { this.count.update(v => v + 1) }","count = 0; increment() { this.count++ }",High,https://angular.dev/guide/signals
|
||||
3,Components,Use @if/@for/@switch control flow,Built-in control flow syntax replaces *ngIf/*ngFor directives,@if and @for in templates,*ngIf and *ngFor structural directives,"@if (isLoggedIn) { <Dashboard /> } @else { <Login /> }","<div *ngIf=""isLoggedIn""><Dashboard /></div>",High,https://angular.dev/guide/templates/control-flow
|
||||
4,Components,Use input() and output() signals,Signal-based inputs/outputs replace @Input()/@Output() decorators,input() and output() for component API,@Input() and @Output() decorators,"name = input<string>(); clicked = output<void>()","@Input() name: string; @Output() clicked = new EventEmitter()",High,https://angular.dev/guide/components/inputs
|
||||
5,Components,Use content projection,ng-content for flexible component composition,ng-content with select for named slots,Rigid templates that can't be customized,"<ng-content select=""[header]"" /> <ng-content />","<div class=""header"">{{ title }}</div>",Medium,https://angular.dev/guide/components/content-projection
|
||||
6,Components,Keep components small,Single responsibility; components should do one thing,Extract sub-components when template exceeds 50 lines,Monolithic components handling multiple concerns,"<UserAvatar /> <UserDetails /> <UserActions />",One 300-line component template,Medium,https://angular.dev/guide/components
|
||||
7,Components,Use OnPush change detection,Reduces re-renders by only checking on input changes or signal updates,OnPush for all components,Default change detection strategy,"changeDetection: ChangeDetectionStrategy.OnPush","changeDetection: ChangeDetectionStrategy.Default",High,https://angular.dev/guide/components/lifecycle
|
||||
8,Components,Avoid direct DOM manipulation,Use renderer or ElementRef sparingly; prefer template bindings,Template bindings and Angular directives,Direct document.querySelector or innerHTML,"[class.active]=""isActive""","this.el.nativeElement.classList.add('active')",High,https://angular.dev/guide/components/host-elements
|
||||
9,Routing,Lazy load feature routes,Load route chunks on demand to reduce initial bundle,loadComponent() for all feature routes,Eager-loaded routes in app config,"{ path: 'admin' loadComponent: () => import('./admin/admin.component') }","{ path: 'admin' component: AdminComponent }",High,https://angular.dev/guide/routing/lazy-loading
|
||||
10,Routing,Use route guards with functional API,Protect routes with canActivate/canMatch functional guards,Functional guards returning boolean or UrlTree,Class-based guards with CanActivate interface,"canActivate: [() => inject(AuthService).isLoggedIn()]","canActivate: [AuthGuard]",High,https://angular.dev/guide/routing/common-router-tasks#preventing-unauthorized-access
|
||||
11,Routing,Use route resolvers for data,Pre-fetch data before route activation using resolve,ResolveFn for route data,Fetching data in ngOnInit causing flash of empty state,"resolve: { user: () => inject(UserService).getUser() }",Fetch in ngOnInit with loading state flickering,Medium,https://angular.dev/guide/routing/common-router-tasks#resolve
|
||||
12,Routing,Type route params with inject,Use inject(ActivatedRoute) with signals or toSignal,Typed route params via ActivatedRoute,Untyped route.snapshot.params string access,"const id = toSignal(route.paramMap.pipe(map(p => p.get('id'))))","const id = this.route.snapshot.params['id']",Medium,https://angular.dev/api/router/ActivatedRoute
|
||||
13,Routing,Use nested routes for layouts,Compose shared layouts using router-outlet nesting,Nested routes with shared layout components,Duplicating layout code across routes,"{ path: 'app' component: ShellComponent children: [...] }",Duplicate header/sidebar in each route component,Medium,https://angular.dev/guide/routing/router-tutorial-toh#child-route-configuration
|
||||
14,Routing,Configure preloading strategies,Preload lazy modules in background after initial load,PreloadAllModules or custom strategy,No preloading causing delayed navigation,"provideRouter(routes withPreloading(PreloadAllModules))","provideRouter(routes)",Low,https://angular.dev/api/router/PreloadAllModules
|
||||
15,State,Use signals for local state,Signals provide synchronous reactive state without RxJS overhead,signal() for component-local reactive state,BehaviorSubject for simple local state,"const items = signal<Item[]>([]); addItem(i: Item) { this.items.update(arr => [...arr i]) }","items$ = new BehaviorSubject<Item[]>([])",High,https://angular.dev/guide/signals
|
||||
16,State,Use computed() for derived state,Lazily evaluated derived values that update when dependencies change,computed() for values derived from other signals,Duplicated state or manual sync,"readonly total = computed(() => this.items().reduce((s i) => s + i.price 0))","this.total = this.items.reduce(...) // called manually",High,https://angular.dev/guide/signals#computed-signals
|
||||
17,State,Use effect() carefully,Effects run side effects when signals change; avoid overuse,effect() for side effects like logging or localStorage sync,effect() for deriving state (use computed instead),"effect(() => localStorage.setItem('cart' JSON.stringify(this.cart())))","effect(() => { this.total.set(this.items().length) })",Medium,https://angular.dev/guide/signals#effects
|
||||
18,State,Use NgRx Signal Store for complex state,NgRx Signal Store is the modern lightweight state management for Angular,@ngrx/signals SignalStore for feature state,Full NgRx reducer/action/effect boilerplate for simple state,"const Store = signalStore(withState({ count: 0 }) withMethods(s => ({ increment: () => patchState(s { count: s.count() + 1 }) })))","createReducer(on(increment state => ({ ...state count: state.count + 1 })))",Medium,https://ngrx.io/guide/signals
|
||||
19,State,Inject services for shared state,Services with signals share state across components without a store,Injectable service with signals for cross-component state,Prop drilling or @Input chains for shared state,"@Injectable({ providedIn: 'root' }) class CartService { items = signal<Item[]>([]) }","@Input() cartItems passed through 4 component levels",Medium,https://angular.dev/guide/di/creating-injectable-service
|
||||
20,State,Avoid mixing RxJS and signals unnecessarily,Use toSignal() to bridge RxJS into signal world at the boundary,toSignal() to convert observable to signal at component edge,Subscribing in components and storing in signal manually,"readonly user = toSignal(this.userService.user$)","this.userService.user$.subscribe(u => this.user.set(u))",Medium,https://angular.dev/guide/rxjs-interop
|
||||
21,Forms,Use typed reactive forms,FormGroup/FormControl with explicit generics for compile-time safety,FormBuilder with typed controls,Untyped FormControl or any casts,"fb.group<LoginForm>({ email: fb.control('') password: fb.control('') })","new FormGroup({ email: new FormControl(null) })",High,https://angular.dev/guide/forms/typed-forms
|
||||
22,Forms,Use reactive forms over template-driven,Reactive forms scale better and are fully testable,ReactiveFormsModule for all non-trivial forms,FormsModule with ngModel for complex forms,"<input [formControl]=""emailControl"" />","<input [(ngModel)]=""email"" />",Medium,https://angular.dev/guide/forms/reactive-forms
|
||||
23,Forms,Write custom validators as functions,Functional validators are composable and tree-shakeable,ValidatorFn functions for custom validation,Class-based validators implementing Validator interface,"const noSpaces: ValidatorFn = ctrl => ctrl.value?.includes(' ') ? { noSpaces: true } : null","class NoSpacesValidator implements Validator { validate(c) {} }",Medium,https://angular.dev/guide/forms/form-validation#custom-validators
|
||||
24,Forms,Use updateOn for performance,Control when validation runs to avoid per-keystroke validation overhead,updateOn: 'blur' or 'submit' for expensive validators,Default updateOn: 'change' for async validators,"fb.control('' { updateOn: 'blur' validators: [Validators.email] })","fb.control('' [Validators.email]) // validates on every key",Low,https://angular.dev/api/forms/AbstractControl#updateOn
|
||||
25,Forms,Use FormArray for dynamic fields,FormArray manages variable-length lists of controls,FormArray for add/remove field scenarios,Manually tracking index-based controls,"get items(): FormArray { return this.form.get('items') as FormArray }","items: [FormControl] managed outside form",Medium,https://angular.dev/guide/forms/reactive-forms#using-the-formarray-class
|
||||
26,Forms,Display validation errors clearly,Use form control touched and dirty states to show errors at the right time,Show errors after field is touched,Show all errors on page load,"@if (email.invalid && email.touched) { <span>Invalid email</span> }","@if (email.invalid) { <span>Invalid email</span> }",Medium,https://angular.dev/guide/forms/form-validation
|
||||
27,Performance,Apply OnPush to all components,OnPush + signals eliminates most unnecessary change detection cycles,OnPush change detection everywhere,Default strategy which checks entire tree on every event,changeDetection: ChangeDetectionStrategy.OnPush,changeDetection: ChangeDetectionStrategy.Default,High,https://angular.dev/best-practices/skipping-component-subtrees
|
||||
28,Performance,Use trackBy in @for blocks,Stable identity for list items prevents full DOM re-creation on change,track item.id in @for,"@for (item of items; track item.id) { <li>{{ item.name }}</li> }","@for (item of items; track $index) { <li>{{ item.name }}</li> }",High,https://angular.dev/guide/templates/control-flow#track-and-identity
|
||||
29,Performance,Use @defer for below-the-fold content,Defer blocks lazy-load components when they enter the viewport,@defer with on viewport for non-critical UI,Eagerly loading all components at startup,"@defer (on viewport) { <HeavyChart /> } @placeholder { <Skeleton /> }","<HeavyChart /> loaded at startup",High,https://angular.dev/guide/defer
|
||||
30,Performance,Use NgOptimizedImage,Enforces image best practices: lazy loading LCP hints and proper sizing,NgOptimizedImage for all img tags,Plain img tags for CMS or user content,"<img ngSrc=""/hero.jpg"" width=""800"" height=""400"" priority />","<img src=""/hero.jpg"" />",High,https://angular.dev/guide/image-optimization
|
||||
31,Performance,Tree-shake unused Angular features,Import only what you use from Angular packages,Import specific Angular modules needed,Import BrowserAnimationsModule when not using animations,"import { NgOptimizedImage } from '@angular/common'","import { CommonModule } from '@angular/common' // entire module",Medium,https://angular.dev/tools/cli/build
|
||||
32,Performance,Avoid subscribe in components,Subscriptions leak and cause bugs; prefer async pipe or toSignal,toSignal() or async pipe instead of manual subscribe,Manual subscribe without unsubscribe in ngOnDestroy,"readonly data = toSignal(this.service.data$)","this.service.data$.subscribe(d => this.data = d)",High,https://angular.dev/guide/rxjs-interop
|
||||
33,Performance,Use SSR with Angular Universal,Pre-render pages for faster LCP and better SEO,SSR or SSG for public-facing routes,Pure CSR for SEO-critical pages,"ng add @angular/ssr","// no SSR, client renders empty shell",Medium,https://angular.dev/guide/ssr
|
||||
34,Performance,Minimize bundle with standalone APIs,Standalone components + provideRouter() eliminate dead NgModule code,provideRouter() and provideHttpClient() in app.config,Root AppModule with all imports,provideRouter(routes) in app.config.ts,"@NgModule({ imports: [RouterModule.forRoot(routes)] })",Medium,https://angular.dev/guide/routing/standalone
|
||||
35,Testing,Use TestBed for component tests,TestBed sets up Angular DI for realistic component testing,TestBed.configureTestingModule for component tests,Instantiate components with new keyword,"TestBed.configureTestingModule({ imports: [MyComponent] })","const comp = new MyComponent()",High,https://angular.dev/guide/testing/components-basics
|
||||
36,Testing,Use Angular CDK component harnesses,Harnesses provide a stable testing API that survives template refactors,MatButtonHarness and custom HarnessLoader,Direct native element queries that break on template changes,"const btn = await loader.getHarness(MatButtonHarness)","fixture.debugElement.query(By.css('button'))",Medium,https://material.angular.io/cdk/test-harnesses/overview
|
||||
37,Testing,Use Spectator for less boilerplate,Spectator wraps TestBed with a cleaner API reducing test setup noise,Spectator for unit tests,Raw TestBed for every test,"const spectator = createComponentFactory(MyComponent)","TestBed.configureTestingModule({ declarations: [MyComponent] providers: [...] })",Low,https://github.com/ngneat/spectator
|
||||
38,Testing,Mock services with jasmine.createSpyObj,Isolate unit tests by providing mock implementations of dependencies,SpyObj or jest.fn() mocks for services,Real HTTP calls in unit tests,"const spy = jasmine.createSpyObj('UserService' ['getUser']); spy.getUser.and.returnValue(of(user))","providers: [UserService] // real service in unit test",High,https://angular.dev/guide/testing/services
|
||||
39,Testing,Write integration tests for routes,Test full route navigation including guards and resolvers,RouterTestingHarness for route integration tests,Mock all routing behavior in unit tests,"const harness = await RouterTestingHarness.create(); await harness.navigateByUrl('/home')","// manually calling route guard methods",Medium,https://angular.dev/api/router/testing/RouterTestingHarness
|
||||
40,Testing,Test signal-based components,Signals update synchronously; no async flush needed in most cases,Read signal value directly in test assertions,TestBed.tick() or fakeAsync for signal reads,"component.count.set(5); expect(component.double()).toBe(10)","fakeAsync(() => { component.count.set(5); tick(); expect(component.double()).toBe(10) })",Medium,https://angular.dev/guide/testing
|
||||
41,Styling,Use ViewEncapsulation.Emulated,Default emulation scopes styles to component preventing global leaks,Emulated or None for intentional global styles,ViewEncapsulation.None for component-specific styles,ViewEncapsulation.Emulated (default),ViewEncapsulation.None on feature components,Medium,https://angular.dev/guide/components/styling#style-scoping
|
||||
42,Styling,Use :host selector,Style the component's host element using :host pseudo-class,":host for host element styles",Adding wrapper div just for styling,":host { display: block; padding: 1rem }","<div class=""wrapper"">...</div> + .wrapper { padding: 1rem }",Medium,https://angular.dev/guide/components/styling#host-element
|
||||
43,Styling,Use CSS custom properties for theming,CSS variables work across component boundaries and enable dynamic theming,CSS custom properties for colors and spacing,Hardcoded hex values in component styles,":root { --primary: #6200ee } button { background: var(--primary) }","button { background: #6200ee }",Medium,https://angular.dev/guide/components/styling
|
||||
44,Styling,Integrate Tailwind with Angular,Tailwind utilities work alongside Angular's ViewEncapsulation via global stylesheet,Add Tailwind in styles.css and use utility classes in templates,Custom CSS for layout that Tailwind already handles,"<div class=""flex items-center gap-4 p-6"">","<div class=""my-custom-flex""> /* .my-custom-flex { display: flex } */",Low,https://tailwindcss.com/docs/guides/angular
|
||||
45,Styling,Use Angular Material theming tokens,Material 3 uses design tokens for systematic theming,M3 token-based theming for Angular Material,Overriding Angular Material CSS with deep selectors,"@include mat.button-theme($my-theme)","::ng-deep .mat-button { background: red }",Medium,https://material.angular.io/guide/theming
|
||||
46,Architecture,Use injection tokens for config,Provide configuration via InjectionToken for testability and flexibility,InjectionToken for environment-specific values,Importing environment.ts directly in services,"const API_URL = new InjectionToken<string>('apiUrl'); provide: [{ provide: API_URL useValue: env.apiUrl }]","constructor(private env: Environment) { this.url = env.apiUrl }",Medium,https://angular.dev/guide/di/dependency-injection-providers#using-an-injectiontoken-object
|
||||
47,Architecture,Use HTTP interceptors,Intercept requests for auth headers error handling and logging,Functional interceptors with withInterceptors(),Service-level header management in every request,"withInterceptors([authInterceptor errorInterceptor])","httpClient.get(url { headers: { Authorization: token } }) in every call",High,https://angular.dev/guide/http/interceptors
|
||||
48,Architecture,Organize by feature not type,Feature-based folder structure scales better than type-based,Feature folders with collocated component service and routes,Flat folders: all-components/ all-services/,"src/features/checkout/checkout.component.ts checkout.service.ts checkout.routes.ts","src/components/checkout.component.ts src/services/checkout.service.ts",Medium,https://angular.dev/style-guide#folders-by-feature-structure
|
||||
49,Architecture,Use environment configurations,Separate environment values for dev staging and prod via Angular build configs,angular.json fileReplacements for env configs,Hardcoded API URLs or feature flags in source,"fileReplacements: [{ replace: environment.ts with: environment.prod.ts }]","const API = 'https://api.example.com' // hardcoded in service",High,https://angular.dev/tools/cli/environments
|
||||
50,Architecture,Prefer inject() over constructor DI,inject() function is composable and works in more contexts than constructor injection,inject() for dependency injection,Constructor parameters for new code,"readonly http = inject(HttpClient); readonly router = inject(Router)","constructor(private http: HttpClient private router: Router) {}",Medium,https://angular.dev/api/core/inject
|
||||
|
Can't render this file because it has a wrong number of fields in line 29.
|
|
|
@ -1,54 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Architecture,Use Islands Architecture,Astro's partial hydration only loads JS for interactive components,Interactive components with client directives,Hydrate entire page like traditional SPA,<Counter client:load />,Everything as client component,High,https://docs.astro.build/en/concepts/islands/
|
||||
2,Architecture,Default to zero JS,Astro ships zero JS by default - add only when needed,Static components without client directive,Add client:load to everything,<Header /> (static),<Header client:load /> (unnecessary),High,https://docs.astro.build/en/basics/astro-components/
|
||||
3,Architecture,Choose right client directive,Different directives for different hydration timing,client:visible for below-fold client:idle for non-critical,client:load for everything,<Comments client:visible />,<Comments client:load />,Medium,https://docs.astro.build/en/reference/directives-reference/#client-directives
|
||||
4,Architecture,Use content collections,Type-safe content management for blogs docs,Content collections for structured content,Loose markdown files without schema,const posts = await getCollection('blog'),import.meta.glob('./posts/*.md'),High,https://docs.astro.build/en/guides/content-collections/
|
||||
5,Architecture,Define collection schemas,Zod schemas for content validation,Schema with required fields and types,No schema validation,"defineCollection({ schema: z.object({...}) })",defineCollection({}),High,https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema
|
||||
6,Routing,Use file-based routing,Create routes by adding .astro files in pages/,pages/ directory for routes,Manual route configuration,src/pages/about.astro,Custom router setup,Medium,https://docs.astro.build/en/basics/astro-pages/
|
||||
7,Routing,Dynamic routes with brackets,Use [param] for dynamic routes,Bracket notation for params,Query strings for dynamic content,pages/blog/[slug].astro,pages/blog.astro?slug=x,Medium,https://docs.astro.build/en/guides/routing/#dynamic-routes
|
||||
8,Routing,Use getStaticPaths for SSG,Generate static pages at build time,getStaticPaths for known dynamic routes,Fetch at runtime for static content,"export async function getStaticPaths() { return [...] }",No getStaticPaths with dynamic route,High,https://docs.astro.build/en/reference/api-reference/#getstaticpaths
|
||||
9,Routing,Enable SSR when needed,Server-side rendering for dynamic content,output: 'server' or 'hybrid' for dynamic,SSR for purely static sites,"export const prerender = false;",SSR for static blog,Medium,https://docs.astro.build/en/guides/server-side-rendering/
|
||||
10,Components,Keep .astro for static,Use .astro components for static content,Astro components for layout structure,React/Vue for static markup,<Layout><slot /></Layout>,<ReactLayout>{children}</ReactLayout>,High,
|
||||
11,Components,Use framework components for interactivity,React Vue Svelte for complex interactivity,Framework component with client directive,Astro component with inline scripts,<ReactCounter client:load />,<script> in .astro for complex state,Medium,https://docs.astro.build/en/guides/framework-components/
|
||||
12,Components,Pass data via props,Astro components receive props in frontmatter,Astro.props for component data,Global state for simple data,"const { title } = Astro.props;",Import global store,Low,https://docs.astro.build/en/basics/astro-components/#component-props
|
||||
13,Components,Use slots for composition,Named and default slots for flexible layouts,<slot /> for child content,Props for HTML content,<slot name="header" />,<Component header={<div>...</div>} />,Medium,https://docs.astro.build/en/basics/astro-components/#slots
|
||||
14,Components,Colocate component styles,Scoped styles in component file,<style> in same .astro file,Separate CSS files for component styles,<style> .card { } </style>,import './Card.css',Low,
|
||||
15,Styling,Use scoped styles by default,Astro scopes styles to component automatically,<style> for component-specific styles,Global styles for everything,<style> h1 { } </style> (scoped),<style is:global> for everything,Medium,https://docs.astro.build/en/guides/styling/#scoped-styles
|
||||
16,Styling,Use is:global sparingly,Global styles only when truly needed,is:global for base styles or overrides,is:global for component styles,<style is:global> body { } </style>,<style is:global> .card { } </style>,Medium,
|
||||
17,Styling,Integrate Tailwind properly,Use @astrojs/tailwind integration,Official Tailwind integration,Manual Tailwind setup,npx astro add tailwind,Manual PostCSS config,Low,https://docs.astro.build/en/guides/integrations-guide/tailwind/
|
||||
18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium,
|
||||
19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/
|
||||
20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),"import post1; import post2;",Medium,
|
||||
21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High,
|
||||
22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/
|
||||
23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"<link rel=""preload"" href=""font.woff2"" as=""font"">",No preload for critical assets,Medium,
|
||||
24,Performance,Optimize images with astro:assets,Built-in image optimization,<Image /> component for optimization,<img> for local images,"import { Image } from 'astro:assets';","<img src=""./image.jpg"">",High,https://docs.astro.build/en/guides/images/
|
||||
25,Performance,Use picture for responsive images,Multiple formats and sizes,<Picture /> for art direction,Single image size for all screens,<Picture /> with multiple sources,<Image /> with single size,Medium,
|
||||
26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"<img loading=""lazy"">",No lazy loading,Medium,
|
||||
27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High,
|
||||
28,ViewTransitions,Enable View Transitions,Smooth page transitions,<ViewTransitions /> in head,Full page reloads,"import { ViewTransitions } from 'astro:transitions';",No transition API,Medium,https://docs.astro.build/en/guides/view-transitions/
|
||||
29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"<header transition:name=""header"">",<header> without name,Low,
|
||||
30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"<video transition:persist id=""player"">",Video restarts on navigation,Medium,
|
||||
31,ViewTransitions,Add fallback for no-JS,Graceful degradation,Content works without JS,Require JS for basic navigation,Static content accessible,Broken without ViewTransitions JS,High,
|
||||
32,SEO,Use built-in SEO component,Head management for meta tags,Astro SEO integration or manual head,No meta tags,"<title>{title}</title><meta name=""description"">",No SEO tags,High,
|
||||
33,SEO,Generate sitemap,Automatic sitemap generation,@astrojs/sitemap integration,Manual sitemap maintenance,npx astro add sitemap,Hand-written sitemap.xml,Medium,https://docs.astro.build/en/guides/integrations-guide/sitemap/
|
||||
34,SEO,Add RSS feed for content,RSS for blogs and content sites,@astrojs/rss for feed generation,No RSS feed,rss() helper in pages/rss.xml.js,No feed for blog,Low,https://docs.astro.build/en/guides/rss/
|
||||
35,SEO,Use canonical URLs,Prevent duplicate content issues,Astro.url for canonical generation,"<link rel=""canonical"" href={Astro.url}>",No canonical tags,Medium,
|
||||
36,Integrations,Use official integrations,Astro's integration system,npx astro add for integrations,Manual configuration,npx astro add react,Manual React setup,Medium,https://docs.astro.build/en/guides/integrations-guide/
|
||||
37,Integrations,Configure integrations in astro.config,Centralized configuration,integrations array in config,Scattered configuration,"integrations: [react(), tailwind()]",Multiple config files,Low,
|
||||
38,Integrations,Use adapter for deployment,Platform-specific adapters,Correct adapter for host,Wrong or no adapter,@astrojs/vercel for Vercel,No adapter for SSR,High,https://docs.astro.build/en/guides/deploy/
|
||||
39,TypeScript,Enable TypeScript,Type safety for Astro projects,tsconfig.json with astro types,No TypeScript,Astro TypeScript template,JavaScript only,Medium,https://docs.astro.build/en/guides/typescript/
|
||||
40,TypeScript,Type component props,Define prop interfaces,Props interface in frontmatter,Untyped props,"interface Props { title: string }",No props typing,Medium,
|
||||
41,TypeScript,Use strict mode,Catch errors early,strict: true in tsconfig,Loose TypeScript config,strictest template,base template,Low,
|
||||
42,Markdown,Use MDX for components,Components in markdown content,@astrojs/mdx for interactive docs,Plain markdown with workarounds,<Component /> in .mdx,HTML in .md files,Medium,https://docs.astro.build/en/guides/integrations-guide/mdx/
|
||||
43,Markdown,Configure markdown plugins,Extend markdown capabilities,remarkPlugins rehypePlugins in config,Manual HTML for features,remarkPlugins: [remarkToc],Manual TOC in every post,Low,
|
||||
44,Markdown,Use frontmatter for metadata,Structured post metadata,Frontmatter with typed schema,Inline metadata,title date in frontmatter,# Title as first line,Medium,
|
||||
45,API,Use API routes for endpoints,Server endpoints in pages/api,pages/api/[endpoint].ts for APIs,External API for simple endpoints,pages/api/posts.json.ts,Separate Express server,Medium,https://docs.astro.build/en/guides/endpoints/
|
||||
46,API,Return proper responses,Use Response object,new Response() with headers,Plain objects,return new Response(JSON.stringify(data)),return data,Medium,
|
||||
47,API,Handle methods correctly,Export named method handlers,export GET POST handlers,Single default export,export const GET = async () => {},export default async () => {},Low,
|
||||
48,Security,Sanitize user content,Prevent XSS in dynamic content,set:html only for trusted content,set:html with user input,"<Fragment set:html={sanitized} />","<div set:html={userInput} />",High,
|
||||
49,Security,Use HTTPS in production,Secure connections,HTTPS for all production sites,HTTP in production,https://example.com,http://example.com,High,
|
||||
50,Security,Validate API input,Check and sanitize all input,Zod validation for API routes,Trust all input,const body = schema.parse(data),const body = await request.json(),High,
|
||||
51,Build,Use hybrid rendering,Mix static and dynamic pages,output: 'hybrid' for flexibility,All SSR or all static,prerender per-page basis,Single rendering mode,Medium,https://docs.astro.build/en/guides/server-side-rendering/#hybrid-rendering
|
||||
52,Build,Analyze bundle size,Monitor JS bundle impact,Build output shows bundle sizes,Ignore bundle growth,Check astro build output,No size monitoring,Medium,
|
||||
53,Build,Use prefetch,Preload linked pages,prefetch integration,No prefetch for navigation,npx astro add prefetch,Manual prefetch,Low,https://docs.astro.build/en/guides/prefetch/
|
||||
|
Can't render this file because it contains an unexpected character in line 14 and column 147.
|
|
|
@ -1,53 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Widgets,Use StatelessWidget when possible,Immutable widgets are simpler,StatelessWidget for static UI,StatefulWidget for everything,class MyWidget extends StatelessWidget,class MyWidget extends StatefulWidget (static),Medium,https://api.flutter.dev/flutter/widgets/StatelessWidget-class.html
|
||||
2,Widgets,Keep widgets small,Single responsibility principle,Extract widgets into smaller pieces,Large build methods,Column(children: [Header() Content()]),500+ line build method,Medium,
|
||||
3,Widgets,Use const constructors,Compile-time constants for performance,const MyWidget() when possible,Non-const for static widgets,const Text('Hello'),Text('Hello') for literals,High,https://dart.dev/guides/language/language-tour#constant-constructors
|
||||
4,Widgets,Prefer composition over inheritance,Combine widgets using children,Compose widgets,Extend widget classes,Container(child: MyContent()),class MyContainer extends Container,Medium,
|
||||
5,State,Use setState correctly,Minimal state in StatefulWidget,setState for UI state changes,setState for business logic,setState(() { _counter++; }),Complex logic in setState,Medium,https://api.flutter.dev/flutter/widgets/State/setState.html
|
||||
6,State,Avoid setState in build,Never call setState during build,setState in callbacks only,setState in build method,onPressed: () => setState(() {}),build() { setState(); },High,
|
||||
7,State,Use state management for complex apps,Provider Riverpod BLoC,State management for shared state,setState for global state,Provider.of<MyState>(context),Global setState calls,Medium,
|
||||
8,State,Prefer Riverpod or Provider,Recommended state solutions,Riverpod for new projects,InheritedWidget manually,ref.watch(myProvider),Custom InheritedWidget,Medium,https://riverpod.dev/
|
||||
9,State,Dispose resources,Clean up controllers and subscriptions,dispose() for cleanup,Memory leaks from subscriptions,@override void dispose() { controller.dispose(); },No dispose implementation,High,
|
||||
10,Layout,Use Column and Row,Basic layout widgets,Column Row for linear layouts,Stack for simple layouts,"Column(children: [Text(), Button()])",Stack for vertical list,Medium,https://api.flutter.dev/flutter/widgets/Column-class.html
|
||||
11,Layout,Use Expanded and Flexible,Control flex behavior,Expanded to fill space,Fixed sizes in flex containers,Expanded(child: Container()),Container(width: 200) in Row,Medium,
|
||||
12,Layout,Use SizedBox for spacing,Consistent spacing,SizedBox for gaps,Container for spacing only,SizedBox(height: 16),Container(height: 16),Low,
|
||||
13,Layout,Use LayoutBuilder for responsive,Respond to constraints,LayoutBuilder for adaptive layouts,Fixed sizes for responsive,LayoutBuilder(builder: (context constraints) {}),Container(width: 375),Medium,https://api.flutter.dev/flutter/widgets/LayoutBuilder-class.html
|
||||
14,Layout,Avoid deep nesting,Keep widget tree shallow,Extract deeply nested widgets,10+ levels of nesting,Extract widget to method or class,Column(Row(Column(Row(...)))),Medium,
|
||||
15,Lists,Use ListView.builder,Lazy list building,ListView.builder for long lists,ListView with children for large lists,"ListView.builder(itemCount: 100, itemBuilder: ...)",ListView(children: items.map(...).toList()),High,https://api.flutter.dev/flutter/widgets/ListView-class.html
|
||||
16,Lists,Provide itemExtent when known,Skip measurement,itemExtent for fixed height items,No itemExtent for uniform lists,ListView.builder(itemExtent: 50),ListView.builder without itemExtent,Medium,
|
||||
17,Lists,Use keys for stateful items,Preserve widget state,Key for stateful list items,No key for dynamic lists,ListTile(key: ValueKey(item.id)),ListTile without key,High,
|
||||
18,Lists,Use SliverList for custom scroll,Custom scroll effects,CustomScrollView with Slivers,Nested ListViews,CustomScrollView(slivers: [SliverList()]),ListView inside ListView,Medium,https://api.flutter.dev/flutter/widgets/SliverList-class.html
|
||||
19,Navigation,Use Navigator 2.0 or GoRouter,Declarative routing,go_router for navigation,Navigator.push for complex apps,GoRouter(routes: [...]),Navigator.push everywhere,Medium,https://pub.dev/packages/go_router
|
||||
20,Navigation,Use named routes,Organized navigation,Named routes for clarity,Anonymous routes,Navigator.pushNamed(context '/home'),Navigator.push(context MaterialPageRoute()),Low,
|
||||
21,Navigation,Handle back button (PopScope),Android back behavior and predictive back (Android 14+),Use PopScope widget (WillPopScope is deprecated),Use WillPopScope,"PopScope(canPop: false, onPopInvoked: (didPop) => ...)",WillPopScope(onWillPop: ...),High,https://api.flutter.dev/flutter/widgets/PopScope-class.html
|
||||
22,Navigation,Pass typed arguments,Type-safe route arguments,Typed route arguments,Dynamic arguments,MyRoute(id: '123'),arguments: {'id': '123'},Medium,
|
||||
23,Async,Use FutureBuilder,Async UI building,FutureBuilder for async data,setState for async,FutureBuilder(future: fetchData()),fetchData().then((d) => setState()),Medium,https://api.flutter.dev/flutter/widgets/FutureBuilder-class.html
|
||||
24,Async,Use StreamBuilder,Stream UI building,StreamBuilder for streams,Manual stream subscription,StreamBuilder(stream: myStream),stream.listen in initState,Medium,https://api.flutter.dev/flutter/widgets/StreamBuilder-class.html
|
||||
25,Async,Handle loading and error states,Complete async UI states,ConnectionState checks,Only success state,if (snapshot.connectionState == ConnectionState.waiting),No loading indicator,High,
|
||||
26,Async,Cancel subscriptions,Clean up stream subscriptions,Cancel in dispose,Memory leaks,subscription.cancel() in dispose,No subscription cleanup,High,
|
||||
27,Theming,Use ThemeData,Consistent theming,ThemeData for app theme,Hardcoded colors,Theme.of(context).primaryColor,Color(0xFF123456) everywhere,Medium,https://api.flutter.dev/flutter/material/ThemeData-class.html
|
||||
28,Theming,Use ColorScheme,Material 3 color system,ColorScheme for colors,Individual color properties,colorScheme: ColorScheme.fromSeed(),primaryColor: Colors.blue,Medium,
|
||||
29,Theming,Access theme via context,Dynamic theme access,Theme.of(context),Static theme reference,Theme.of(context).textTheme.bodyLarge,TextStyle(fontSize: 16),Medium,
|
||||
30,Theming,Support dark mode,Respect system theme,darkTheme in MaterialApp,Light theme only,"MaterialApp(theme: light, darkTheme: dark)",MaterialApp(theme: light),Medium,
|
||||
31,Animation,Use implicit animations,Simple animations,AnimatedContainer AnimatedOpacity,Explicit for simple transitions,AnimatedContainer(duration: Duration()),AnimationController for fade,Low,https://api.flutter.dev/flutter/widgets/AnimatedContainer-class.html
|
||||
32,Animation,Use AnimationController for complex,Fine-grained control,AnimationController with Ticker,Implicit for complex sequences,AnimationController(vsync: this),AnimatedContainer for staggered,Medium,
|
||||
33,Animation,Dispose AnimationControllers,Clean up animation resources,dispose() for controllers,Memory leaks,controller.dispose() in dispose,No controller disposal,High,
|
||||
34,Animation,Use Hero for transitions,Shared element transitions,Hero for navigation animations,Manual shared element,Hero(tag: 'image' child: Image()),Custom shared element animation,Low,https://api.flutter.dev/flutter/widgets/Hero-class.html
|
||||
35,Forms,Use Form widget,Form validation,Form with GlobalKey,Individual validation,Form(key: _formKey child: ...),TextField without Form,Medium,https://api.flutter.dev/flutter/widgets/Form-class.html
|
||||
36,Forms,Use TextEditingController,Control text input,Controller for text fields,onChanged for all text,final controller = TextEditingController(),onChanged: (v) => setState(),Medium,
|
||||
37,Forms,Validate on submit,Form validation flow,_formKey.currentState!.validate(),Skip validation,if (_formKey.currentState!.validate()),Submit without validation,High,
|
||||
38,Forms,Dispose controllers,Clean up text controllers,dispose() for controllers,Memory leaks,controller.dispose() in dispose,No controller disposal,High,
|
||||
39,Performance,Use const widgets,Reduce rebuilds,const for static widgets,No const for literals,const Icon(Icons.add),Icon(Icons.add),High,
|
||||
40,Performance,Avoid rebuilding entire tree,Minimal rebuild scope,Isolate changing widgets,setState on parent,Consumer only around changing widget,setState on root widget,High,
|
||||
41,Performance,Use RepaintBoundary,Isolate repaints,RepaintBoundary for animations,Full screen repaints,RepaintBoundary(child: AnimatedWidget()),Animation without boundary,Medium,https://api.flutter.dev/flutter/widgets/RepaintBoundary-class.html
|
||||
42,Performance,Profile with DevTools,Measure before optimizing,Flutter DevTools profiling,Guess at performance,DevTools performance tab,Optimize without measuring,Medium,https://docs.flutter.dev/tools/devtools
|
||||
43,Accessibility,Use Semantics widget,Screen reader support,Semantics for accessibility,Missing accessibility info,Semantics(label: 'Submit button'),GestureDetector without semantics,High,https://api.flutter.dev/flutter/widgets/Semantics-class.html
|
||||
44,Accessibility,Support large fonts,MediaQuery text scaling,MediaQuery.textScaleFactor,Fixed font sizes,style: Theme.of(context).textTheme,TextStyle(fontSize: 14),High,
|
||||
45,Accessibility,Test with screen readers,TalkBack and VoiceOver,Test accessibility regularly,Skip accessibility testing,Regular TalkBack testing,No screen reader testing,High,
|
||||
46,Testing,Use widget tests,Test widget behavior,WidgetTester for UI tests,Unit tests only,testWidgets('...' (tester) async {}),Only test() for UI,Medium,https://docs.flutter.dev/testing
|
||||
47,Testing,Use integration tests,Full app testing,integration_test package,Manual testing only,IntegrationTestWidgetsFlutterBinding,Manual E2E testing,Medium,
|
||||
48,Testing,Mock dependencies,Isolate tests,Mockito or mocktail,Real dependencies in tests,when(mock.method()).thenReturn(),Real API calls in tests,Medium,
|
||||
49,Platform,Use Platform checks,Platform-specific code,Platform.isIOS Platform.isAndroid,Same code for all platforms,if (Platform.isIOS) {},Hardcoded iOS behavior,Medium,
|
||||
50,Platform,Use kIsWeb for web,Web platform detection,kIsWeb for web checks,Platform for web,if (kIsWeb) {},Platform.isWeb (doesn't exist),Medium,
|
||||
51,Packages,Use pub.dev packages,Community packages,Popular maintained packages,Custom implementations,cached_network_image,Custom image cache,Medium,https://pub.dev/
|
||||
52,Packages,Check package quality,Quality before adding,Pub points and popularity,Any package without review,100+ pub points,Unmaintained packages,Medium,
|
||||
|
|
|
@ -1,56 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Animation,Use Tailwind animate utilities,Built-in animations are optimized and respect reduced-motion,Use animate-pulse animate-spin animate-ping,Custom @keyframes for simple effects,animate-pulse,@keyframes pulse {...},Medium,https://tailwindcss.com/docs/animation
|
||||
2,Animation,Limit bounce animations,Continuous bounce is distracting and causes motion sickness,Use animate-bounce sparingly on CTAs only,Multiple bounce animations on page,Single CTA with animate-bounce,5+ elements with animate-bounce,High,
|
||||
3,Animation,Transition duration,Use appropriate transition speeds for UI feedback,duration-150 to duration-300 for UI,duration-1000 or longer for UI elements,transition-all duration-200,transition-all duration-1000,Medium,https://tailwindcss.com/docs/transition-duration
|
||||
4,Animation,Hover transitions,Add smooth transitions on hover state changes,Add transition class with hover states,Instant hover changes without transition,hover:bg-gray-100 transition-colors,hover:bg-gray-100 (no transition),Low,
|
||||
5,Z-Index,Use Tailwind z-* scale,Consistent stacking context with predefined scale,z-0 z-10 z-20 z-30 z-40 z-50,Arbitrary z-index values,z-50 for modals,z-[9999],Medium,https://tailwindcss.com/docs/z-index
|
||||
6,Z-Index,Fixed elements z-index,Fixed navigation and modals need explicit z-index,z-50 for nav z-40 for dropdowns,Relying on DOM order for stacking,fixed top-0 z-50,fixed top-0 (no z-index),High,
|
||||
7,Z-Index,Negative z-index for backgrounds,Use negative z-index for decorative backgrounds,z-[-1] for background elements,Positive z-index for backgrounds,-z-10 for decorative,z-10 for background,Low,
|
||||
8,Layout,Container max-width,Limit content width for readability,max-w-7xl mx-auto for main content,Full-width content on large screens,max-w-7xl mx-auto px-4,w-full (no max-width),Medium,https://tailwindcss.com/docs/container
|
||||
9,Layout,Responsive padding,Adjust padding for different screen sizes,px-4 md:px-6 lg:px-8,Same padding all sizes,px-4 sm:px-6 lg:px-8,px-8 (same all sizes),Medium,
|
||||
10,Layout,Grid gaps,Use consistent gap utilities for spacing,gap-4 gap-6 gap-8,Margins on individual items,grid gap-6,grid with mb-4 on each item,Medium,https://tailwindcss.com/docs/gap
|
||||
11,Layout,Flexbox alignment,Use flex utilities for alignment,items-center justify-between,Multiple nested wrappers,flex items-center justify-between,Nested divs for alignment,Low,
|
||||
12,Images,Aspect ratio,Maintain consistent image aspect ratios,aspect-video aspect-square,No aspect ratio on containers,aspect-video rounded-lg,No aspect control,Medium,https://tailwindcss.com/docs/aspect-ratio
|
||||
13,Images,Object fit,Control image scaling within containers,object-cover object-contain,Stretched distorted images,object-cover w-full h-full,No object-fit,Medium,https://tailwindcss.com/docs/object-fit
|
||||
14,Images,Lazy loading,Defer loading of off-screen images,loading='lazy' on images,All images eager load,<img loading='lazy'>,<img> without lazy,High,
|
||||
15,Images,Responsive images,Serve appropriate image sizes,srcset and sizes attributes,Same large image all devices,srcset with multiple sizes,4000px image everywhere,High,
|
||||
16,Typography,Prose plugin,Use @tailwindcss/typography for rich text,prose prose-lg for article content,Custom styles for markdown,prose prose-lg max-w-none,Custom text styling,Medium,https://tailwindcss.com/docs/typography-plugin
|
||||
17,Typography,Line height,Use appropriate line height for readability,leading-relaxed for body text,Default tight line height,leading-relaxed (1.625),leading-none or leading-tight,Medium,https://tailwindcss.com/docs/line-height
|
||||
18,Typography,Font size scale,Use consistent text size scale,text-sm text-base text-lg text-xl,Arbitrary font sizes,text-lg,text-[17px],Low,https://tailwindcss.com/docs/font-size
|
||||
19,Typography,Text truncation,Handle long text gracefully,truncate or line-clamp-*,Overflow breaking layout,line-clamp-2,No overflow handling,Medium,https://tailwindcss.com/docs/text-overflow
|
||||
20,Colors,Opacity utilities,Use color opacity utilities,bg-black/50 text-white/80,Separate opacity class,bg-black/50,bg-black opacity-50,Low,https://tailwindcss.com/docs/background-color
|
||||
21,Colors,Dark mode,Support dark mode with dark: prefix,dark:bg-gray-900 dark:text-white,No dark mode support,dark:bg-gray-900,Only light theme,Medium,https://tailwindcss.com/docs/dark-mode
|
||||
22,Colors,Semantic colors,Use semantic color naming in config,primary secondary danger success,Generic color names in components,bg-primary,bg-blue-500 everywhere,Medium,
|
||||
23,Spacing,Consistent spacing scale,Use Tailwind spacing scale consistently,p-4 m-6 gap-8,Arbitrary pixel values,p-4 (1rem),p-[15px],Low,https://tailwindcss.com/docs/customizing-spacing
|
||||
24,Spacing,Negative margins,Use sparingly for overlapping effects,-mt-4 for overlapping elements,Negative margins for layout fixing,-mt-8 for card overlap,-m-2 to fix spacing issues,Medium,
|
||||
25,Spacing,Space between,Use space-y-* for vertical lists,space-y-4 on flex/grid column,Margin on each child,space-y-4,Each child has mb-4,Low,https://tailwindcss.com/docs/space
|
||||
26,Forms,Focus states,Always show focus indicators,focus:ring-2 focus:ring-blue-500,Remove focus outline,focus:ring-2 focus:ring-offset-2,focus:outline-none (no replacement),High,
|
||||
27,Forms,Input sizing,Consistent input dimensions,h-10 px-3 for inputs,Inconsistent input heights,h-10 w-full px-3,Various heights per input,Medium,
|
||||
28,Forms,Disabled states,Clear disabled styling,disabled:opacity-50 disabled:cursor-not-allowed,No disabled indication,disabled:opacity-50,Same style as enabled,Medium,
|
||||
29,Forms,Placeholder styling,Style placeholder text appropriately,placeholder:text-gray-400,Dark placeholder text,placeholder:text-gray-400,Default dark placeholder,Low,
|
||||
30,Responsive,Mobile-first approach,Start with mobile styles and add breakpoints,Default mobile + md: lg: xl:,Desktop-first approach,text-sm md:text-base,text-base max-md:text-sm,Medium,https://tailwindcss.com/docs/responsive-design
|
||||
31,Responsive,Breakpoint testing,Test at standard breakpoints,320 375 768 1024 1280 1536,Only test on development device,Test all breakpoints,Single device testing,High,
|
||||
32,Responsive,Hidden/shown utilities,Control visibility per breakpoint,hidden md:block,Different content per breakpoint,hidden md:flex,Separate mobile/desktop components,Low,https://tailwindcss.com/docs/display
|
||||
33,Buttons,Button sizing,Consistent button dimensions,px-4 py-2 or px-6 py-3,Inconsistent button sizes,px-4 py-2 text-sm,Various padding per button,Medium,
|
||||
34,Buttons,Touch targets,Minimum 44px touch target on mobile,min-h-[44px] on mobile,Small buttons on mobile,min-h-[44px] min-w-[44px],h-8 w-8 on mobile,High,
|
||||
35,Buttons,Loading states,Show loading feedback,disabled + spinner icon,Clickable during loading,<Button disabled><Spinner/></Button>,Button without loading state,High,
|
||||
36,Buttons,Icon buttons,Accessible icon-only buttons,aria-label on icon buttons,Icon button without label,<button aria-label='Close'><XIcon/></button>,<button><XIcon/></button>,High,
|
||||
37,Cards,Card structure,Consistent card styling,rounded-lg shadow-md p-6,Inconsistent card styles,rounded-2xl shadow-lg p-6,Mixed card styling,Low,
|
||||
38,Cards,Card hover states,Interactive cards should have hover feedback,hover:shadow-lg transition-shadow,No hover on clickable cards,hover:shadow-xl transition-shadow,Static cards that are clickable,Medium,
|
||||
39,Cards,Card spacing,Consistent internal card spacing,space-y-4 for card content,Inconsistent internal spacing,space-y-4 or p-6,Mixed mb-2 mb-4 mb-6,Low,
|
||||
40,Accessibility,Screen reader text,Provide context for screen readers,sr-only for hidden labels,Missing context for icons,<span class='sr-only'>Close menu</span>,No label for icon button,High,https://tailwindcss.com/docs/screen-readers
|
||||
41,Accessibility,Focus visible,Show focus only for keyboard users,focus-visible:ring-2,Focus on all interactions,focus-visible:ring-2,focus:ring-2 (shows on click too),Medium,
|
||||
42,Accessibility,Reduced motion,Respect user motion preferences,motion-reduce:animate-none,Ignore motion preferences,motion-reduce:transition-none,No reduced motion support,High,https://tailwindcss.com/docs/hover-focus-and-other-states#prefers-reduced-motion
|
||||
43,Performance,Configure content paths,Tailwind needs to know where classes are used,Use 'content' array in config,Use deprecated 'purge' option (v2),"content: ['./src/**/*.{js,ts,jsx,tsx}']",purge: [...],High,https://tailwindcss.com/docs/content-configuration
|
||||
44,Performance,JIT mode,Use JIT for faster builds and smaller bundles,JIT enabled (default in v3),Full CSS in development,Tailwind v3 defaults,Tailwind v2 without JIT,Medium,
|
||||
45,Performance,Avoid @apply bloat,Use @apply sparingly,Direct utilities in HTML,Heavy @apply usage,class='px-4 py-2 rounded',@apply px-4 py-2 rounded;,Low,https://tailwindcss.com/docs/reusing-styles
|
||||
46,Plugins,Official plugins,Use official Tailwind plugins,@tailwindcss/forms typography aspect-ratio,Custom implementations,@tailwindcss/forms,Custom form reset CSS,Medium,https://tailwindcss.com/docs/plugins
|
||||
47,Plugins,Custom utilities,Create utilities for repeated patterns,Custom utility in config,Repeated arbitrary values,Custom shadow utility,"shadow-[0_4px_20px_rgba(0,0,0,0.1)] everywhere",Medium,
|
||||
48,Layout,Container Queries,Use @container for component-based responsiveness,Use @container and @lg: etc.,Media queries for component internals,@container @lg:grid-cols-2,@media (min-width: ...) inside component,Medium,https://github.com/tailwindlabs/tailwindcss-container-queries
|
||||
49,Interactivity,Group and Peer,Style based on parent/sibling state,group-hover peer-checked,JS for simple state interactions,group-hover:text-blue-500,onMouseEnter={() => setHover(true)},Low,https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state
|
||||
50,Customization,Arbitrary Values,Use [] for one-off values,w-[350px] for specific needs,Creating config for single use,top-[117px] (if strictly needed),style={{ top: '117px' }},Low,https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values
|
||||
51,Colors,Theme color variables,Define colors in Tailwind theme and use directly,bg-primary text-success border-cta,bg-[var(--color-primary)] text-[var(--color-success)],bg-primary,bg-[var(--color-primary)],Medium,https://tailwindcss.com/docs/customizing-colors
|
||||
52,Colors,Use bg-linear-to-* for gradients,Tailwind v4 uses bg-linear-to-* syntax for gradients,bg-linear-to-r bg-linear-to-b,bg-gradient-to-* (deprecated in v4),bg-linear-to-r from-blue-500 to-purple-500,bg-gradient-to-r from-blue-500 to-purple-500,Medium,https://tailwindcss.com/docs/background-image
|
||||
53,Layout,Use shrink-0 shorthand,Shorter class name for flex-shrink-0,shrink-0 shrink,flex-shrink-0 flex-shrink,shrink-0,flex-shrink-0,Low,https://tailwindcss.com/docs/flex-shrink
|
||||
54,Layout,Use size-* for square dimensions,Single utility for equal width and height,size-4 size-8 size-12,Separate h-* w-* for squares,size-6,h-6 w-6,Low,https://tailwindcss.com/docs/size
|
||||
55,Images,SVG explicit dimensions,Add width/height attributes to SVGs to prevent layout shift before CSS loads,<svg class='size-6' width='24' height='24'>,SVG without explicit dimensions,<svg class='size-6' width='24' height='24'>,<svg class='size-6'>,High,
|
||||
|
|
|
@ -1,76 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Application,Start UI from Application subclass,JavaFX apps should bootstrap the primary Stage through Application.start(),Extend Application and configure Scene in start(),Create UI from a random main method without launching JavaFX,"public class App extends Application { public void start(Stage stage) { stage.setScene(new Scene(root)); stage.show(); } }",new Stage().show(),High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/application/Application.html
|
||||
2,Threading,Keep work off the FX Application Thread,Long-running work blocks rendering and input when executed on the UI thread,Use Task or Service for background work,Run network database or file work in button handlers,"Task<List<Item>> task = new Task<>() { protected List<Item> call() { return repo.load(); } }; new Thread(task).start();",loadLargeFile(); table.setItems(items);,High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/concurrent/Task.html
|
||||
3,Threading,Update UI only on FX thread,Scene graph changes must happen on the JavaFX Application Thread,Use bindings task handlers or Platform.runLater for UI changes,Mutate controls directly from background threads,"task.setOnSucceeded(e -> table.setItems(FXCollections.observableArrayList(task.getValue())));",new Thread(() -> label.setText("Done")).start(),High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/application/Platform.html
|
||||
4,Threading,Bind progress to background tasks,Task exposes progress and message properties for responsive feedback,Bind ProgressBar and Label to task properties,Poll progress manually or leave users without feedback,"progress.progressProperty().bind(task.progressProperty()); status.textProperty().bind(task.messageProperty());",while(running) progress.setProgress(x);,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/concurrent/Task.html
|
||||
5,FXML,Use FXML for stable declarative layouts,FXML keeps view structure readable for screens with many controls,Place layout in FXML and behavior in controller,Build large screens entirely in one Java method,"<VBox spacing=""12"" xmlns:fx=""http://javafx.com/fxml"" fx:controller=""app.MainController"">",VBox root = new VBox(); root.getChildren().add(... 200 lines ...);,Medium,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXMLLoader.html
|
||||
6,FXML,Keep controllers focused on view behavior,Controllers should coordinate controls and delegate business logic to services,Inject services or call application services from controller,Put database queries and domain rules directly in controller,"public void save() { customerService.save(form.toCommand()); }",public void save() { DriverManager.getConnection(...); },High,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXML.html
|
||||
7,FXML,Use fx:id for injected controls,FXML controls need stable fx:id values that match controller fields,Annotate fields with @FXML and keep ids descriptive,Look up controls by CSS selector for normal wiring,"@FXML private TableView<Customer> customerTable;",root.lookup("#customerTable"),Medium,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXML.html
|
||||
8,FXML,Fail fast when loading FXML,FXML load errors should surface during screen creation with clear context,Load resources with getResource and handle IOException explicitly,Swallow loader errors and show a blank scene,"URL view = getClass().getResource(\"/views/main.fxml\"); Parent root = FXMLLoader.load(view);",try { FXMLLoader.load(url); } catch(Exception ignored) {},High,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXMLLoader.html
|
||||
9,CSS,Style with style classes,JavaFX CSS works best through reusable styleClass names,Add semantic style classes and define them in CSS,Set long inline style strings throughout code,"button.getStyleClass().add(\"primary-action\");",".setStyle(\"-fx-background-color: #2563eb; -fx-padding: 12; ...\")",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html
|
||||
10,CSS,Use design tokens through looked-up colors,Looked-up colors keep palettes consistent across controls,Define named colors on root and reuse them in CSS,Repeat hex values in every selector,".root { -brand-primary: #2563eb; } .button.primary { -fx-background-color: -brand-primary; }",".save { -fx-background-color: #2563eb; } .link { -fx-text-fill: #2563eb; }",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html
|
||||
11,CSS,Avoid overusing inline effects,Expensive CSS effects and shadows can hurt desktop UI responsiveness,Use subtle shadows only on important elevated surfaces,Apply blur drop shadow and glow to every node,".dialog-card { -fx-effect: dropshadow(gaussian, rgba(0,0,0,.18), 16, 0, 0, 4); }",".table-row-cell { -fx-effect: dropshadow(gaussian, black, 20, .5, 0, 0); }",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/effect/package-summary.html
|
||||
12,Layout,Choose layout panes by responsibility,Each pane solves a different layout problem and should be selected intentionally,Use BorderPane for app shell GridPane for forms VBox/HBox for simple stacks,Use absolute positioning for resizable app screens,"BorderPane shell = new BorderPane(); shell.setTop(toolbar); shell.setCenter(content);",Pane root = new Pane(); button.setLayoutX(742);,High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/layout/package-summary.html
|
||||
13,Layout,Prefer constraints over fixed coordinates,Responsive JavaFX layouts depend on constraints and grow priorities,Use hgrow vgrow column constraints and alignment,Hard-code pixel positions and sizes,"GridPane.setHgrow(nameField, Priority.ALWAYS); column.setPercentWidth(50);",field.setPrefWidth(328); field.setLayoutX(120);,High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/layout/GridPane.html
|
||||
14,Layout,Set sensible min pref and max sizes,Controls should resize predictably across windows and DPI settings,Use Region.USE_COMPUTED_SIZE and max widths intentionally,Lock every control to fixed width and height,"button.setMaxWidth(Double.MAX_VALUE); VBox.setVgrow(table, Priority.ALWAYS);","button.setMinSize(96, 32); button.setMaxSize(96, 32);",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/layout/Region.html
|
||||
15,Layout,Use spacing and padding consistently,Desktop UI needs scan-friendly rhythm and clear grouping,Set spacing padding and Insets through shared constants or CSS,Use inconsistent ad hoc gaps between controls,"form.setHgap(12); form.setVgap(10); form.setPadding(new Insets(16));",box.setSpacing(3); other.setSpacing(17);,Low,https://openjfx.io/javadoc/21/javafx.graphics/javafx/geometry/Insets.html
|
||||
16,Controls,Use ObservableList for list controls,TableView ListView and ComboBox update automatically from observable collections,Back controls with FXCollections.observableArrayList(),Mutate plain lists and manually refresh controls,"ObservableList<Customer> rows = FXCollections.observableArrayList(); table.setItems(rows);",List<Customer> rows = new ArrayList<>(); table.setItems((ObservableList) rows);,High,https://openjfx.io/javadoc/21/javafx.base/javafx/collections/ObservableList.html
|
||||
17,Controls,Configure TableView cell value factories with properties,Table columns should observe stable JavaFX properties for updates,Expose StringProperty ObjectProperty or use ReadOnlyObjectWrapper,Return transient strings without observable support,"nameCol.setCellValueFactory(data -> data.getValue().nameProperty());",nameCol.setCellValueFactory(data -> new SimpleStringProperty(data.getValue().toString()));,Medium,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/TableColumn.html
|
||||
18,Controls,Use cell factories for custom rendering,Custom table or list visuals belong in reusable cell factories,Override updateItem and handle empty state,Place complex Nodes directly in model objects,"col.setCellFactory(c -> new TableCell<>() { protected void updateItem(Status s, boolean empty) { super.updateItem(s, empty); setText(empty ? null : s.label()); } });",row.setBadge(new Label("Active"));,Medium,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/Cell.html
|
||||
19,Controls,Virtualized controls are for large data,TableView ListView TreeView virtualize cells and outperform manual node lists,Use TableView or ListView for hundreds of rows,Create hundreds of HBoxes inside a VBox,"ListView<Item> list = new ListView<>(items);",items.forEach(i -> vbox.getChildren().add(new ItemRow(i)));,High,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/ListView.html
|
||||
20,Controls,Handle empty states explicitly,Empty tables and lists need visible guidance or next actions,Set placeholder nodes for empty data views,Leave blank white areas that look broken,"table.setPlaceholder(new Label(\"No customers match this filter\"));",table.setPlaceholder(null);,Low,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/TableView.html
|
||||
21,Binding,Use property binding for derived UI state,JavaFX binding reduces imperative synchronization bugs,Bind disabled visible text and progress properties to source state,Manually update every dependent control in each event handler,"saveButton.disableProperty().bind(form.validProperty().not());",if(!valid) saveButton.setDisable(true);,High,https://openjfx.io/javadoc/21/javafx.base/javafx/beans/binding/Bindings.html
|
||||
22,Binding,Unbind before manual updates,Bound properties cannot be set directly without errors,Call unbind when switching from bound to manual state,Set a bound property directly,"label.textProperty().unbind(); label.setText(\"Ready\");",label.textProperty().bind(task.messageProperty()); label.setText(\"Ready\");,Medium,https://openjfx.io/javadoc/21/javafx.base/javafx/beans/property/Property.html
|
||||
23,Binding,Use listeners sparingly,Bindings express simple relationships more clearly than listeners,Use listeners for side effects and bindings for values,Create listener chains for simple computed text,"totalLabel.textProperty().bind(Bindings.format(""Total: %d"", total));","count.addListener((o, a, b) -> totalLabel.setText(""Total: "" + b));",Low,https://openjfx.io/javadoc/21/javafx.base/javafx/beans/value/ObservableValue.html
|
||||
24,Events,Use action handlers for commands,Buttons and menu items should route to named command methods,Use setOnAction or @FXML handler methods with clear names,Put large lambdas inline for complex operations,"@FXML private void handleSave(ActionEvent event) { saveCustomer(); }",saveButton.setOnAction(e -> { validate(); transform(); query(); save(); refresh(); });,Medium,https://openjfx.io/javadoc/21/javafx.base/javafx/event/ActionEvent.html
|
||||
25,Events,Use event filters for global shortcuts,Filters can intercept keyboard events before child controls consume them,Register accelerators or filters at Scene level,Add duplicate key handlers to every control,"scene.getAccelerators().put(new KeyCodeCombination(KeyCode.S, SHORTCUT_DOWN), this::save);",nameField.setOnKeyPressed(...); table.setOnKeyPressed(...);,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/Scene.html
|
||||
26,Accessibility,Connect labels to inputs,Accessible desktop forms need labels associated with controls,Use Label.setLabelFor and clear prompt text,Use placeholder-only labels,"nameLabel.setLabelFor(nameField); nameField.setPromptText(\"Jane Doe\");",nameField.setPromptText(\"Name\");,High,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/Label.html
|
||||
27,Accessibility,Expose accessible text for icon buttons,Icon-only controls need names for screen readers and tooltips,Set accessibleText and Tooltip on icon buttons,Use unlabeled graphic-only buttons,"button.setAccessibleText(""Refresh""); button.setTooltip(new Tooltip(""Refresh""));","new Button("""", refreshIcon)",High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/AccessibleRole.html
|
||||
28,Accessibility,Keep keyboard focus visible,Desktop users rely on focus traversal and visible focus indicators,Preserve focus rings and tab order,Remove outlines without alternative focus state,".button:focused { -fx-border-color: -brand-focus; -fx-border-width: 2; }",".button:focused { -fx-background-insets: 0; }",High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/Node.html
|
||||
29,Accessibility,Use mnemonics for menu and form workflows,Mnemonics make desktop workflows faster and more accessible,Enable mnemonicParsing and choose unique mnemonic letters,Ignore keyboard alternatives for frequent actions,"saveButton.setMnemonicParsing(true); saveButton.setText(""_Save"");","saveButton.setText(""Save"");",Low,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/Labeled.html
|
||||
30,Validation,Show validation near the field,Users should not hunt for form errors in desktop dialogs,Bind error labels or pseudo classes next to invalid controls,Show only a generic alert after submit,"field.pseudoClassStateChanged(PseudoClass.getPseudoClass(""invalid""), !valid);","new Alert(ERROR, ""Invalid input"").show();",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/css/PseudoClass.html
|
||||
31,Validation,Use TextFormatter for constrained input,TextFormatter prevents invalid edits before they enter the model,Attach TextFormatter for numeric dates and masks,Parse and reject invalid text only after submit,"amountField.setTextFormatter(new TextFormatter<>(new IntegerStringConverter(), 0, c -> c.getControlNewText().matches(""\\d*"") ? c : null));",Integer.parseInt(amountField.getText());,Medium,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/TextFormatter.html
|
||||
32,Dialogs,Use modal ownership for dialogs,Dialogs should block only the relevant window and return structured results,Set owner modality and use showAndWait,Open unmanaged windows for confirmations,"dialog.initOwner(stage); dialog.initModality(Modality.WINDOW_MODAL); Optional<ButtonType> result = dialog.showAndWait();",new Stage().show();,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/stage/Modality.html
|
||||
33,Dialogs,Prefer custom DialogPane over ad hoc stages,Dialog gives consistent buttons focus and result handling,Use Dialog<T> for forms confirmations and wizards,Build every modal as a new Stage manually,"Dialog<Customer> dialog = new Dialog<>(); dialog.getDialogPane().getButtonTypes().addAll(OK, CANCEL);",Stage modal = new Stage(); modal.setScene(new Scene(new VBox()));,Low,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/Dialog.html
|
||||
34,Images,Load images as resources,Packaged apps need resources resolved from the classpath or module path,Use getResourceAsStream for bundled assets,Use absolute local file paths in production UI,"new Image(getClass().getResourceAsStream(""/images/logo.png""));","new Image(""file:/Users/me/Desktop/logo.png"")",High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/image/Image.html
|
||||
35,Images,Use background loading for large images,Large image decoding can pause UI startup,Use Image(url true) or a background Task for heavy assets,Load many full-size images synchronously during startup,"Image preview = new Image(url, true);",gallery.add(new Image(url));,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/image/Image.html
|
||||
36,Animation,Keep animations purposeful and short,Desktop UI animations should clarify state changes without delaying work,Use 150-250ms transitions for reveal hover and selection,Animate every layout change with long timelines,"FadeTransition ft = new FadeTransition(Duration.millis(180), pane); ft.setToValue(1);","new Timeline(new KeyFrame(Duration.seconds(2), ...)).play();",Low,https://openjfx.io/javadoc/21/javafx.graphics/javafx/animation/package-summary.html
|
||||
37,Animation,Respect reduced-motion contexts where possible,Some users experience motion sensitivity in desktop apps,Provide a setting to disable decorative animations,Make animation required for comprehension,"if (settings.reducedMotion()) pane.setOpacity(1); else fade.play();",alwaysSpin.play();,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/animation/Animation.html
|
||||
38,Performance,Avoid recreating scenes for small state changes,Replacing whole scenes loses state and can flicker,Swap center content or update view models,Rebuild the entire Stage for every navigation click,"shell.setCenter(customerView);",stage.setScene(new Scene(loadMainAgain()));,Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/Scene.html
|
||||
39,Performance,Reuse loaded views when appropriate,FXML loading and CSS application are not free,Cache stable views or controllers for frequent navigation,Reload heavyweight screens repeatedly without need,"Node settings = viewCache.computeIfAbsent(""settings"", this::loadSettings);","button.setOnAction(e -> shell.setCenter(loadFxml(""settings.fxml"")));",Low,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXMLLoader.html
|
||||
40,Performance,Batch observable list changes,Many single-item updates can cause repeated layout and sort work,Use setAll or addAll for bulk replacement,Loop add items one by one to visible lists,"items.setAll(repository.findAll());",for(Item item : loaded) items.add(item);,Medium,https://openjfx.io/javadoc/21/javafx.base/javafx/collections/ObservableList.html
|
||||
41,Architecture,Use view models for complex screens,View models keep controller state testable and separate from controls,Expose JavaFX properties from a screen model,Store all state only inside controls,"customerNameField.textProperty().bindBidirectional(viewModel.nameProperty());",String name = customerNameField.getText(); // everywhere,Medium,https://openjfx.io/javadoc/21/javafx.base/javafx/beans/property/package-summary.html
|
||||
42,Architecture,Separate navigation from feature controllers,Feature controllers should not know how every screen is launched,Use a navigator or application shell service,Call FXMLLoader for unrelated screens from each controller,"navigator.showCustomers();",FXMLLoader.load(getClass().getResource(\"/views/admin.fxml\"));,Medium,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXMLLoader.html
|
||||
43,Modules,Declare required JavaFX modules,Modular JavaFX apps must require the modules they use,Add javafx.controls javafx.fxml and opens controller packages,Depend on classpath accidents only,"module app { requires javafx.controls; requires javafx.fxml; opens app.ui to javafx.fxml; }",module app { requires javafx.controls; },High,https://openjfx.io/openjfx-docs/#modular
|
||||
44,Packaging,Use jlink or jpackage for desktop delivery,JavaFX apps should ship with the runtime they need,Package a runtime image or native installer,Ask end users to install matching Java and JavaFX manually,"jpackage --name MyApp --module app/app.Main --runtime-image build/image",java -jar app.jar,Medium,https://openjfx.io/openjfx-docs/#modular
|
||||
45,Testing,Use TestFX for interaction tests,UI flows need automated coverage beyond controller unit tests,Write TestFX tests for key forms dialogs and navigation,Only manually click through releases,"clickOn(""#nameField"").write(""Alice""); clickOn(""Save""); verifyThat(""Saved"", isVisible());",// manual QA only,Medium,https://github.com/TestFX/TestFX
|
||||
46,Theme,Use AtlantaFX as the enterprise theme baseline,AtlantaFX provides modern JavaFX themes while preserving standard controls,Use AtlantaFX user-agent stylesheet plus a small app CSS layer,Rewrite every standard control style from scratch,"Application.setUserAgentStylesheet(new PrimerLight().getUserAgentStylesheet());",scene.getStylesheets().add("/css/huge-custom-theme.css");,High,https://mkpaz.github.io/atlantafx/
|
||||
47,Theme,Prefer Primer for enterprise applications,PrimerLight and PrimerDark are neutral enough for dense business workflows,Use PrimerLight as default and PrimerDark for dark mode,Use Dracula or Cupertino as the default enterprise theme,"Application.setUserAgentStylesheet(new PrimerLight().getUserAgentStylesheet());",Application.setUserAgentStylesheet(new Dracula().getUserAgentStylesheet());,Medium,https://mkpaz.github.io/atlantafx/themes/
|
||||
48,Theme,Layer brand CSS after AtlantaFX,Application CSS should customize brand tokens and business states after the base theme,Add app.css to the Scene after setting AtlantaFX,Edit AtlantaFX source CSS directly,"scene.getStylesheets().add(getClass().getResource(""/css/app.css"").toExternalForm());",modify atlantafx-base CSS files,High,https://mkpaz.github.io/atlantafx/theming/
|
||||
49,Theme,Use looked-up colors as enterprise tokens,JavaFX looked-up colors keep brand and semantic colors reusable across controls,Define app-primary app-success app-warning app-danger on root,Repeat hex values in every selector,".root { -app-primary: #2563eb; -app-danger: #dc2626; }",".save { -fx-background-color: #2563eb; } .link { -fx-text-fill: #2563eb; }",High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html
|
||||
50,Theme,Keep theme switching centralized,Dark mode switching should not be scattered across controllers,Use a ThemeService that sets user-agent stylesheet and app CSS variants,Let each controller decide its own theme,themeService.apply(ThemeMode.DARK);,if(dark) button.setStyle(...);,Medium,https://mkpaz.github.io/atlantafx/
|
||||
51,Theme,Validate contrast for business status colors,Enterprise screens use status colors heavily and need readable contrast,Check text on success warning danger and selected row backgrounds,Assume brand colors are accessible,".status-danger { -fx-text-fill: -app-danger; }",red text on dark red background,High,https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
|
||||
52,Theme,Use AtlantaFX style classes before custom CSS,AtlantaFX exposes utility styles that reduce custom CSS drift,Prefer Styles constants or documented style classes,Create one-off class names for every button variant,saveButton.getStyleClass().add(Styles.ACCENT);,"saveButton.getStyleClass().add(""blue-button-42"");",Medium,https://mkpaz.github.io/atlantafx/
|
||||
53,Theme,Treat AtlantaFX as a base not the whole design system,AtlantaFX modernizes controls but enterprise UX still needs layout density and workflow rules,Define app shell navigation table density form and validation conventions,Assume theme choice alone solves enterprise usability,"root.getStyleClass().add(""enterprise-shell"");",only set PrimerLight and stop,High,https://mkpaz.github.io/atlantafx/
|
||||
54,Icons,Use Ikonli for consistent enterprise icons,Icon fonts integrate cleanly with JavaFX controls and avoid emoji-style UI,Use FontIcon with semantic style classes,Use emoji as toolbar or menu icons,"Button refresh = new Button(""Refresh"", new FontIcon(""mdi2r-refresh""));",new Button("Refresh"),Medium,https://kordamp.org/ikonli/
|
||||
55,Components,Use AtlantaFX controls for common app affordances,AtlantaFX provides useful controls such as Card Message ModalPane Popover and ToggleSwitch,Use built-in AtlantaFX controls before adding another dependency,Add ControlsFX for components AtlantaFX already covers,"Message message = new Message(""Saved"", ""Customer updated successfully"");","new Label(""Saved"") with ad hoc styling",Medium,https://mkpaz.github.io/atlantafx/
|
||||
56,Components,Add ControlsFX only for missing enterprise controls,ControlsFX is useful for specialized controls but should stay optional,Use ControlsFX for SpreadsheetView PropertySheet CheckComboBox or StatusBar needs,Add ControlsFX by default before requirements are clear,PropertySheet sheet = new PropertySheet(items);,"implementation ""org.controlsfx:controlsfx"" with no usage",Low,https://controlsfx.github.io/
|
||||
57,Testing,Test theme-critical flows with TestFX,Theme and CSS changes can break focus visibility dialogs and button affordance,Use TestFX for login save validation and modal workflows,Only inspect AtlantaFX screens manually,"clickOn(""#saveButton""); verifyThat("".message"", isVisible());",manual theme QA only,Medium,https://github.com/TestFX/TestFX
|
||||
58,Architecture,Use application shell plus feature workspaces,Enterprise JavaFX apps need stable navigation around changing work areas,Use BorderPane shell with navigation toolbar and central workspace,Replace the whole Stage for every feature,"shell.setLeft(navigation); shell.setTop(toolbar); shell.setCenter(workspace);",stage.setScene(new Scene(loadFeature()));,High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/layout/BorderPane.html
|
||||
59,Architecture,Use MVVM for complex enterprise screens,Large forms and tables need testable state outside the controller,Expose JavaFX properties from view models and bind controls to them,Put all screen state and validation in the controller,amountField.textProperty().bindBidirectional(vm.amountProperty());,controller.amount = amountField.getText();,High,https://openjfx.io/javadoc/21/javafx.base/javafx/beans/property/package-summary.html
|
||||
60,Architecture,Inject services into controllers,Enterprise controllers should coordinate UI and call application services,Use a controller factory or DI container for services,Create database connections inside FXML controllers,loader.setControllerFactory(type -> injector.getInstance(type));,new CustomerRepository(new DriverManager(...)),High,https://openjfx.io/javadoc/21/javafx.fxml/javafx/fxml/FXMLLoader.html
|
||||
61,Navigation,Use role-aware navigation models,Menus toolbars and shortcuts should reflect the same permission model,Build navigation items from commands with required roles,Hide buttons in one place and leave shortcuts enabled,"command.enabledProperty().bind(permissionService.allowed(""invoice.approve""));",approveButton.setVisible(false);,High,
|
||||
62,Workflow,Represent workflow states visibly,Approval and processing screens need clear business state signals,Use semantic badges row styles and disabled actions by workflow state,Use only free text status columns,"row.pseudoClassStateChanged(PseudoClass.getPseudoClass(""blocked""), item.isBlocked());","statusCol.setText(""B"");",Medium,https://openjfx.io/javadoc/21/javafx.graphics/javafx/css/PseudoClass.html
|
||||
63,TableView,Design TableView for high-density enterprise data,Enterprise users scan compare sort filter and act on rows for long periods,Use compact row height clear columns sorting filtering and selection summary,Use card grids for large tabular datasets,"table.getStyleClass().add(""dense-table""); table.getSortOrder().setAll(updatedAtCol);",new TilePane(customerCards),High,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/TableView.html
|
||||
64,TableView,Keep row actions predictable,Inline actions in dense tables should be limited and permission-aware,Use context menus or a side detail panel for secondary actions,Place many buttons in every row,"table.setRowFactory(tv -> { TableRow<Order> row = new TableRow<>(); row.setContextMenu(orderMenu); return row; });",row contains Edit Delete Approve Print Email buttons,Medium,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/ContextMenu.html
|
||||
65,TableView,Use server-side paging for large enterprise datasets,Desktop clients should not load entire enterprise tables into memory,Fetch pages or filtered slices from services,Load all records and filter in the UI,"Page<Customer> page = customerService.search(criteria, pageRequest);",customerRepository.findAll(),High,
|
||||
66,Forms,Use form sections for enterprise data entry,Long enterprise forms need grouping and progressive disclosure,Group fields into titled sections with validation summaries,Place dozens of inputs in one unbroken GridPane,"TitledPane billing = new TitledPane(""Billing"", billingForm);",new GridPane with 80 controls,Medium,https://openjfx.io/javadoc/21/javafx.controls/javafx/scene/control/TitledPane.html
|
||||
67,Forms,Provide validation summary plus field errors,Enterprise forms often need multiple corrections before submission,Show a summary at top and field-level messages near controls,Show only one modal alert after Save,"summary.setItems(vm.validationErrors()); field.pseudoClassStateChanged(INVALID, fieldError);","new Alert(ERROR, ""Invalid form"").showAndWait();",High,
|
||||
68,Tasks,Make long operations cancellable,Enterprise imports exports sync and reports need cancel paths,Expose cancel button bound to Task running state,Force users to wait or kill the app,cancelButton.setOnAction(e -> task.cancel());,runReportButton.setDisable(true);,High,https://openjfx.io/javadoc/21/javafx.graphics/javafx/concurrent/Task.html
|
||||
69,Tasks,Surface retryable errors without losing context,Network and service failures should preserve user input and next action,Show inline retry messages and keep form/table state,Clear the screen on service failure,"message.setDescription(""Could not save. Check connection and retry."");",loadErrorScene();,High,
|
||||
70,Audit,Log business actions through services,Enterprise desktop apps need traceability for sensitive changes,Record user action entity result and timestamp in service layer,Log only UI button clicks,"audit.log(user, ""invoice.approve"", invoiceId, SUCCESS);","System.out.println(""clicked approve"");",Medium,
|
||||
71,Configuration,Separate user preferences from application config,Enterprise apps need deploy-time config and per-user preferences,Use config files for endpoints and Preferences for UI choices,Hard-code environment URLs and window state,"Preferences.userNodeForPackage(App.class).put(""theme"", ""dark"");","private static final String API = ""http://localhost:8080"";",Medium,https://docs.oracle.com/en/java/javase/21/docs/api/java.prefs/java/util/prefs/Preferences.html
|
||||
72,Deployment,Package resources and themes inside the runtime image,AtlantaFX app CSS icons and FXML must be available after jpackage,Load resources from classpath or module resources,Load theme files from developer machine paths,"getClass().getResource(""/css/app.css"").toExternalForm();","new File(""src/main/resources/css/app.css"").toURI()",High,https://openjfx.io/openjfx-docs/#modular
|
||||
73,Deployment,Write logs to user-writable locations,Installed desktop apps may not write inside the application directory,Use platform-specific user data directories for logs and cache,Write logs beside the executable,"Path logs = appData.resolve(""logs/app.log"");",Path.of("app.log"),Medium,
|
||||
74,Testing,Cover enterprise happy path and failure path,Enterprise UI tests should verify save validation permission and service failure flows,Use TestFX for core workflows and service fakes,Only test controller methods without UI interaction,"clickOn(""Save""); verifyThat(""Customer saved"", isVisible());",controller.save(); assertTrue(saved);,High,https://github.com/TestFX/TestFX
|
||||
75,Dependencies,Keep optional UI libraries behind actual needs,AtlantaFX should be default but additional libraries should be justified,Start with JavaFX AtlantaFX Ikonli TestFX and add ControlsFX only for missing controls,Adopt many UI libraries at project start,"dependencies { implementation(""io.github.mkpaz:atlantafx-base:2.1.0"") }",implementation controlsfx gemsfx tilesfx materialfx all at once,Medium,
|
||||
|
Can't render this file because it contains an unexpected character in line 4 and column 345.
|
|
|
@ -1,53 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Composable,Pure UI composables,Composable functions should only render UI,Accept state and callbacks,Calling usecase/repo,Pure UI composable,Business logic in UI,High,https://developer.android.com/jetpack/compose/mental-model
|
||||
2,Composable,Small composables,Each composable has single responsibility,Split into components,Huge composable,Reusable UI,Monolithic UI,Medium,
|
||||
3,Composable,Stateless by default,Prefer stateless composables,Hoist state,Local mutable state,Stateless UI,Hidden state,High,https://developer.android.com/jetpack/compose/state#state-hoisting
|
||||
4,State,Single source of truth,UI state comes from one source,StateFlow from VM,Multiple states,Unified UiState,Scattered state,High,https://developer.android.com/topic/architecture/ui-layer
|
||||
5,State,Model UI State,Use sealed interface/data class,UiState.Loading,Boolean flags,Explicit state,Flag hell,High,
|
||||
6,State,remember only UI state,remember for UI-only state,"Scroll, animation",Business state,Correct remember,Misuse remember,High,https://developer.android.com/jetpack/compose/state
|
||||
7,State,rememberSaveable,Persist state across config,rememberSaveable,remember,State survives,State lost,High,https://developer.android.com/jetpack/compose/state#restore-ui-state
|
||||
8,State,derivedStateOf,Optimize recomposition,derivedStateOf,Recompute always,Optimized,Jank,Medium,https://developer.android.com/jetpack/compose/performance
|
||||
9,SideEffect,LaunchedEffect keys,Use correct keys,LaunchedEffect(id),LaunchedEffect(Unit),Scoped effect,Infinite loop,High,https://developer.android.com/jetpack/compose/side-effects
|
||||
10,SideEffect,rememberUpdatedState,Avoid stale lambdas,rememberUpdatedState,Capture directly,Safe callback,Stale state,Medium,https://developer.android.com/jetpack/compose/side-effects
|
||||
11,SideEffect,DisposableEffect,Clean up resources,onDispose,No cleanup,No leak,Memory leak,High,
|
||||
12,Architecture,Unidirectional data flow,UI → VM → State,onEvent,Two-way binding,Predictable flow,Hard debug,High,https://developer.android.com/topic/architecture
|
||||
13,Architecture,No business logic in UI,Logic belongs to VM,Collect state,Call repo,Clean UI,Fat UI,High,
|
||||
14,Architecture,Expose immutable state,Expose StateFlow,asStateFlow,Mutable exposed,Safe API,State mutation,High,
|
||||
15,Lifecycle,Lifecycle-aware collect,Use collectAsStateWithLifecycle,Lifecycle aware,collectAsState,No leak,Leak,High,https://developer.android.com/jetpack/compose/lifecycle
|
||||
16,Navigation,Event-based navigation,VM emits navigation event,"VM: Channel + receiveAsFlow(), V: Collect with Dispatchers.Main.immediate",Nav in UI,Decoupled nav,Using State / SharedFlow for navigation -> event is replayed and navigation fires again (StateFlow),High,https://developer.android.com/jetpack/compose/navigation
|
||||
17,Navigation,Typed routes,Use sealed routes,sealed class Route,String routes,Type-safe,Runtime crash,Medium,
|
||||
18,Performance,Stable parameters,Prefer immutable/stable params,@Immutable,Mutable params,Stable recomposition,Extra recomposition,High,https://developer.android.com/jetpack/compose/performance
|
||||
19,Performance,Use key in Lazy,Provide stable keys,key=id,No key,Stable list,Item jump,High,
|
||||
20,Performance,Avoid heavy work,No heavy computation in UI,Precompute in VM,Compute in UI,Smooth UI,Jank,High,
|
||||
21,Performance,Remember expensive objects,remember heavy objects,remember,Recreate each recomposition,Efficient,Wasteful,Medium,
|
||||
22,Theming,Design system,Centralized theme,Material3 tokens,Hardcoded values,Consistent UI,Inconsistent,High,https://developer.android.com/jetpack/compose/themes
|
||||
23,Theming,Dark mode support,Theme-based colors,colorScheme,Fixed color,Adaptive UI,Broken dark,Medium,
|
||||
24,Layout,Prefer Modifier over extra layouts,Use Modifier to adjust layout instead of adding wrapper composables,Use Modifier.padding(),Wrap content with extra Box,Padding via modifier,Box just for padding,High,https://developer.android.com/jetpack/compose/modifiers
|
||||
25,Layout,Avoid deep layout nesting,Deep layout trees increase measure & layout cost,Keep layout flat,Box ? Column ? Box ? Row,Flat hierarchy,Deep nested tree,High,
|
||||
26,Layout,Use Row/Column for linear layout,Linear layouts are simpler and more performant,Use Row / Column,Custom layout for simple cases,Row/Column usage,Over-engineered layout,High,
|
||||
27,Layout,Use Box only for overlapping content,Box should be used only when children overlap,Stack elements,Use Box as Column,Proper overlay,Misused Box,Medium,
|
||||
28,Layout,Prefer LazyColumn over Column scroll,Lazy layouts are virtualized and efficient,LazyColumn,Column.verticalScroll(),Lazy list,Scrollable Column,High,https://developer.android.com/jetpack/compose/lists
|
||||
29,Layout,Avoid nested scroll containers,Nested scrolling causes UX & performance issues,Single scroll container,Scroll inside scroll,One scroll per screen,Nested scroll,High,
|
||||
30,Layout,Avoid fillMaxSize by default,fillMaxSize may break parent constraints,Use exact size,Fill max everywhere,Constraint-aware size,Overfilled layout,Medium,
|
||||
31,Layout,Avoid intrinsic size unless necessary,Intrinsic measurement is expensive,Explicit sizing,IntrinsicSize.Min,Predictable layout,Expensive measure,High,https://developer.android.com/jetpack/compose/layout/intrinsics
|
||||
32,Layout,Use Arrangement and Alignment APIs,Declare layout intent explicitly,Use Arrangement / Alignment,Manual spacing hacks,Declarative spacing,Magic spacing,High,
|
||||
33,Layout,Extract reusable layout patterns,Repeated layouts should be shared,Create layout composable,Copy-paste layouts,Reusable scaffold,Duplicated layout,High,
|
||||
34,Theming,No hardcoded text style,Use typography,MaterialTheme.typography,Hardcode sp,Scalable,Inconsistent,Medium,
|
||||
35,Testing,Stateless UI testing,Composable easy to test,Pass state,Hidden state,Testable,Hard test,High,https://developer.android.com/jetpack/compose/testing
|
||||
36,Testing,Use testTag,Stable UI selectors,Modifier.testTag,Find by text,Stable tests,Flaky tests,Medium,
|
||||
37,Preview,Multiple previews,Preview multiple states,@Preview,Single preview,Better dev UX,Misleading,Low,https://developer.android.com/jetpack/compose/tooling/preview
|
||||
38,DI,Inject VM via Hilt,Use hiltViewModel,@HiltViewModel,Manual VM,Clean DI,Coupling,High,https://developer.android.com/training/dependency-injection/hilt-jetpack
|
||||
39,DI,No DI in UI,Inject in VM,Constructor inject,Inject composable,Proper scope,Wrong scope,High,
|
||||
40,Accessibility,Content description,Accessible UI,contentDescription,Ignore a11y,Inclusive,A11y fail,Medium,https://developer.android.com/jetpack/compose/accessibility
|
||||
41,Accessibility,Semantics,Use semantics API,Modifier.semantics,None,Testable a11y,Invisible,Medium,
|
||||
42,Animation,Compose animation APIs,Use animate*AsState,AnimatedVisibility,Manual anim,Smooth,Jank,Medium,https://developer.android.com/jetpack/compose/animation
|
||||
43,Animation,Avoid animation logic in VM,Animation is UI concern,Animate in UI,Animate in VM,Correct layering,Mixed concern,Low,
|
||||
44,Modularization,Feature-based UI modules,UI per feature,:feature:ui,God module,Scalable,Tight coupling,High,https://developer.android.com/topic/modularization
|
||||
45,Modularization,Public UI contracts,Expose minimal UI API,Interface/Route,Expose impl,Encapsulated,Leaky module,Medium,
|
||||
46,State,Snapshot state only,Use Compose state,mutableStateOf,Custom observable,Compose aware,Buggy UI,Medium,
|
||||
47,State,Avoid mutable collections,Immutable list/map,PersistentList,MutableList,Stable UI,Silent bug,High,
|
||||
48,Lifecycle,RememberCoroutineScope usage,Only for UI jobs,UI coroutine,Long jobs,Scoped job,Leak,Medium,https://developer.android.com/jetpack/compose/side-effects#remembercoroutinescope
|
||||
49,Interop,Interop View carefully,Use AndroidView,Isolated usage,Mix everywhere,Safe interop,Messy UI,Low,https://developer.android.com/jetpack/compose/interop
|
||||
50,Interop,Avoid legacy patterns,No LiveData in UI,StateFlow,LiveData,Modern stack,Legacy debt,Medium,
|
||||
51,Debug,Use layout inspector,Inspect recomposition,Tools,Blind debug,Fast debug,Guessing,Low,https://developer.android.com/studio/debug/layout-inspector
|
||||
52,Debug,Enable recomposition counts,Track recomposition,Debug flags,Ignore,Performance aware,Hidden jank,Low,
|
||||
|
|
|
@ -1,51 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Blade Templates,Use Blade components for reusable UI,Extract repeated markup into named Blade components,Use x-* components with @props for all reusable UI,Duplicate HTML blocks across views,<x-card :title="$title">{{ $slot }}</x-card>,@include('card' ['title' => $title]),High,https://laravel.com/docs/blade#components
|
||||
2,Blade Templates,Use layouts with @extends and @section,Define one master layout and extend it per page,@extends layout with named @section blocks,Duplicate header/footer HTML in every view,@extends('layouts.app') @section('content'),Full HTML in every view file,High,https://laravel.com/docs/blade#layouts-using-template-inheritance
|
||||
3,Blade Templates,Use @props for component type-safety,Declare accepted props inside components with @props,@props with defaults to document component API,Pass arbitrary variables without declaration,@props(['title' => '' 'variant' => 'primary']),No @props declaration in component,Medium,https://laravel.com/docs/blade#component-data-and-attributes
|
||||
4,Blade Templates,Use conditional CSS classes with @class,Build class strings conditionally without ternary noise,@class directive for conditional class binding,String concatenation or nested ternaries,@class(['btn' 'btn-primary' => $primary 'btn-disabled' => $disabled]),class="btn {{ $primary ? 'btn-primary' : '' }}",Medium,https://laravel.com/docs/blade#conditional-classes-and-styles
|
||||
5,Blade Templates,Use named slots for flexible layouts,Named slots let callers inject content into specific regions,@slot('header') and $slot for flexible component APIs,Hard-code all sub-sections inside components,"<x-modal><x-slot:header>Title</x-slot>Body</x-modal>",<x-modal title="Title">Body with no slot control</x-modal>,Medium,https://laravel.com/docs/blade#slots
|
||||
6,Blade Templates,Use Blade directives instead of raw PHP,Blade directives are readable and IDE-supported,@if @foreach @forelse @empty instead of <?php ?>,Raw PHP tags inside Blade templates,@forelse($items as $item) ... @empty <p>None</p> @endforelse,<?php foreach($items as $item): ?>,High,https://laravel.com/docs/blade#blade-directives
|
||||
7,Blade Templates,Escape output with {{ }},Use double curly braces for XSS-safe output,{{ }} for all user-supplied or dynamic text,{!! !!} for untrusted data,{{ $user->name }},{!! $user->name !!},High,https://laravel.com/docs/blade#displaying-data
|
||||
8,Blade Templates,Use @vite for asset loading,Vite integration handles cache busting and HMR automatically,@vite(['resources/css/app.css' 'resources/js/app.js']),Manual script/link tags with hardcoded paths,@vite(['resources/css/app.css' 'resources/js/app.js']),<link href="/css/app.css?v=123">,High,https://laravel.com/docs/vite
|
||||
9,Livewire,Bind inputs with wire:model,Two-way data binding keeps component state in sync,wire:model for all form inputs managed by Livewire,Manual JavaScript listeners syncing to component,<input wire:model="email">,<input @change="$wire.email = $event.target.value">,High,https://livewire.laravel.com/docs/properties
|
||||
10,Livewire,Use wire:model.live for real-time validation,Validate on input rather than only on submit,wire:model.live + #[Validate] for instant feedback,Only validate on form submit,<input wire:model.live="email"> with #[Validate('email')],<input wire:model="email"> with validate() on submit only,Medium,https://livewire.laravel.com/docs/validation
|
||||
11,Livewire,Use wire:click for actions,Bind UI events to component methods cleanly,wire:click for buttons and interactive elements,JavaScript fetch calls replicating Livewire actions,<button wire:click="save">Save</button>,<button onclick="fetch('/save')">Save</button>,High,https://livewire.laravel.com/docs/actions
|
||||
12,Livewire,Use lifecycle hooks appropriately,mount() for init; updated() for reactive side effects,mount() for initialization updatedFoo() for property changes,Heavy logic in render() or __construct(),public function mount(): void { $this->items = Item::all(); },public function render(): View { $this->items = Item::all(); },Medium,https://livewire.laravel.com/docs/lifecycle-hooks
|
||||
13,Livewire,Use lazy loading for heavy components,Defer render of expensive components until visible,wire:init or lazy attribute on components,Load all Livewire components on page load,<livewire:analytics-chart lazy />,<livewire:analytics-chart /> with heavy DB queries on mount,Medium,https://livewire.laravel.com/docs/lazy
|
||||
14,Livewire,Integrate Alpine.js for local UI state,Use Alpine.js for UI-only state that doesn't need server round-trips,x-data / x-show / x-transition for tooltips dropdowns,Livewire server calls for purely visual toggle state,<div x-data="{ open: false }"><button @click="open = !open">,<button wire:click="toggleDropdown"> for a local dropdown,Medium,https://livewire.laravel.com/docs/alpine
|
||||
15,Livewire,Use wire:loading for feedback,Always indicate to users when a server action is in progress,wire:loading.attr="disabled" and wire:loading elements,Provide no feedback while Livewire request is in flight,<button wire:click="save" wire:loading.attr="disabled">Save</button>,<button wire:click="save">Save</button> with no loading state,High,https://livewire.laravel.com/docs/wire-loading
|
||||
16,Livewire,Handle file uploads with WithFileUploads,Livewire's trait manages chunked upload and temp storage,WithFileUploads trait + wire:model for file inputs,Manual multipart form submissions for Livewire pages,use WithFileUploads; public $photo; <input wire:model="photo" type="file">,<form action="/upload" method="POST" enctype="multipart/form-data">,Medium,https://livewire.laravel.com/docs/uploads
|
||||
17,Inertia.js,Use Inertia page components as route endpoints,Each page is a Vue/React component rendered server-side via Inertia::render(),Inertia::render('Dashboard' ['data' => $data]) in controllers,Return JSON and fetch from JavaScript,return Inertia::render('Users/Index' ['users' => $users]);,return response()->json($users); with client-side fetch,High,https://inertiajs.com/responses
|
||||
18,Inertia.js,Share global data via HandleInertiaRequests,Middleware share() provides auth user and flash to every page,Share auth/flash in HandleInertiaRequests middleware,Pass auth to every Inertia::render() call,public function share(Request $r): array { return ['auth' => ['user' => $r->user()]]; },Inertia::render('Page' ['auth' => auth()->user()]) every controller,High,https://inertiajs.com/shared-data
|
||||
19,Inertia.js,Use <Link> for client-side navigation,Inertia Link intercepts clicks for SPA-like transitions,<Link href="/dashboard"> instead of <a href>,Regular <a> tags for internal navigation,<Link href={route('dashboard')}>Dashboard</Link>,<a href="/dashboard">Dashboard</a>,High,https://inertiajs.com/links
|
||||
20,Inertia.js,Use useForm for form state and submission,Inertia's useForm manages progress errors and transforms,"useForm for all page-level forms, form.post() for submit",Axios/fetch for form submissions on Inertia pages,"const form = useForm({ name: '' }); form.post('/users');","axios.post('/users', { name });",High,https://inertiajs.com/forms
|
||||
21,Inertia.js,Use persistent layouts to preserve state,Wrap pages in a persistent layout so header/sidebar don't remount,layout property on page component for persistent UI,Re-render full layout on every page visit,MyPage.layout = (page) => <AppLayout>{page}</AppLayout>,No layout — full page reload feel on navigation,Medium,https://inertiajs.com/pages#persistent-layouts
|
||||
22,Inertia.js,Enable SSR for public pages,Server-side rendering improves SEO and first paint,Enable Inertia SSR for marketing and public pages,Client-only rendering for all pages including public,php artisan inertia:start-ssr with @inertiaHead,No SSR on pages requiring good SEO,Medium,https://inertiajs.com/server-side-rendering
|
||||
23,Styling,Set up Tailwind CSS via Vite,Use Vite + tailwindcss plugin for fast HMR and optimized builds,Install tailwindcss @tailwindcss/vite and configure vite.config.js,Laravel Mix or manual PostCSS pipeline for new projects,plugins: [tailwindcss()] in vite.config.js + @import 'tailwindcss' in app.css,Laravel Mix with require('tailwindcss') in webpack,High,https://tailwindcss.com/docs/installation/framework-guides
|
||||
24,Styling,Purge unused styles via content config,Tailwind scans Blade and JS files to tree-shake unused classes,content: ['./resources/views/**/*.blade.php' './resources/js/**/*.{js,vue}'],No content config — ship all 3MB of CSS,content: ['./resources/**/*.blade.php' './resources/**/*.js'],content: [],High,https://tailwindcss.com/docs/content-configuration
|
||||
25,Styling,Use dark mode class strategy,class-based dark mode integrates with server-rendered preference,darkMode: 'class' with a toggle that sets class on <html>,Media query only — no user override possible,darkMode: 'class'; document.documentElement.classList.toggle('dark'),darkMode: 'media' — no programmatic control,Medium,https://tailwindcss.com/docs/dark-mode
|
||||
26,Styling,Use @apply sparingly in component CSS,Extract only truly repeated multi-class patterns,@apply for BEM base classes shared across many components,@apply for every single element — defeats Tailwind's purpose,@apply flex items-center gap-2 (shared button base),@apply text-sm for a single use,Low,https://tailwindcss.com/docs/functions-and-directives#apply
|
||||
27,Styling,Configure custom design tokens in CSS,Define brand colors spacing fonts as CSS variables consumed by Tailwind,Custom @theme tokens matched to brand guidelines,Magic color hex codes scattered across Blade templates,@theme { --color-brand: oklch(0.6 0.2 250); },bg-[#1a2b3c] inline throughout templates,Medium,https://tailwindcss.com/docs/theme
|
||||
28,Components,Use anonymous Blade components for UI primitives,Blade files in resources/views/components/ auto-register as x-* components,Anonymous components for buttons alerts badges cards,Blade @includes for anything reusable,<x-badge variant="success">Active</x-badge>,@include('partials.badge' ['variant' => 'success']),Medium,https://laravel.com/docs/blade#anonymous-components
|
||||
29,Components,Use class-based components for complex logic,PHP class components can inject services and pre-process data,app/View/Components/ class when component needs PHP logic,Blade @php blocks for business logic inside templates,class AlertComponent { public function __construct(public string $type) {} },@php $color = $type === 'error' ? 'red' : 'green'; @endphp,Medium,https://laravel.com/docs/blade#components
|
||||
30,Components,Forward extra attributes with $attributes,Pass through HTML attributes like class id aria to root element,$attributes->merge() on root element of components,Ignore caller-provided HTML attributes silently,<div {{ $attributes->merge(['class' => 'btn']) }}>,<div class="btn"> — drops extra class/id from caller,High,https://laravel.com/docs/blade#component-attributes
|
||||
31,Components,Separate variant logic from templates,Keep variant/size/color logic in a PHP class or helper not in Blade,Variant class or match() expression in component class,Long @if chains for variants inside Blade templates,"public function classes(): string { return match($this->variant) { 'primary' => 'bg-blue-600', } }","@if($variant === 'primary') bg-blue-600 @elseif($variant === 'secondary')...",Medium,https://laravel.com/docs/blade#components
|
||||
32,Components,Provide default slot content,Use {{ $slot ?? '' }} or named slot defaults so components are usable empty,Default content in slots for optional regions,Require every slot to be filled — throws errors on empty usage,{{ $icon ?? '' }} in component Blade file,{{ $icon }} — fatal if caller omits slot,Low,https://laravel.com/docs/blade#slots
|
||||
33,Components,Use component namespacing for packages,Prefix third-party or module components to avoid collisions,Register custom prefix via Blade::componentNamespace(),Mix first-party and package component names with no prefix,Blade::componentNamespace('Modules\\Shop\\Views' 'shop'); <x-shop::product-card />,<x-product-card /> colliding with first-party card,Low,https://laravel.com/docs/blade#manually-registering-components
|
||||
34,Forms,Validate with Form Request classes,Move validation rules out of controllers into dedicated FormRequest classes,php artisan make:request and define rules() + authorize(),Inline validate() in controller actions,class StorePostRequest extends FormRequest { public function rules() { return ['title' => 'required|max:255']; } },public function store(Request $r) { $r->validate(['title' => 'required']); },High,https://laravel.com/docs/validation#form-request-validation
|
||||
35,Forms,Preserve old input on validation failure,Use old() to repopulate form fields after server-side error redirect,old('field') as default value on all form inputs,Empty form fields when validation fails,<input name="email" value="{{ old('email') }}">,<input name="email">,High,https://laravel.com/docs/validation#repopulating-forms
|
||||
36,Forms,Display validation errors with @error,Use the @error directive for inline field-level error messages,@error('field') to show per-field messages,Dump $errors->all() in one block at top of form,@error('email') <p class="text-red-500">{{ $message }}</p> @enderror,@foreach($errors->all() as $e) {{ $e }} @endforeach,Medium,https://laravel.com/docs/validation#quick-displaying-the-validation-errors
|
||||
37,Forms,Use CSRF token on all forms,CSRF protection is enabled by default — include @csrf in every form,@csrf in every POST/PUT/PATCH/DELETE form,Disable VerifyCsrfToken middleware for convenience,<form method="POST">@csrf ...,<form method="POST"> without @csrf,High,https://laravel.com/docs/csrf
|
||||
38,Forms,Use method spoofing for PUT/PATCH/DELETE,HTML forms only support GET/POST — use @method for REST actions,@method('PUT') inside form for update/delete routes,Route::post for all mutations including updates,"<form method=""POST"">@csrf @method('PUT')",<form method="POST" action="/users/update">,Medium,https://laravel.com/docs/routing#form-method-spoofing
|
||||
39,Forms,Display flash messages consistently,Flash success/error in controller; read in layout with session(),session('status') in layout for global flash display,Re-query DB or pass flash from every controller individually,@if(session('success')) <div class="alert">{{ session('success') }}</div> @endif,if($user) return back()->with(['user' => $user]);,Medium,https://laravel.com/docs/session#flash-data
|
||||
40,Performance,Eager load relationships to prevent N+1,Always eager load related models used in views with with(),with() in queries before passing collections to views,Lazy-load relations inside Blade loops,User::with('posts' 'avatar')->get(),User::all() then @foreach $user->posts in Blade,High,https://laravel.com/docs/eloquent-relationships#eager-loading
|
||||
41,Performance,Cache rendered Blade fragments,Use cache() helper to wrap expensive rendered partials,cache() around slow partials that change infrequently,Re-render identical content on every request,@php echo cache()->remember('sidebar' 3600 fn() => view('sidebar')->render()); @endphp,{{ view('sidebar')->render() }} on every page load,Medium,https://laravel.com/docs/cache
|
||||
42,Performance,Paginate large data sets,Always paginate collections in list views,->paginate() or ->simplePaginate() with {{ $items->links() }},->get() for large tables in views,User::paginate(20) with <x-pagination :links="$users" />,User::all() passed to Blade,High,https://laravel.com/docs/pagination
|
||||
43,Performance,Queue slow background tasks,Offload emails notifications and heavy processing to queues,Dispatch jobs for anything taking >200ms,Block HTTP request with slow operations,ProcessImage::dispatch($file); return back();,Storage::put(); Mail::send(); Image::resize(); in controller,High,https://laravel.com/docs/queues
|
||||
44,Performance,Use route model binding,Laravel resolves models automatically — avoids manual find(),Type-hint model in controller method,Manual User::findOrFail($id) in every method,public function show(User $user): View { return view('users.show' compact('user')); },public function show($id) { $user = User::findOrFail($id); },Medium,https://laravel.com/docs/routing#route-model-binding
|
||||
45,Performance,Enable HTTP response caching for static content,Cache control headers for pages that rarely change,Cache-Control headers via middleware for public pages,No caching — serve every response fresh,response()->view('home')->header('Cache-Control' 'public, max-age=3600'),No cache headers on marketing pages,Medium,https://laravel.com/docs/responses#response-headers
|
||||
46,Security,Escape all output in Blade,{{ }} auto-escapes HTML — never use {!! !!} on user data,{{ }} for all untrusted or dynamic content,{!! !!} for user-controlled strings,{{ $comment->body }},{!! $comment->body !!},High,https://laravel.com/docs/blade#displaying-data
|
||||
47,Security,Protect routes with Gate and Policy,Use policies for authorization — never inline permission checks in views,@can / Gate::allows() for UI visibility; policy()->authorize() for actions,Hardcode role checks inline across templates,@can('update' $post) <a href="{{ route('posts.edit' $post) }}">Edit</a> @endcan,@if(auth()->user()->role === 'admin') <a href="/edit">,High,https://laravel.com/docs/authorization#policies
|
||||
48,Security,Validate and authorize file uploads,Check MIME type size and store outside public root,Store in storage/app/private + validate mimes and max,Store raw upload in public/ without validation,"'avatar' => ['required' 'image' 'mimes:jpg,png' 'max:2048']",'avatar' => 'required' with no MIME or size check,High,https://laravel.com/docs/filesystem#file-uploads
|
||||
49,Security,Use signed URLs for temporary links,Generate expiring URLs for private downloads or email confirmations,URL::signedRoute() or temporarySignedRoute(),Expose sequential IDs in download URLs without auth,URL::temporarySignedRoute('file.download' now()->addMinutes(30) ['file' => $id]),route('file.download' $id) with no expiry or signature,High,https://laravel.com/docs/urls#signed-urls
|
||||
50,Security,Set a strict Content Security Policy,CSP headers prevent XSS injection of external scripts,spatie/laravel-csp or custom middleware to emit CSP header,No CSP — browser runs any injected script,Header: Content-Security-Policy: default-src 'self'; script-src 'self',No Content-Security-Policy header on responses,Medium,https://laravel.com/docs/middleware
|
||||
|
Can't render this file because it contains an unexpected character in line 2 and column 209.
|
|
|
@ -1,53 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Routing,Use App Router for new projects,App Router is the recommended approach in Next.js 14+,app/ directory with page.tsx,pages/ for new projects,app/dashboard/page.tsx,pages/dashboard.tsx,Medium,https://nextjs.org/docs/app
|
||||
2,Routing,Use file-based routing,Create routes by adding files in app directory,page.tsx for routes layout.tsx for layouts,Manual route configuration,app/blog/[slug]/page.tsx,Custom router setup,Medium,https://nextjs.org/docs/app/building-your-application/routing
|
||||
3,Routing,Colocate related files,Keep components styles tests with their routes,Component files alongside page.tsx,Separate components folder,app/dashboard/_components/,components/dashboard/,Low,
|
||||
4,Routing,Use route groups for organization,Group routes without affecting URL,Parentheses for route groups,Nested folders affecting URL,(marketing)/about/page.tsx,marketing/about/page.tsx,Low,https://nextjs.org/docs/app/building-your-application/routing/route-groups
|
||||
5,Routing,Handle loading states,Use loading.tsx for route loading UI,loading.tsx alongside page.tsx,Manual loading state management,app/dashboard/loading.tsx,useState for loading in page,Medium,https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming
|
||||
6,Routing,Handle errors with error.tsx,Catch errors at route level,error.tsx with reset function,try/catch in every component,app/dashboard/error.tsx,try/catch in page component,High,https://nextjs.org/docs/app/building-your-application/routing/error-handling
|
||||
7,Rendering,Use Server Components by default,Server Components reduce client JS bundle,Keep components server by default,Add 'use client' unnecessarily,export default function Page(),('use client') for static content,High,https://nextjs.org/docs/app/building-your-application/rendering/server-components
|
||||
8,Rendering,Mark Client Components explicitly,'use client' for interactive components,Add 'use client' only when needed,Server Component with hooks/events,('use client') for onClick useState,No directive with useState,High,https://nextjs.org/docs/app/building-your-application/rendering/client-components
|
||||
9,Rendering,Push Client Components down,Keep Client Components as leaf nodes,Client wrapper for interactive parts only,Mark page as Client Component,<InteractiveButton/> in Server Page,('use client') on page.tsx,High,
|
||||
10,Rendering,Use streaming for better UX,Stream content with Suspense boundaries,Suspense for slow data fetches,Wait for all data before render,<Suspense><SlowComponent/></Suspense>,await allData then render,Medium,https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming
|
||||
11,Rendering,Choose correct rendering strategy,SSG for static SSR for dynamic ISR for semi-static,generateStaticParams for known paths,SSR for static content,export const revalidate = 3600,fetch without cache config,Medium,
|
||||
12,DataFetching,Fetch data in Server Components,Fetch directly in async Server Components,async function Page() { const data = await fetch() },useEffect for initial data,const data = await fetch(url),useEffect(() => fetch(url)),High,https://nextjs.org/docs/app/building-your-application/data-fetching
|
||||
13,DataFetching,Configure caching explicitly (Next.js 15+),Next.js 15 changed defaults to uncached for fetch,Explicitly set cache: 'force-cache' for static data,Assume default is cached (it's not in Next.js 15),fetch(url { cache: 'force-cache' }),fetch(url) // Uncached in v15,High,https://nextjs.org/docs/app/building-your-application/upgrading/version-15
|
||||
14,DataFetching,Deduplicate fetch requests,React and Next.js dedupe same requests,Same fetch call in multiple components,Manual request deduplication,Multiple components fetch same URL,Custom cache layer,Low,
|
||||
15,DataFetching,Use Server Actions for mutations,Server Actions for form submissions,action={serverAction} in forms,API route for every mutation,<form action={createPost}>,<form onSubmit={callApiRoute}>,Medium,https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
|
||||
16,DataFetching,Revalidate data appropriately,Use revalidatePath/revalidateTag after mutations,Revalidate after Server Action,'use client' with manual refetch,revalidatePath('/posts'),router.refresh() everywhere,Medium,https://nextjs.org/docs/app/building-your-application/caching#revalidating
|
||||
17,Images,Use next/image for optimization,Automatic image optimization and lazy loading,<Image> component for all images,<img> tags directly,<Image src={} alt={} width={} height={}>,<img src={}/>,High,https://nextjs.org/docs/app/building-your-application/optimizing/images
|
||||
18,Images,Provide width and height,Prevent layout shift with dimensions,width and height props or fill,Missing dimensions,<Image width={400} height={300}/>,<Image src={url}/>,High,
|
||||
19,Images,Use fill for responsive images,Fill container with object-fit,fill prop with relative parent,Fixed dimensions for responsive,"<Image fill className=""object-cover""/>",<Image width={window.width}/>,Medium,
|
||||
20,Images,Configure remote image domains,Whitelist external image sources,remotePatterns in next.config.js,Allow all domains,remotePatterns: [{ hostname: 'cdn.example.com' }],domains: ['*'],High,https://nextjs.org/docs/app/api-reference/components/image#remotepatterns
|
||||
21,Images,Use priority for LCP images,Mark above-fold images as priority,priority prop on hero images,All images with priority,<Image priority src={hero}/>,<Image priority/> on every image,Medium,
|
||||
22,Fonts,Use next/font for fonts,Self-hosted fonts with zero layout shift,next/font/google or next/font/local,External font links,import { Inter } from 'next/font/google',"<link href=""fonts.googleapis.com""/>",Medium,https://nextjs.org/docs/app/building-your-application/optimizing/fonts
|
||||
23,Fonts,Apply font to layout,Set font in root layout for consistency,className on body in layout.tsx,Font in individual pages,<body className={inter.className}>,Each page imports font,Low,
|
||||
24,Fonts,Use variable fonts,Variable fonts reduce bundle size,Single variable font file,Multiple font weights as files,Inter({ subsets: ['latin'] }),Inter_400 Inter_500 Inter_700,Low,
|
||||
25,Metadata,Use generateMetadata for dynamic,Generate metadata based on params,export async function generateMetadata(),Hardcoded metadata everywhere,generateMetadata({ params }),export const metadata = {},Medium,https://nextjs.org/docs/app/building-your-application/optimizing/metadata
|
||||
26,Metadata,Include OpenGraph images,Add OG images for social sharing,opengraph-image.tsx or og property,Missing social preview images,opengraph: { images: ['/og.png'] },No OG configuration,Medium,
|
||||
27,Metadata,Use metadata API,Export metadata object for static metadata,export const metadata = {},Manual head tags,export const metadata = { title: 'Page' },<head><title>Page</title></head>,Medium,
|
||||
28,API,Use Route Handlers for APIs,app/api routes for API endpoints,app/api/users/route.ts,pages/api for new projects,export async function GET(request),export default function handler,Medium,https://nextjs.org/docs/app/building-your-application/routing/route-handlers
|
||||
29,API,Return proper Response objects,Use NextResponse for API responses,NextResponse.json() for JSON,Plain objects or res.json(),return NextResponse.json({ data }),return { data },Medium,
|
||||
30,API,Handle HTTP methods explicitly,Export named functions for methods,Export GET POST PUT DELETE,Single handler for all methods,export async function POST(),switch(req.method),Low,
|
||||
31,API,Validate request body,Validate input before processing,Zod or similar for validation,Trust client input,const body = schema.parse(await req.json()),const body = await req.json(),High,
|
||||
32,Middleware,Use middleware for auth,Protect routes with middleware.ts,middleware.ts at root,Auth check in every page,export function middleware(request),if (!session) redirect in page,Medium,https://nextjs.org/docs/app/building-your-application/routing/middleware
|
||||
33,Middleware,Match specific paths,Configure middleware matcher,config.matcher for specific routes,Run middleware on all routes,matcher: ['/dashboard/:path*'],No matcher config,Medium,
|
||||
34,Middleware,Keep middleware edge-compatible,Middleware runs on Edge runtime,Edge-compatible code only,Node.js APIs in middleware,Edge-compatible auth check,fs.readFile in middleware,High,
|
||||
35,Environment,Use NEXT_PUBLIC prefix,Client-accessible env vars need prefix,NEXT_PUBLIC_ for client vars,Server vars exposed to client,NEXT_PUBLIC_API_URL,API_SECRET in client code,High,https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
|
||||
36,Environment,Validate env vars,Check required env vars exist,Validate on startup,Undefined env at runtime,if (!process.env.DATABASE_URL) throw,process.env.DATABASE_URL (might be undefined),High,
|
||||
37,Environment,Use .env.local for secrets,Local env file for development secrets,.env.local gitignored,Secrets in .env committed,.env.local with secrets,.env with DATABASE_PASSWORD,High,
|
||||
38,Performance,Analyze bundle size,Use @next/bundle-analyzer,Bundle analyzer in dev,Ship large bundles blindly,ANALYZE=true npm run build,No bundle analysis,Medium,https://nextjs.org/docs/app/building-your-application/optimizing/bundle-analyzer
|
||||
39,Performance,Use dynamic imports,Code split with next/dynamic,dynamic() for heavy components,Import everything statically,const Chart = dynamic(() => import('./Chart')),import Chart from './Chart',Medium,https://nextjs.org/docs/app/building-your-application/optimizing/lazy-loading
|
||||
40,Performance,Avoid layout shifts,Reserve space for dynamic content,Skeleton loaders aspect ratios,Content popping in,"<Skeleton className=""h-48""/>",No placeholder for async content,High,
|
||||
41,Performance,Use Partial Prerendering,Combine static and dynamic in one route,Static shell with Suspense holes,Full dynamic or static pages,Static header + dynamic content,Entire page SSR,Low,https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering
|
||||
42,Link,Use next/link for navigation,Client-side navigation with prefetching,"<Link href=""""> for internal links",<a> for internal navigation,"<Link href=""/about"">About</Link>","<a href=""/about"">About</a>",High,https://nextjs.org/docs/app/api-reference/components/link
|
||||
43,Link,Prefetch strategically,Control prefetching behavior,prefetch={false} for low-priority,Prefetch all links,<Link prefetch={false}>,Default prefetch on every link,Low,
|
||||
44,Link,Use scroll option appropriately,Control scroll behavior on navigation,scroll={false} for tabs pagination,Always scroll to top,<Link scroll={false}>,Manual scroll management,Low,
|
||||
45,Config,Use next.config.js correctly,Configure Next.js behavior,Proper config options,Deprecated or wrong options,images: { remotePatterns: [] },images: { domains: [] },Medium,https://nextjs.org/docs/app/api-reference/next-config-js
|
||||
46,Config,Enable strict mode,Catch potential issues early,reactStrictMode: true,Strict mode disabled,reactStrictMode: true,reactStrictMode: false,Medium,
|
||||
47,Config,Configure redirects and rewrites,Use config for URL management,redirects() rewrites() in config,Manual redirect handling,redirects: async () => [...],res.redirect in pages,Medium,https://nextjs.org/docs/app/api-reference/next-config-js/redirects
|
||||
48,Deployment,Use Vercel for easiest deploy,Vercel optimized for Next.js,Deploy to Vercel,Self-host without knowledge,vercel deploy,Complex Docker setup for simple app,Low,https://nextjs.org/docs/app/building-your-application/deploying
|
||||
49,Deployment,Configure output for self-hosting,Set output option for deployment target,output: 'standalone' for Docker,Default output for containers,output: 'standalone',No output config for Docker,Medium,https://nextjs.org/docs/app/building-your-application/deploying#self-hosting
|
||||
50,Security,Sanitize user input,Never trust user input,Escape sanitize validate all input,Direct interpolation of user data,DOMPurify.sanitize(userInput),dangerouslySetInnerHTML={{ __html: userInput }},High,
|
||||
51,Security,Use CSP headers,Content Security Policy for XSS protection,Configure CSP in next.config.js,No security headers,headers() with CSP,No CSP configuration,High,https://nextjs.org/docs/app/building-your-application/configuring/content-security-policy
|
||||
52,Security,Validate Server Action input,Server Actions are public endpoints,Validate and authorize in Server Action,Trust Server Action input,Auth check + validation in action,Direct database call without check,High,
|
||||
|
|
|
@ -1,71 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Installation,Add Nuxt UI module,Install and configure Nuxt UI in your Nuxt project,pnpm add @nuxt/ui and add to modules,Manual component imports,"modules: ['@nuxt/ui']","import { UButton } from '@nuxt/ui'",High,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
2,Installation,Import Tailwind and Nuxt UI CSS,Required CSS imports in main.css file,@import tailwindcss and @import @nuxt/ui,Skip CSS imports,"@import ""tailwindcss""; @import ""@nuxt/ui"";",No CSS imports,High,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
3,Installation,Wrap app with UApp component,UApp provides global configs for Toast Tooltip and overlays,<UApp> wrapper in app.vue,Skip UApp wrapper,<UApp><NuxtPage/></UApp>,<NuxtPage/> without wrapper,High,https://ui.nuxt.com/docs/components/app
|
||||
4,Components,Use U prefix for components,All Nuxt UI components use U prefix by default,UButton UInput UModal,Button Input Modal,<UButton>Click</UButton>,<Button>Click</Button>,Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
5,Components,Use semantic color props,Use semantic colors like primary secondary error,color="primary" color="error",Hardcoded colors,"<UButton color=""primary"">","<UButton class=""bg-green-500"">",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system
|
||||
6,Components,Use variant prop for styling,Nuxt UI provides solid outline soft subtle ghost link variants,variant="soft" variant="outline",Custom button classes,"<UButton variant=""soft"">","<UButton class=""border bg-transparent"">",Medium,https://ui.nuxt.com/docs/components/button
|
||||
7,Components,Use size prop consistently,Components support xs sm md lg xl sizes,size="sm" size="lg",Arbitrary sizing classes,"<UButton size=""lg"">","<UButton class=""text-xl px-6"">",Low,https://ui.nuxt.com/docs/components/button
|
||||
8,Icons,Use i-{collection}-{name} format for icons,Nuxt UI v4 uses Iconify i-prefix format — lucide:home is v3 legacy,i-lucide-home i-heroicons-user format,lucide:home format (v3 syntax),"<UButton icon=""i-lucide-home"">","<UButton icon=""lucide:home"">",High,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
9,Icons,Use leadingIcon and trailingIcon props,Position icons with dedicated props for clarity,leadingIcon="i-lucide-plus" trailingIcon="i-lucide-arrow-right",Manual icon positioning or slots,"<UButton leadingIcon=""i-lucide-plus"" label=""Add"">","<UButton><UIcon name=""i-lucide-plus""/>Add</UButton>",Low,https://ui.nuxt.com/docs/components/button
|
||||
10,Theming,Configure colors in app.config.ts,Runtime color configuration without restart,ui.colors.primary in app.config.ts,Hardcoded colors in components,"defineAppConfig({ ui: { colors: { primary: 'blue' } } })","<UButton class=""bg-blue-500"">",High,https://ui.nuxt.com/docs/getting-started/theme/design-system
|
||||
11,Theming,Use @theme directive for custom colors,Define design tokens in CSS with Tailwind @theme,@theme { --color-brand-500: #xxx },Inline color definitions,@theme { --color-brand-500: #ef4444; },:style="{ color: '#ef4444' }",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system
|
||||
12,Theming,Extend semantic colors in nuxt.config,Register new colors like tertiary in theme.colors,theme.colors array in ui config,Use undefined colors,"ui: { theme: { colors: ['primary', 'tertiary'] } }","<UButton color=""tertiary""> without config",Medium,https://ui.nuxt.com/docs/getting-started/theme/design-system
|
||||
13,Forms,Use UForm with schema validation,UForm supports Zod Yup Joi Valibot schemas,:schema prop with validation schema,Manual form validation,"<UForm :schema=""schema"" :state=""state"">",Manual @blur validation,High,https://ui.nuxt.com/docs/components/form
|
||||
14,Forms,Use UFormField for field wrapper,Provides label error message and validation display,UFormField with name prop,Manual error handling,"<UFormField name=""email"" label=""Email"">",<div><label>Email</label><UInput/><span>error</span></div>,Medium,https://ui.nuxt.com/docs/components/form-field
|
||||
15,Forms,Handle form submit with @submit,UForm emits submit event with validated data,@submit handler on UForm,@click on submit button,"<UForm @submit=""onSubmit"">","<UButton @click=""onSubmit"">",Medium,https://ui.nuxt.com/docs/components/form
|
||||
16,Forms,Use validateOn prop for validation timing,Control when validation triggers (blur change input),validateOn="['blur']" for performance,Always validate on input,"<UForm :validateOn=""['blur', 'change']"">","<UForm> (validates on every keystroke)",Low,https://ui.nuxt.com/docs/components/form
|
||||
17,Overlays,Use v-model:open for overlay control,Modal Slideover Drawer use v-model:open,v-model:open for controlled state,Manual show/hide logic,"<UModal v-model:open=""isOpen"">",<UModal v-if="isOpen">,Medium,https://ui.nuxt.com/docs/components/modal
|
||||
18,Overlays,Use useOverlay composable for programmatic overlays,Open overlays programmatically — v4 API is create().open() not open(Component),overlay.create(Component).open({ props }) pattern,v3 overlay.open(Component) pattern (removed in v4),"const modal = overlay.create(MyModal); const { result } = modal.open({ title: 'Confirm' })","overlay.open(MyModal, { props: { title: 'Confirm' } })",High,https://ui.nuxt.com/docs/components/modal
|
||||
19,Overlays,Use title and description props,Built-in header support for overlays,title="Confirm" description="Are you sure?",Manual header content,"<UModal title=""Confirm"" description=""Are you sure?"">","<UModal><template #header><h2>Confirm</h2></template>",Low,https://ui.nuxt.com/docs/components/modal
|
||||
20,Dashboard,Use UDashboardSidebar for navigation,Provides collapsible resizable sidebar with mobile support,UDashboardSidebar with header default footer slots,Custom sidebar implementation,<UDashboardSidebar><template #header>...</template></UDashboardSidebar>,<aside class="w-64 border-r">,Medium,https://ui.nuxt.com/docs/components/dashboard-sidebar
|
||||
21,Dashboard,Use UDashboardGroup for layout,Wraps dashboard components with sidebar state management,UDashboardGroup > UDashboardSidebar + UDashboardPanel,Manual layout flex containers,<UDashboardGroup><UDashboardSidebar/><UDashboardPanel/></UDashboardGroup>,"<div class=""flex""><aside/><main/></div>",Medium,https://ui.nuxt.com/docs/components/dashboard-group
|
||||
22,Dashboard,Use UDashboardNavbar for top navigation,Responsive navbar with mobile menu support,UDashboardNavbar in dashboard layout,Custom navbar implementation,<UDashboardNavbar :links="navLinks"/>,<nav class="border-b">,Low,https://ui.nuxt.com/docs/components/dashboard-navbar
|
||||
23,Tables,Use UTable with data and columns props,Powered by TanStack Table with built-in features,:data and :columns props,Manual table markup,"<UTable :data=""users"" :columns=""columns""/>","<table><tr v-for=""user in users"">",High,https://ui.nuxt.com/docs/components/table
|
||||
24,Tables,Define columns with accessorKey,Column definitions use accessorKey for data binding,accessorKey: 'email' in column def,String column names only,"{ accessorKey: 'email', header: 'Email' }","['name', 'email']",Medium,https://ui.nuxt.com/docs/components/table
|
||||
25,Tables,Use cell slot for custom rendering,Customize cell content with scoped slots,#cell-columnName slot,Override entire table,<template #cell-status="{ row }">,Manual column render function,Medium,https://ui.nuxt.com/docs/components/table
|
||||
26,Tables,Enable sorting with sortable column option,Add sortable: true to column definition,sortable: true in column,Manual sort implementation,"{ accessorKey: 'name', sortable: true }",@click="sortBy('name')",Low,https://ui.nuxt.com/docs/components/table
|
||||
27,Navigation,Use UNavigationMenu for nav links,Horizontal or vertical navigation with dropdown support,UNavigationMenu with items array,Manual nav with v-for,"<UNavigationMenu :items=""navItems""/>","<nav><a v-for=""item in items"">",Medium,https://ui.nuxt.com/docs/components/navigation-menu
|
||||
28,Navigation,Use UBreadcrumb for page hierarchy,Automatic breadcrumb with NuxtLink support,:items array with label and to,Manual breadcrumb links,"<UBreadcrumb :items=""breadcrumbs""/>","<nav><span v-for=""crumb in crumbs"">",Low,https://ui.nuxt.com/docs/components/breadcrumb
|
||||
29,Navigation,Use UTabs for tabbed content,Tab navigation with content panels,UTabs with items containing slot content,Manual tab state,"<UTabs :items=""tabs""/>","<div><button @click=""tab=1"">",Medium,https://ui.nuxt.com/docs/components/tabs
|
||||
30,Feedback,Use useToast for notifications,Composable for toast notifications,useToast().add({ title description }),Alert components for toasts,"const toast = useToast(); toast.add({ title: 'Saved' })",<UAlert v-if="showSuccess">,High,https://ui.nuxt.com/docs/components/toast
|
||||
31,Feedback,Use UAlert for inline messages,Static alert messages with icon and actions,UAlert with title description color,Toast for static messages,"<UAlert title=""Warning"" color=""warning""/>",useToast for inline alerts,Medium,https://ui.nuxt.com/docs/components/alert
|
||||
32,Feedback,Use USkeleton for loading states,Placeholder content during data loading,USkeleton with appropriate size,Spinner for content loading,<USkeleton class="h-4 w-32"/>,<UIcon name="lucide:loader" class="animate-spin"/>,Low,https://ui.nuxt.com/docs/components/skeleton
|
||||
33,Color Mode,Use UColorModeButton for theme toggle,Built-in light/dark mode toggle button,UColorModeButton component,Manual color mode logic,<UColorModeButton/>,"<button @click=""toggleColorMode"">",Low,https://ui.nuxt.com/docs/components/color-mode-button
|
||||
34,Color Mode,Use UColorModeSelect for theme picker,Dropdown to select system light or dark mode,UColorModeSelect component,Custom select for theme,<UColorModeSelect/>,"<USelect v-model=""colorMode"" :items=""modes""/>",Low,https://ui.nuxt.com/docs/components/color-mode-select
|
||||
35,Customization,Use ui prop for component styling,Override component styles via ui prop,ui prop with slot class overrides,Global CSS overrides,"<UButton :ui=""{ base: 'rounded-full' }""/>",<UButton class="!rounded-full"/>,Medium,https://ui.nuxt.com/docs/getting-started/theme/components
|
||||
36,Customization,Configure default variants in nuxt.config,Set default color and size for all components,theme.defaultVariants in ui config,Repeat props on every component,"ui: { theme: { defaultVariants: { color: 'neutral' } } }","<UButton color=""neutral""> everywhere",Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
37,Customization,Use app.config.ts for theme overrides,Runtime theme customization,defineAppConfig with ui key,nuxt.config for runtime values,"defineAppConfig({ ui: { button: { defaultVariants: { size: 'sm' } } } })","nuxt.config ui.button.size: 'sm'",Medium,https://ui.nuxt.com/docs/getting-started/theme/components
|
||||
38,Performance,Enable component detection,Tree-shake unused component CSS,experimental.componentDetection: true,Include all component CSS,"ui: { experimental: { componentDetection: true } }","ui: {} (includes all CSS)",Low,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
39,Performance,Use UTable virtualize for large data,Enable virtualization for 1000+ rows,:virtualize prop on UTable,Render all rows,"<UTable :data=""largeData"" virtualize/>","<UTable :data=""largeData""/>",Medium,https://ui.nuxt.com/docs/components/table
|
||||
40,Accessibility,Use semantic component props,Components have built-in ARIA support,Use title description label props,Skip accessibility props,"<UModal title=""Settings"">","<UModal><h2>Settings</h2>",Medium,https://ui.nuxt.com/docs/components/modal
|
||||
41,Accessibility,Use UFormField for form accessibility,Automatic label-input association,UFormField wraps inputs,Manual id and for attributes,"<UFormField label=""Email""><UInput/></UFormField>","<label for=""email"">Email</label><UInput id=""email""/>",High,https://ui.nuxt.com/docs/components/form-field
|
||||
42,Content,Use UContentToc for table of contents,Automatic TOC with active heading highlight,UContentToc with :links,Manual TOC implementation,"<UContentToc :links=""toc""/>","<nav><a v-for=""heading in headings"">",Low,https://ui.nuxt.com/docs/components/content-toc
|
||||
43,Content,Use UContentSearch for docs search,Command palette for documentation search,UContentSearch with Nuxt Content,Custom search implementation,<UContentSearch/>,<UCommandPalette :groups="searchResults"/>,Low,https://ui.nuxt.com/docs/components/content-search
|
||||
44,AI/Chat,Use UChatMessages for chat UI,Designed for Vercel AI SDK integration,UChatMessages with messages array,Custom chat message list,"<UChatMessages :messages=""messages""/>","<div v-for=""msg in messages"">",Medium,https://ui.nuxt.com/docs/components/chat-messages
|
||||
45,AI/Chat,Use UChatPrompt for input,Enhanced textarea for AI prompts,UChatPrompt with v-model,Basic textarea,<UChatPrompt v-model="prompt"/>,<UTextarea v-model="prompt"/>,Medium,https://ui.nuxt.com/docs/components/chat-prompt
|
||||
46,Editor,Use UEditor for rich text,TipTap-based editor with toolbar support,UEditor with v-model:content,Custom TipTap setup,"<UEditor v-model:content=""content""/>",Manual TipTap initialization,Medium,https://ui.nuxt.com/docs/components/editor
|
||||
47,Links,Use to prop for navigation,UButton and ULink support NuxtLink to prop,to="/dashboard" for internal links,href for internal navigation,"<UButton to=""/dashboard"">","<UButton href=""/dashboard"">",Medium,https://ui.nuxt.com/docs/components/button
|
||||
48,Links,Use external prop for outside links,Explicitly mark external links,target="_blank" with external URLs,Forget rel="noopener","<UButton to=""https://example.com"" target=""_blank"">","<UButton href=""https://..."">",Low,https://ui.nuxt.com/docs/components/link
|
||||
49,Loading,Use loadingAuto on buttons,Automatic loading state from @click promise,loadingAuto prop on UButton,Manual loading state,"<UButton loadingAuto @click=""async () => await save()"">","<UButton :loading=""isLoading"" @click=""save"">",Low,https://ui.nuxt.com/docs/components/button
|
||||
50,Loading,Use UForm loadingAuto,Auto-disable form during submit,loadingAuto on UForm (default true),Manual form disabled state,"<UForm @submit=""handleSubmit"">","<UForm :disabled=""isSubmitting"">",Low,https://ui.nuxt.com/docs/components/form
|
||||
51,Installation,Do not manually add auto-registered modules,Nuxt UI v4 auto-registers @nuxt/icon @nuxt/fonts @nuxtjs/color-mode,Configure via root-level keys in nuxt.config,Adding them to modules array causes duplicate registration,"icon: { /* opts */ } in nuxt.config","modules: ['@nuxt/ui', '@nuxt/icon']",High,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
52,Installation,Use official templates to bootstrap projects,Nuxt UI provides starter templates via nuxi init,npx nuxi init -t ui/dashboard for dashboard project,Manual project setup from scratch,"npx nuxi@latest init -t ui/dashboard","pnpm create nuxt app (manual UI setup)",Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
53,Icons,Install icon collections locally for SSR,Local Iconify JSON prevents network requests and flash,pnpm i @iconify-json/lucide for reliable server rendering,Rely on remote icon fetching in production,"pnpm i @iconify-json/lucide @iconify-json/simple-icons",No local icon packages,Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
54,Icons,Override default component icons globally,Components use default icons configurable via appConfig.ui.icons,Set loading close check icons in app.config.ts,Accept default icons for all components,"defineAppConfig({ ui: { icons: { loading: 'i-lucide-refresh-cw', close: 'i-lucide-x' } } })","<UModal :close-icon=""'i-lucide-x'""> on every usage",Low,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
55,Forms,Use UFileUpload for file input,Built-in drag-drop and preview support,UFileUpload with v-model and accept prop,Custom input type=file,"<UFileUpload v-model=""files"" accept=""image/*"" multiple/>","<input type=""file"" @change=""handleFiles"">",Medium,https://ui.nuxt.com/docs/components/file-upload
|
||||
56,Forms,Use UInputDate for date selection,Locale-aware date picker built on UCalendar,UInputDate with v-model and locale prop,Third-party date picker libraries,"<UInputDate v-model=""date"" />","<DatePicker v-model=""date"" />",Medium,https://ui.nuxt.com/docs/components/input-date
|
||||
57,Forms,Use UInputTags for tag input,Multi-value tag input with keyboard support,UInputTags with v-model and max prop,Custom chip input implementation,"<UInputTags v-model=""tags"" :max=""5"" />","<UInput @keydown.enter=""addTag"">",Low,https://ui.nuxt.com/docs/components/input-tags
|
||||
58,Forms,Use UColorPicker for color selection,Full-featured color picker with multiple format support,UColorPicker with v-model and format prop,Native input type=color,"<UColorPicker v-model=""color"" format=""hex"" />","<input type=""color"" v-model=""color"">",Low,https://ui.nuxt.com/docs/components/color-picker
|
||||
59,Data,Use UTree for hierarchical data,Built-in tree component with expand/collapse,UTree with items prop containing nested children,Custom recursive component,"<UTree :items=""treeItems"" />","<TreeNode v-for=""item in items"" :key=""item.id"">",Low,https://ui.nuxt.com/docs/components/tree
|
||||
60,Data,Use UMarquee for infinite scroll content,Animated infinite scroll band for logos or testimonials,UMarquee with repeat and pauseOnHover props,CSS animation keyframes loop,"<UMarquee :repeat=""3"" pause-on-hover>","<div class=""animate-marquee"">",Low,https://ui.nuxt.com/docs/components/marquee
|
||||
61,Overlays,Use UContextMenu for right-click menus,Context menu triggered by right-click on children,UContextMenu wrapping target element,Browser default context menu,<UContextMenu :items="menuItems"><div>Right-click me</div></UContextMenu>,"<div @contextmenu.prevent=""showMenu"">",Medium,https://ui.nuxt.com/docs/components/context-menu
|
||||
62,Overlays,Await overlay result for confirmation dialogs,useOverlay returns a result Promise resolving to user action,await instance.result to get confirm/cancel,Emit events from overlay components,"const { result } = modal.open(); if (await result) { deleteItem() }","overlay.open(Confirm, { onConfirm: deleteItem })",Medium,https://ui.nuxt.com/docs/components/modal
|
||||
63,Navigation,Use UCommandPalette with grouped items,Command palette supports grouped search with icons and kbds,groups array with id label items,Flat list without categories,"<UCommandPalette :groups=""[{ id: 'actions', label: 'Actions', items }]""/>","<UCommandPalette :items=""flatList""/>",Medium,https://ui.nuxt.com/docs/components/command-palette
|
||||
64,Navigation,Use defineShortcuts with extractShortcuts,Wire keyboard shortcuts from menu item kbds automatically,extractShortcuts(items) + defineShortcuts to sync keybindings,Manually duplicate shortcuts from menu items,"defineShortcuts(extractShortcuts(items))","defineShortcuts({ meta_n: () => newFile() }) // duplicated from items",Low,https://ui.nuxt.com/docs/composables/define-shortcuts
|
||||
65,Layout,Use UHeader and UFooter for page layout,Responsive header/footer with built-in mobile menu,UHeader with #default slot for nav UFooter with columns,Custom header/footer from scratch,"<UHeader><template #right><UNavigationMenu/></template></UHeader>","<header class=""sticky top-0"">",Low,https://ui.nuxt.com/docs/components/header
|
||||
66,Layout,Use UPageAside for sidebar content,Sidebar that hides below lg breakpoint automatically,UPageAside for docs and landing page sidebars,Manual hidden lg: classes,"<UPageAside><UNavigationMenu orientation=""vertical""/></UPageAside>","<aside class=""hidden lg:block"">",Low,https://ui.nuxt.com/docs/components/page-aside
|
||||
67,Color Mode,Wrap custom color mode toggles in ClientOnly,Prevents hydration mismatch on server-rendered color mode,ClientOnly with fallback placeholder,Direct useColorMode in template without ClientOnly,"<ClientOnly><USwitch v-model=""isDark""/><template #fallback><div class=""size-8""/></template></ClientOnly>",<USwitch v-model="isDark"/> directly in template,Medium,https://ui.nuxt.com/docs/getting-started/installation/nuxt
|
||||
68,Theming,Read generated theme file to find slot names,Nuxt UI generates theme files listing all component slots and variants,Check .nuxt/ui/<component>.ts for slot names,Guess slot names or use trial-and-error,".nuxt/ui/button.ts for UButton slot names","<UButton :ui=""{ base: 'rounded-full' }""/> without checking slots",Medium,https://ui.nuxt.com/docs/getting-started/theme/components
|
||||
69,Composables,Use defineShortcuts whenever keyword shortcut,whenever array condition prevents shortcut firing when inactive,whenever: [isFormValid] to guard shortcut execution,Always-on shortcuts that fire in wrong context,"defineShortcuts({ meta_enter: { handler: submit, whenever: [isFormValid] } })","defineShortcuts({ meta_enter: () => submit() }) // fires even when invalid",Low,https://ui.nuxt.com/docs/composables/define-shortcuts
|
||||
70,i18n,Use UApp locale prop for internationalization,Nuxt UI supports 50+ built-in locales via locale prop on UApp,Import locale from @nuxt/ui/locale and pass to UApp,Manual translation of component UI strings,"import { fr } from '@nuxt/ui/locale'; // <UApp :locale=""fr"">","<UModal title=""Fermer""> manually for each component",Low,https://ui.nuxt.com/docs/composables/define-locale
|
||||
|
Can't render this file because it contains an unexpected character in line 6 and column 94.
|
|
|
@ -1,59 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Routing,Use file-based routing,Create routes by adding files in pages directory,pages/ directory with index.vue,Manual route configuration,pages/dashboard/index.vue,Custom router setup,Medium,https://nuxt.com/docs/getting-started/routing
|
||||
2,Routing,Use dynamic route parameters,Create dynamic routes with bracket syntax,[id].vue for dynamic params,Hardcoded routes for dynamic content,pages/posts/[id].vue,pages/posts/post1.vue,Medium,https://nuxt.com/docs/getting-started/routing
|
||||
3,Routing,Use catch-all routes,Handle multiple path segments with [...slug],[...slug].vue for catch-all,Multiple nested dynamic routes,pages/[...slug].vue,pages/[a]/[b]/[c].vue,Low,https://nuxt.com/docs/getting-started/routing
|
||||
4,Routing,Define page metadata with definePageMeta,Set page-level configuration and middleware,definePageMeta for layout middleware title,Manual route meta configuration,"definePageMeta({ layout: 'admin', middleware: 'auth' })",router.beforeEach for page config,High,https://nuxt.com/docs/api/utils/define-page-meta
|
||||
5,Routing,Use validate for route params,Validate dynamic route parameters before rendering,validate function in definePageMeta,Manual validation in setup,"definePageMeta({ validate: (route) => /^\d+$/.test(route.params.id) })",if (!valid) navigateTo('/404'),Medium,https://nuxt.com/docs/api/utils/define-page-meta
|
||||
6,Rendering,Use SSR by default,Server-side rendering is enabled by default,Keep ssr: true (default),Disable SSR unnecessarily,ssr: true (default),ssr: false for all pages,High,https://nuxt.com/docs/guide/concepts/rendering
|
||||
7,Rendering,Use .client suffix for client-only components,Mark components to render only on client,ComponentName.client.vue suffix,v-if with process.client check,Comments.client.vue,<div v-if="process.client"><Comments/></div>,Medium,https://nuxt.com/docs/guide/directory-structure/components
|
||||
8,Rendering,Use .server suffix for server-only components,Mark components to render only on server,ComponentName.server.vue suffix,Manual server check,HeavyMarkdown.server.vue,v-if="process.server",Low,https://nuxt.com/docs/guide/directory-structure/components
|
||||
9,DataFetching,Use useFetch for simple data fetching,Wrapper around useAsyncData for URL fetching,useFetch for API calls,$fetch in onMounted,"const { data } = await useFetch('/api/posts')","onMounted(async () => { data.value = await $fetch('/api/posts') })",High,https://nuxt.com/docs/api/composables/use-fetch
|
||||
10,DataFetching,Use useAsyncData for complex fetching,Fine-grained control over async data,useAsyncData for CMS or custom fetching,useFetch for non-URL data sources,"const { data } = await useAsyncData('posts', () => cms.getPosts())","const { data } = await useFetch(() => cms.getPosts())",Medium,https://nuxt.com/docs/api/composables/use-async-data
|
||||
11,DataFetching,Use $fetch for non-reactive requests,$fetch for event handlers and non-component code,$fetch in event handlers or server routes,useFetch in click handlers,"async function submit() { await $fetch('/api/submit', { method: 'POST' }) }","async function submit() { await useFetch('/api/submit') }",High,https://nuxt.com/docs/api/utils/dollarfetch
|
||||
12,DataFetching,Use lazy option for non-blocking fetch,Defer data fetching for better initial load,lazy: true for below-fold content,Blocking fetch for non-critical data,"useFetch('/api/comments', { lazy: true })",await useFetch('/api/comments') for footer,Medium,https://nuxt.com/docs/api/composables/use-fetch
|
||||
13,DataFetching,Use server option to control fetch location,Choose where data is fetched,server: false for client-only data,Server fetch for user-specific client data,"useFetch('/api/user-preferences', { server: false })",useFetch for localStorage-dependent data,Medium,https://nuxt.com/docs/api/composables/use-fetch
|
||||
14,DataFetching,Use pick to reduce payload size,Select only needed fields from response,pick option for large responses,Fetching entire objects when few fields needed,"useFetch('/api/user', { pick: ['id', 'name'] })",useFetch('/api/user') then destructure,Low,https://nuxt.com/docs/api/composables/use-fetch
|
||||
15,DataFetching,Use transform for data manipulation,Transform data before storing in state,transform option for data shaping,Manual transformation after fetch,"useFetch('/api/posts', { transform: (posts) => posts.map(p => p.title) })",const titles = data.value.map(p => p.title),Low,https://nuxt.com/docs/api/composables/use-fetch
|
||||
16,DataFetching,Handle loading and error states,Always handle pending and error states,Check status pending error refs,Ignoring loading states,"<div v-if=""status === 'pending'"">Loading...</div>",No loading indicator,High,https://nuxt.com/docs/getting-started/data-fetching
|
||||
17,Lifecycle,Avoid side effects in script setup root,Move side effects to lifecycle hooks,Side effects in onMounted,setInterval in root script setup,"onMounted(() => { interval = setInterval(...) })","<script setup>setInterval(...)</script>",High,https://nuxt.com/docs/guide/concepts/nuxt-lifecycle
|
||||
18,Lifecycle,Use onMounted for DOM access,Access DOM only after component is mounted,onMounted for DOM manipulation,Direct DOM access in setup,"onMounted(() => { document.getElementById('el') })","<script setup>document.getElementById('el')</script>",High,https://nuxt.com/docs/api/composables/on-mounted
|
||||
19,Lifecycle,Use nextTick for post-render access,Wait for DOM updates before accessing elements,await nextTick() after state changes,Immediate DOM access after state change,"count.value++; await nextTick(); el.value.focus()","count.value++; el.value.focus()",Medium,https://nuxt.com/docs/api/utils/next-tick
|
||||
20,Lifecycle,Use onPrehydrate for pre-hydration logic,Run code before Nuxt hydrates the page,onPrehydrate for client setup,onMounted for hydration-critical code,"onPrehydrate(() => { console.log(window) })",onMounted for pre-hydration needs,Low,https://nuxt.com/docs/api/composables/on-prehydrate
|
||||
21,Server,Use server/api for API routes,Create API endpoints in server/api directory,server/api/users.ts for /api/users,Manual Express setup,server/api/hello.ts -> /api/hello,app.get('/api/hello'),High,https://nuxt.com/docs/guide/directory-structure/server
|
||||
22,Server,Use defineEventHandler for handlers,Define server route handlers,defineEventHandler for all handlers,export default function,"export default defineEventHandler((event) => { return { hello: 'world' } })","export default function(req, res) {}",High,https://nuxt.com/docs/guide/directory-structure/server
|
||||
23,Server,Use server/routes for non-api routes,Routes without /api prefix,server/routes for custom paths,server/api for non-api routes,server/routes/sitemap.xml.ts,server/api/sitemap.xml.ts,Medium,https://nuxt.com/docs/guide/directory-structure/server
|
||||
24,Server,Use getQuery and readBody for input,Access query params and request body,getQuery(event) readBody(event),Direct event access,"const { id } = getQuery(event)",event.node.req.query,Medium,https://nuxt.com/docs/guide/directory-structure/server
|
||||
25,Server,Validate server input,Always validate input in server handlers,Zod or similar for validation,Trust client input,"const body = await readBody(event); schema.parse(body)",const body = await readBody(event),High,https://nuxt.com/docs/guide/directory-structure/server
|
||||
26,State,Use useState for shared reactive state,SSR-friendly shared state across components,useState for cross-component state,ref for shared state,"const count = useState('count', () => 0)",const count = ref(0) in composable,High,https://nuxt.com/docs/api/composables/use-state
|
||||
27,State,Use unique keys for useState,Prevent state conflicts with unique keys,Descriptive unique keys for each state,Generic or duplicate keys,"useState('user-preferences', () => ({}))",useState('data') in multiple places,Medium,https://nuxt.com/docs/api/composables/use-state
|
||||
28,State,Use Pinia for complex state,Pinia for advanced state management,@pinia/nuxt for complex apps,Custom state management,useMainStore() with Pinia,Custom reactive store implementation,Medium,https://nuxt.com/docs/getting-started/state-management
|
||||
29,State,Use callOnce for one-time async operations,Ensure async operations run only once,callOnce for store initialization,Direct await in component,"await callOnce(store.fetch)",await store.fetch() on every render,Medium,https://nuxt.com/docs/api/utils/call-once
|
||||
30,SEO,Use useSeoMeta for SEO tags,Type-safe SEO meta tag management,useSeoMeta for meta tags,useHead for simple meta,"useSeoMeta({ title: 'Home', ogTitle: 'Home', description: '...' })","useHead({ meta: [{ name: 'description', content: '...' }] })",High,https://nuxt.com/docs/api/composables/use-seo-meta
|
||||
31,SEO,Use reactive values in useSeoMeta,Dynamic SEO tags with refs or getters,Computed getters for dynamic values,Static values for dynamic content,"useSeoMeta({ title: () => post.value.title })","useSeoMeta({ title: post.value.title })",Medium,https://nuxt.com/docs/api/composables/use-seo-meta
|
||||
32,SEO,Use useHead for non-meta head elements,Scripts styles links in head,useHead for scripts and links,useSeoMeta for scripts,"useHead({ script: [{ src: '/analytics.js' }] })","useSeoMeta({ script: '...' })",Medium,https://nuxt.com/docs/api/composables/use-head
|
||||
33,SEO,Include OpenGraph tags,Add OG tags for social sharing,ogTitle ogDescription ogImage,Missing social preview,"useSeoMeta({ ogImage: '/og.png', twitterCard: 'summary_large_image' })",No OG configuration,Medium,https://nuxt.com/docs/api/composables/use-seo-meta
|
||||
34,Middleware,Use defineNuxtRouteMiddleware,Define route middleware properly,defineNuxtRouteMiddleware wrapper,export default function,"export default defineNuxtRouteMiddleware((to, from) => {})","export default function(to, from) {}",High,https://nuxt.com/docs/guide/directory-structure/middleware
|
||||
35,Middleware,Use navigateTo for redirects,Redirect in middleware with navigateTo,return navigateTo('/login'),router.push in middleware,"if (!auth) return navigateTo('/login')","if (!auth) router.push('/login')",High,https://nuxt.com/docs/api/utils/navigate-to
|
||||
36,Middleware,Reference middleware in definePageMeta,Apply middleware to specific pages,middleware array in definePageMeta,Global middleware for page-specific,definePageMeta({ middleware: ['auth'] }),Global auth check for one page,Medium,https://nuxt.com/docs/guide/directory-structure/middleware
|
||||
37,Middleware,Use .global suffix for global middleware,Apply middleware to all routes,auth.global.ts for app-wide auth,Manual middleware on every page,middleware/auth.global.ts,middleware: ['auth'] on every page,Medium,https://nuxt.com/docs/guide/directory-structure/middleware
|
||||
38,ErrorHandling,Use createError for errors,Create errors with proper status codes,createError with statusCode,throw new Error,"throw createError({ statusCode: 404, statusMessage: 'Not Found' })",throw new Error('Not Found'),High,https://nuxt.com/docs/api/utils/create-error
|
||||
39,ErrorHandling,Use NuxtErrorBoundary for local errors,Handle errors within component subtree,NuxtErrorBoundary for component errors,Global error page for local errors,"<NuxtErrorBoundary @error=""log""><template #error=""{ error }"">",error.vue for component errors,Medium,https://nuxt.com/docs/getting-started/error-handling
|
||||
40,ErrorHandling,Use clearError to recover from errors,Clear error state and optionally redirect,clearError({ redirect: '/' }),Manual error state reset,clearError({ redirect: '/home' }),error.value = null,Medium,https://nuxt.com/docs/api/utils/clear-error
|
||||
41,ErrorHandling,Use short statusMessage,Keep statusMessage brief for security,Short generic messages,Detailed error info in statusMessage,"createError({ statusCode: 400, statusMessage: 'Bad Request' })","createError({ statusMessage: 'Invalid user ID: 123' })",High,https://nuxt.com/docs/getting-started/error-handling
|
||||
42,Link,Use NuxtLink for internal navigation,Client-side navigation with prefetching,<NuxtLink to> for internal links,<a href> for internal links,<NuxtLink to="/about">About</NuxtLink>,<a href="/about">About</a>,High,https://nuxt.com/docs/api/components/nuxt-link
|
||||
43,Link,Configure prefetch behavior,Control when prefetching occurs,prefetchOn for interaction-based,Default prefetch for low-priority,"<NuxtLink prefetch-on=""interaction"">",Always default prefetch,Low,https://nuxt.com/docs/api/components/nuxt-link
|
||||
44,Link,Use useRouter for programmatic navigation,Navigate programmatically,useRouter().push() for navigation,Direct window.location,"const router = useRouter(); router.push('/dashboard')",window.location.href = '/dashboard',Medium,https://nuxt.com/docs/api/composables/use-router
|
||||
45,Link,Use navigateTo in composables,Navigate outside components,navigateTo() in middleware or plugins,useRouter in non-component code,return navigateTo('/login'),router.push in middleware,Medium,https://nuxt.com/docs/api/utils/navigate-to
|
||||
46,AutoImports,Leverage auto-imports,Use auto-imported composables directly,Direct use of ref computed useFetch,Manual imports for Nuxt composables,"const count = ref(0)","import { ref } from 'vue'; const count = ref(0)",Medium,https://nuxt.com/docs/guide/concepts/auto-imports
|
||||
47,AutoImports,Use #imports for explicit imports,Explicit imports when needed,#imports for clarity or disabled auto-imports,"import from 'vue' when auto-import enabled","import { ref } from '#imports'","import { ref } from 'vue'",Low,https://nuxt.com/docs/guide/concepts/auto-imports
|
||||
48,AutoImports,Configure third-party auto-imports,Add external package auto-imports,imports.presets in nuxt.config,Manual imports everywhere,"imports: { presets: [{ from: 'vue-i18n', imports: ['useI18n'] }] }",import { useI18n } everywhere,Low,https://nuxt.com/docs/guide/concepts/auto-imports
|
||||
49,Plugins,Use defineNuxtPlugin,Define plugins properly,defineNuxtPlugin wrapper,export default function,"export default defineNuxtPlugin((nuxtApp) => {})","export default function(ctx) {}",High,https://nuxt.com/docs/guide/directory-structure/plugins
|
||||
50,Plugins,Use provide for injection,Provide helpers across app,return { provide: {} } for type safety,nuxtApp.provide without types,"return { provide: { hello: (name) => `Hello ${name}!` } }","nuxtApp.provide('hello', fn)",Medium,https://nuxt.com/docs/guide/directory-structure/plugins
|
||||
51,Plugins,Use .client or .server suffix,Control plugin execution environment,plugin.client.ts for client-only,if (process.client) checks,analytics.client.ts,"if (process.client) { // analytics }",Medium,https://nuxt.com/docs/guide/directory-structure/plugins
|
||||
52,Environment,Use runtimeConfig for env vars,Access environment variables safely,runtimeConfig in nuxt.config,process.env directly,"runtimeConfig: { apiSecret: '', public: { apiBase: '' } }",process.env.API_SECRET in components,High,https://nuxt.com/docs/guide/going-further/runtime-config
|
||||
53,Environment,Use NUXT_ prefix for env override,Override config with environment variables,NUXT_API_SECRET NUXT_PUBLIC_API_BASE,Custom env var names,NUXT_PUBLIC_API_BASE=https://api.example.com,API_BASE=https://api.example.com,High,https://nuxt.com/docs/guide/going-further/runtime-config
|
||||
54,Environment,Access public config with useRuntimeConfig,Get public config in components,useRuntimeConfig().public,Direct process.env access,const config = useRuntimeConfig(); config.public.apiBase,process.env.NUXT_PUBLIC_API_BASE,High,https://nuxt.com/docs/api/composables/use-runtime-config
|
||||
55,Environment,Keep secrets in private config,Server-only secrets in runtimeConfig root,runtimeConfig.apiSecret (server only),Secrets in public config,runtimeConfig: { dbPassword: '' },runtimeConfig: { public: { dbPassword: '' } },High,https://nuxt.com/docs/guide/going-further/runtime-config
|
||||
56,Performance,Use Lazy prefix for code splitting,Lazy load components with Lazy prefix,<LazyComponent> for below-fold,Eager load all components,<LazyMountainsList v-if="show"/>,<MountainsList/> for hidden content,Medium,https://nuxt.com/docs/guide/directory-structure/components
|
||||
57,Performance,Use useLazyFetch for non-blocking data,Alias for useFetch with lazy: true,useLazyFetch for secondary data,useFetch for all requests,"const { data } = useLazyFetch('/api/comments')",await useFetch for comments section,Medium,https://nuxt.com/docs/api/composables/use-lazy-fetch
|
||||
58,Performance,Use lazy hydration for interactivity,Delay component hydration until needed,LazyComponent with hydration strategy,Immediate hydration for all,<LazyModal hydrate-on-visible/>,<Modal/> in footer,Low,https://nuxt.com/docs/guide/going-further/experimental-features
|
||||
|
Can't render this file because it contains an unexpected character in line 8 and column 193.
|
|
|
@ -1,52 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Components,Use functional components,Hooks-based components are standard,Functional components with hooks,Class components,const App = () => { },class App extends Component,Medium,https://reactnative.dev/docs/intro-react
|
||||
2,Components,Keep components small,Single responsibility principle,Split into smaller components,Large monolithic components,<Header /><Content /><Footer />,500+ line component,Medium,
|
||||
3,Components,Use TypeScript,Type safety for props and state,TypeScript for new projects,JavaScript without types,const Button: FC<Props> = () => { },const Button = (props) => { },Medium,
|
||||
4,Components,Colocate component files,Keep related files together,Component folder with styles,Flat structure,components/Button/index.tsx styles.ts,components/Button.tsx styles/button.ts,Low,
|
||||
5,Styling,Use StyleSheet.create,Optimized style objects,StyleSheet for all styles,Inline style objects,StyleSheet.create({ container: {} }),style={{ margin: 10 }},High,https://reactnative.dev/docs/stylesheet
|
||||
6,Styling,Avoid inline styles,Prevent object recreation,Styles in StyleSheet,Inline style objects in render,style={styles.container},"style={{ margin: 10, padding: 5 }}",Medium,
|
||||
7,Styling,Use flexbox for layout,React Native uses flexbox,flexDirection alignItems justifyContent,Absolute positioning everywhere,flexDirection: 'row',position: 'absolute' everywhere,Medium,https://reactnative.dev/docs/flexbox
|
||||
8,Styling,Handle platform differences,Platform-specific styles,Platform.select or .ios/.android files,Same styles for both platforms,"Platform.select({ ios: {}, android: {} })",Hardcoded iOS values,Medium,https://reactnative.dev/docs/platform-specific-code
|
||||
9,Styling,Use responsive dimensions,Scale for different screens,Dimensions or useWindowDimensions,Fixed pixel values,useWindowDimensions(),width: 375,Medium,
|
||||
10,Navigation,Use React Navigation,Standard navigation library,React Navigation for routing,Manual navigation management,createStackNavigator(),Custom navigation state,Medium,https://reactnavigation.org/
|
||||
11,Navigation,Type navigation params,Type-safe navigation,Typed navigation props,Untyped navigation,"navigation.navigate<RootStackParamList>('Home', { id })","navigation.navigate('Home', { id })",Medium,
|
||||
12,Navigation,Use deep linking,Support URL-based navigation,Configure linking prop,No deep link support,linking: { prefixes: [] },No linking configuration,Medium,https://reactnavigation.org/docs/deep-linking/
|
||||
13,Navigation,Handle back button,Android back button handling,useFocusEffect with BackHandler,Ignore back button,BackHandler.addEventListener,No back handler,High,
|
||||
14,State,Use useState for local state,Simple component state,useState for UI state,Class component state,"const [count, setCount] = useState(0)",this.state = { count: 0 },Medium,
|
||||
15,State,Use useReducer for complex state,Complex state logic,useReducer for related state,Multiple useState for related values,useReducer(reducer initialState),5+ useState calls,Medium,
|
||||
16,State,Use context sparingly,Context for global state,Context for theme auth locale,Context for frequently changing data,ThemeContext for app theme,Context for list item data,Medium,
|
||||
17,State,Consider Zustand or Redux,External state management,Zustand for simple Redux for complex,useState for global state,create((set) => ({ })),Prop drilling global state,Medium,
|
||||
18,Lists,Use FlatList for long lists,Virtualized list rendering,FlatList for 50+ items,ScrollView with map,<FlatList data={items} />,<ScrollView>{items.map()}</ScrollView>,High,https://reactnative.dev/docs/flatlist
|
||||
19,Lists,Provide keyExtractor,Unique keys for list items,keyExtractor with stable ID,Index as key,keyExtractor={(item) => item.id},"keyExtractor={(_, index) => index}",High,
|
||||
20,Lists,Optimize renderItem,Memoize list item components,React.memo for list items,Inline render function,renderItem={({ item }) => <MemoizedItem item={item} />},renderItem={({ item }) => <View>...</View>},High,
|
||||
21,Lists,Use getItemLayout for fixed height,Skip measurement for performance,getItemLayout when height known,Dynamic measurement for fixed items,"getItemLayout={(_, index) => ({ length: 50, offset: 50 * index, index })}",No getItemLayout for fixed height,Medium,
|
||||
22,Lists,Implement windowSize,Control render window,Smaller windowSize for memory,Default windowSize for large lists,windowSize={5},windowSize={21} for huge lists,Medium,
|
||||
23,Performance,Use React.memo,Prevent unnecessary re-renders,memo for pure components,No memoization,export default memo(MyComponent),export default MyComponent,Medium,
|
||||
24,Performance,Use useCallback for handlers,Stable function references,useCallback for props,New function on every render,"useCallback(() => {}, [deps])",() => handlePress(),Medium,
|
||||
25,Performance,Use useMemo for expensive ops,Cache expensive calculations,useMemo for heavy computations,Recalculate every render,"useMemo(() => expensive(), [deps])",const result = expensive(),Medium,
|
||||
26,Performance,Avoid anonymous functions in JSX,Prevent re-renders,Named handlers or useCallback,Inline arrow functions,onPress={handlePress},onPress={() => doSomething()},Medium,
|
||||
27,Performance,Use Hermes engine,Improved startup and memory,Enable Hermes in build,JavaScriptCore for new projects,hermes_enabled: true,hermes_enabled: false,Medium,https://reactnative.dev/docs/hermes
|
||||
28,Images,Use expo-image,Modern performant image component for React Native,"Use expo-image for caching, blurring, and performance",Use default Image for heavy lists or unmaintained libraries,<Image source={url} cachePolicy='memory-disk' /> (expo-image),<FastImage source={url} />,Medium,https://docs.expo.dev/versions/latest/sdk/image/
|
||||
29,Images,Specify image dimensions,Prevent layout shifts,width and height for remote images,No dimensions for network images,<Image style={{ width: 100 height: 100 }} />,<Image source={{ uri }} /> no size,High,
|
||||
30,Images,Use resizeMode,Control image scaling,resizeMode cover contain,Stretch images,"resizeMode=""cover""",No resizeMode,Low,
|
||||
31,Forms,Use controlled inputs,State-controlled form fields,value + onChangeText,Uncontrolled inputs,<TextInput value={text} onChangeText={setText} />,<TextInput defaultValue={text} />,Medium,
|
||||
32,Forms,Handle keyboard,Manage keyboard visibility,KeyboardAvoidingView,Content hidden by keyboard,"<KeyboardAvoidingView behavior=""padding"">",No keyboard handling,High,https://reactnative.dev/docs/keyboardavoidingview
|
||||
33,Forms,Use proper keyboard types,Appropriate keyboard for input,keyboardType for input type,Default keyboard for all,"keyboardType=""email-address""","keyboardType=""default"" for email",Low,
|
||||
34,Touch,Use Pressable,Modern touch handling,Pressable for touch interactions,TouchableOpacity for new code,<Pressable onPress={} />,<TouchableOpacity onPress={} />,Low,https://reactnative.dev/docs/pressable
|
||||
35,Touch,Provide touch feedback,Visual feedback on press,Ripple or opacity change,No feedback on press,android_ripple={{ color: 'gray' }},No press feedback,Medium,
|
||||
36,Touch,Set hitSlop for small targets,Increase touch area,hitSlop for icons and small buttons,Tiny touch targets,hitSlop={{ top: 10 bottom: 10 }},44x44 with no hitSlop,Medium,
|
||||
37,Animation,Use Reanimated,High-performance animations,react-native-reanimated,Animated API for complex,useSharedValue useAnimatedStyle,Animated.timing for gesture,Medium,https://docs.swmansion.com/react-native-reanimated/
|
||||
38,Animation,Run on UI thread,worklets for smooth animation,Run animations on UI thread,JS thread animations,runOnUI(() => {}),Animated on JS thread,High,
|
||||
39,Animation,Use gesture handler,Native gesture recognition,react-native-gesture-handler,JS-based gesture handling,<GestureDetector>,<View onTouchMove={} />,Medium,https://docs.swmansion.com/react-native-gesture-handler/
|
||||
40,Async,Handle loading states,Show loading indicators,ActivityIndicator during load,Empty screen during load,{isLoading ? <ActivityIndicator /> : <Content />},No loading state,Medium,
|
||||
41,Async,Handle errors gracefully,Error boundaries and fallbacks,Error UI for failed requests,Crash on error,{error ? <ErrorView /> : <Content />},No error handling,High,
|
||||
42,Async,Cancel async operations,Cleanup on unmount,AbortController or cleanup,Memory leaks from async,useEffect cleanup,No cleanup for subscriptions,High,
|
||||
43,Accessibility,Add accessibility labels,Describe UI elements,accessibilityLabel for all interactive,Missing labels,"accessibilityLabel=""Submit form""",<Pressable> without label,High,https://reactnative.dev/docs/accessibility
|
||||
44,Accessibility,Use accessibility roles,Semantic meaning,accessibilityRole for elements,Wrong roles,"accessibilityRole=""button""",No role for button,Medium,
|
||||
45,Accessibility,Support screen readers,Test with TalkBack/VoiceOver,Test with screen readers,Skip accessibility testing,Regular TalkBack testing,No screen reader testing,High,
|
||||
46,Testing,Use React Native Testing Library,Component testing,render and fireEvent,Enzyme or manual testing,render(<Component />),shallow(<Component />),Medium,https://callstack.github.io/react-native-testing-library/
|
||||
47,Testing,Test on real devices,Real device behavior,Test on iOS and Android devices,Simulator only,Device testing in CI,Simulator only testing,High,
|
||||
48,Testing,Use Detox for E2E,End-to-end testing,Detox for critical flows,Manual E2E testing,detox test,Manual testing only,Medium,https://wix.github.io/Detox/
|
||||
49,Native,Use native modules carefully,Bridge has overhead,Batch native calls,Frequent bridge crossing,Batch updates,Call native on every keystroke,High,
|
||||
50,Native,Use Expo when possible,Simplified development,Expo for standard features,Bare RN for simple apps,expo install package,react-native link package,Low,https://docs.expo.dev/
|
||||
51,Native,Handle permissions,Request permissions properly,Check and request permissions,Assume permissions granted,PermissionsAndroid.request(),Access without permission check,High,https://reactnative.dev/docs/permissionsandroid
|
||||
|
|
|
@ -1,54 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,State,Use useState for local state,Simple component state should use useState hook,useState for form inputs toggles counters,Class components this.state,"const [count, setCount] = useState(0)",this.state = { count: 0 },Medium,https://react.dev/reference/react/useState
|
||||
2,State,Lift state up when needed,Share state between siblings by lifting to parent,Lift shared state to common ancestor,Prop drilling through many levels,Parent holds state passes down,Deep prop chains,Medium,https://react.dev/learn/sharing-state-between-components
|
||||
3,State,Use useReducer for complex state,Complex state logic benefits from reducer pattern,useReducer for state with multiple sub-values,Multiple useState for related values,useReducer with action types,5+ useState calls that update together,Medium,https://react.dev/reference/react/useReducer
|
||||
4,State,Avoid unnecessary state,Derive values from existing state when possible,Compute derived values in render,Store derivable values in state,const total = items.reduce(...),"const [total, setTotal] = useState(0)",High,https://react.dev/learn/choosing-the-state-structure
|
||||
5,State,Initialize state lazily,Use function form for expensive initial state,useState(() => computeExpensive()),useState(computeExpensive()),useState(() => JSON.parse(data)),useState(JSON.parse(data)),Medium,https://react.dev/reference/react/useState#avoiding-recreating-the-initial-state
|
||||
6,Effects,Clean up effects,Return cleanup function for subscriptions timers,Return cleanup function in useEffect,No cleanup for subscriptions,useEffect(() => { sub(); return unsub; }),useEffect(() => { subscribe(); }),High,https://react.dev/reference/react/useEffect#connecting-to-an-external-system
|
||||
7,Effects,Specify dependencies correctly,Include all values used inside effect in deps array,All referenced values in dependency array,Empty deps with external references,[value] when using value in effect,[] when using props/state in effect,High,https://react.dev/reference/react/useEffect#specifying-reactive-dependencies
|
||||
8,Effects,Avoid unnecessary effects,Don't use effects for transforming data or events,Transform data during render handle events directly,useEffect for derived state or event handling,const filtered = items.filter(...),useEffect(() => setFiltered(items.filter(...))),High,https://react.dev/learn/you-might-not-need-an-effect
|
||||
9,Effects,Use refs for non-reactive values,Store values that don't trigger re-renders in refs,useRef for interval IDs DOM elements,useState for values that don't need render,const intervalRef = useRef(null),"const [intervalId, setIntervalId] = useState()",Medium,https://react.dev/reference/react/useRef
|
||||
10,Rendering,Use keys properly,Stable unique keys for list items,Use stable IDs as keys,Array index as key for dynamic lists,key={item.id},key={index},High,https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key
|
||||
11,Rendering,Memoize expensive calculations,Use useMemo for costly computations,useMemo for expensive filtering/sorting,Recalculate every render,"useMemo(() => expensive(), [deps])",const result = expensiveCalc(),Medium,https://react.dev/reference/react/useMemo
|
||||
12,Rendering,Memoize callbacks passed to children,Use useCallback for functions passed as props,useCallback for handlers passed to memoized children,New function reference every render,"useCallback(() => {}, [deps])",const handler = () => {},Medium,https://react.dev/reference/react/useCallback
|
||||
13,Rendering,Use React.memo wisely,Wrap components that render often with same props,memo for pure components with stable props,memo everything or nothing,memo(ExpensiveList),memo(SimpleButton),Low,https://react.dev/reference/react/memo
|
||||
14,Rendering,Avoid inline object/array creation in JSX,Create objects outside render or memoize,Define style objects outside component,Inline objects in props,<div style={styles.container}>,<div style={{ margin: 10 }}>,Medium,
|
||||
15,Components,Keep components small and focused,Single responsibility for each component,One concern per component,Large multi-purpose components,<UserAvatar /><UserName />,<UserCard /> with 500 lines,Medium,
|
||||
16,Components,Use composition over inheritance,Compose components using children and props,Use children prop for flexibility,Inheritance hierarchies,<Card>{content}</Card>,class SpecialCard extends Card,Medium,https://react.dev/learn/thinking-in-react
|
||||
17,Components,Colocate related code,Keep related components and hooks together,Related files in same directory,Flat structure with many files,components/User/UserCard.tsx,components/UserCard.tsx + hooks/useUser.ts,Low,
|
||||
18,Components,Use fragments to avoid extra DOM,Fragment or <> for multiple elements without wrapper,<> for grouping without DOM node,Extra div wrappers,<>{items.map(...)}</>,<div>{items.map(...)}</div>,Low,https://react.dev/reference/react/Fragment
|
||||
19,Props,Destructure props,Destructure props for cleaner component code,Destructure in function signature,props.name props.value throughout,"function User({ name, age })",function User(props),Low,
|
||||
20,Props,Provide default props values,Use default parameters or defaultProps,Default values in destructuring,Undefined checks throughout,function Button({ size = 'md' }),if (size === undefined) size = 'md',Low,
|
||||
21,Props,Avoid prop drilling,Use context or composition for deeply nested data,Context for global data composition for UI,Passing props through 5+ levels,<UserContext.Provider>,<A user={u}><B user={u}><C user={u}>,Medium,https://react.dev/learn/passing-data-deeply-with-context
|
||||
22,Props,Validate props with TypeScript,Use TypeScript interfaces for prop types,interface Props { name: string },PropTypes or no validation,interface ButtonProps { onClick: () => void },Button.propTypes = {},Medium,
|
||||
23,Events,Use synthetic events correctly,React normalizes events across browsers,e.preventDefault() e.stopPropagation(),Access native event unnecessarily,onClick={(e) => e.preventDefault()},onClick={(e) => e.nativeEvent.preventDefault()},Low,https://react.dev/reference/react-dom/components/common#react-event-object
|
||||
24,Events,Avoid binding in render,Use arrow functions in class or hooks,Arrow functions in functional components,bind in render or constructor,const handleClick = () => {},this.handleClick.bind(this),Medium,
|
||||
25,Events,Pass event handlers not call results,Pass function reference not invocation,onClick={handleClick},onClick={handleClick()} causing immediate call,onClick={handleClick},onClick={handleClick()},High,
|
||||
26,Forms,Controlled components for forms,Use state to control form inputs,value + onChange for inputs,Uncontrolled inputs with refs,<input value={val} onChange={setVal}>,<input ref={inputRef}>,Medium,https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable
|
||||
27,Forms,Handle form submission properly,Prevent default and handle in submit handler,onSubmit with preventDefault,onClick on submit button only,<form onSubmit={handleSubmit}>,<button onClick={handleSubmit}>,Medium,
|
||||
28,Forms,Debounce rapid input changes,Debounce search/filter inputs,useDeferredValue or debounce for search,Filter on every keystroke,useDeferredValue(searchTerm),useEffect filtering on every change,Medium,https://react.dev/reference/react/useDeferredValue
|
||||
29,Hooks,Follow rules of hooks,Only call hooks at top level and in React functions,Hooks at component top level,Hooks in conditions loops or callbacks,"const [x, setX] = useState()","if (cond) { const [x, setX] = useState() }",High,https://react.dev/reference/rules/rules-of-hooks
|
||||
30,Hooks,Custom hooks for reusable logic,Extract shared stateful logic to custom hooks,useCustomHook for reusable patterns,Duplicate hook logic across components,const { data } = useFetch(url),Duplicate useEffect/useState in components,Medium,https://react.dev/learn/reusing-logic-with-custom-hooks
|
||||
31,Hooks,Name custom hooks with use prefix,Custom hooks must start with use,useFetch useForm useAuth,fetchData or getData for hook,function useFetch(url),function fetchData(url),High,
|
||||
32,Context,Use context for global data,Context for theme auth locale,Context for app-wide state,Context for frequently changing data,<ThemeContext.Provider>,Context for form field values,Medium,https://react.dev/learn/passing-data-deeply-with-context
|
||||
33,Context,Split contexts by concern,Separate contexts for different domains,ThemeContext + AuthContext,One giant AppContext,<ThemeProvider><AuthProvider>,<AppProvider value={{theme user...}}>,Medium,
|
||||
34,Context,Memoize context values,Prevent unnecessary re-renders with useMemo,useMemo for context value object,New object reference every render,"value={useMemo(() => ({...}), [])}","value={{ user, theme }}",High,
|
||||
35,Performance,Use React DevTools Profiler,Profile to identify performance bottlenecks,Profile before optimizing,Optimize without measuring,React DevTools Profiler,Guessing at bottlenecks,Medium,https://react.dev/learn/react-developer-tools
|
||||
36,Performance,Lazy load components,Use React.lazy for code splitting,lazy() for routes and heavy components,Import everything upfront,const Page = lazy(() => import('./Page')),import Page from './Page',Medium,https://react.dev/reference/react/lazy
|
||||
37,Performance,Virtualize long lists,Use windowing for lists over 100 items,react-window or react-virtual,Render thousands of DOM nodes,<VirtualizedList items={items}/>,{items.map(i => <Item />)},High,
|
||||
38,Performance,Batch state updates,React 18 auto-batches but be aware,Let React batch related updates,Manual batching with flushSync,setA(1); setB(2); // batched,flushSync(() => setA(1)),Low,https://react.dev/learn/queueing-a-series-of-state-updates
|
||||
39,ErrorHandling,Use error boundaries,Catch JavaScript errors in component tree,ErrorBoundary wrapping sections,Let errors crash entire app,<ErrorBoundary><App/></ErrorBoundary>,No error handling,High,https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
|
||||
40,ErrorHandling,Handle async errors,Catch errors in async operations,try/catch in async handlers,Unhandled promise rejections,try { await fetch() } catch(e) {},await fetch() // no catch,High,
|
||||
41,Testing,Test behavior not implementation,Test what user sees and does,Test renders and interactions,Test internal state or methods,expect(screen.getByText('Hello')),expect(component.state.name),Medium,https://testing-library.com/docs/react-testing-library/intro/
|
||||
42,Testing,Use testing-library queries,Use accessible queries,getByRole getByLabelText,getByTestId for everything,getByRole('button'),getByTestId('submit-btn'),Medium,https://testing-library.com/docs/queries/about#priority
|
||||
43,Accessibility,Use semantic HTML,Proper HTML elements for their purpose,button for clicks nav for navigation,div with onClick for buttons,<button onClick={...}>,<div onClick={...}>,High,https://react.dev/reference/react-dom/components#all-html-components
|
||||
44,Accessibility,Manage focus properly,Handle focus for modals dialogs,Focus trap in modals return focus on close,No focus management,useEffect to focus input,Modal without focus trap,High,
|
||||
45,Accessibility,Announce dynamic content,Use ARIA live regions for updates,aria-live for dynamic updates,Silent updates to screen readers,"<div aria-live=""polite"">{msg}</div>",<div>{msg}</div>,Medium,
|
||||
46,Accessibility,Label form controls,Associate labels with inputs,htmlFor matching input id,Placeholder as only label,"<label htmlFor=""email"">Email</label>","<input placeholder=""Email""/>",High,
|
||||
47,TypeScript,Type component props,Define interfaces for all props,interface Props with all prop types,any or missing types,interface Props { name: string },function Component(props: any),High,
|
||||
48,TypeScript,Type state properly,Provide types for useState,useState<Type>() for complex state,Inferred any types,useState<User | null>(null),useState(null),Medium,
|
||||
49,TypeScript,Type event handlers,Use React event types,React.ChangeEvent<HTMLInputElement>,Generic Event type,onChange: React.ChangeEvent<HTMLInputElement>,onChange: Event,Medium,
|
||||
50,TypeScript,Use generics for reusable components,Generic components for flexible typing,Generic props for list components,Union types for flexibility,<List<T> items={T[]}>,<List items={any[]}>,Medium,
|
||||
51,Patterns,Container/Presentational split,Separate data logic from UI,Container fetches presentational renders,Mixed data and UI in one,<UserContainer><UserView/></UserContainer>,<User /> with fetch and render,Low,
|
||||
52,Patterns,Render props for flexibility,Share code via render prop pattern,Render prop for customizable rendering,Duplicate logic across components,<DataFetcher render={data => ...}/>,Copy paste fetch logic,Low,https://react.dev/reference/react/cloneElement#passing-data-with-a-render-prop
|
||||
53,Patterns,Compound components,Related components sharing state,Tab + TabPanel sharing context,Prop drilling between related,<Tabs><Tab/><TabPanel/></Tabs>,<Tabs tabs={[]} panels={[...]}/>,Low,
|
||||
|
|
|
@ -1,61 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Setup,Use CLI for installation,Install components via shadcn CLI for proper setup,npx shadcn@latest add component-name,Manual copy-paste from docs,npx shadcn@latest add button,Copy component code manually,High,https://ui.shadcn.com/docs/cli
|
||||
2,Setup,Initialize project properly,Run init command to set up components.json and globals.css,npx shadcn@latest init before adding components,Skip init and add components directly,npx shadcn@latest init,npx shadcn@latest add button (without init),High,https://ui.shadcn.com/docs/installation
|
||||
3,Setup,Configure path aliases,Set up proper import aliases in tsconfig and components.json,Use @/components/ui path aliases,Relative imports like ../../components,import { Button } from "@/components/ui/button",import { Button } from "../../components/ui/button",Medium,https://ui.shadcn.com/docs/installation
|
||||
4,Theming,Use CSS variables for colors,Define colors as CSS variables in globals.css for theming,CSS variables in :root and .dark,Hardcoded color values in components,bg-primary text-primary-foreground,bg-blue-500 text-white,High,https://ui.shadcn.com/docs/theming
|
||||
5,Theming,Follow naming convention,Use semantic color names with foreground pattern,primary/primary-foreground secondary/secondary-foreground,Generic color names,--primary --primary-foreground,--blue --light-blue,Medium,https://ui.shadcn.com/docs/theming
|
||||
6,Theming,Support dark mode,Include .dark class styles for all custom CSS,Define both :root and .dark color schemes,Only light mode colors,.dark { --background: 240 10% 3.9%; },No .dark class styles,High,https://ui.shadcn.com/docs/dark-mode
|
||||
7,Components,Use component variants,Leverage cva variants for consistent styling,Use variant prop for different styles,Inline conditional classes,<Button variant="destructive">,<Button className={isError ? "bg-red-500" : "bg-blue-500"}>,Medium,https://ui.shadcn.com/docs/components/button
|
||||
8,Components,Compose with className,Add custom classes via className prop for overrides,Extend with className for one-off customizations,Modify component source directly,<Button className="w-full">,Edit button.tsx to add w-full,Medium,https://ui.shadcn.com/docs/components/button
|
||||
9,Components,Use size variants consistently,Apply size prop for consistent sizing across components,size="sm" size="lg" for sizing,Mix size classes inconsistently,<Button size="lg">,<Button className="text-lg px-8 py-4">,Medium,https://ui.shadcn.com/docs/components/button
|
||||
10,Components,Prefer compound components,Use provided sub-components for complex UI,Card + CardHeader + CardContent pattern,Single component with many props,<Card><CardHeader><CardTitle>,<Card title="x" content="y" footer="z">,Medium,https://ui.shadcn.com/docs/components/card
|
||||
11,Dialog,Use Dialog for modal content,Dialog component for overlay modal windows,Dialog for confirmations forms details,Alert for modal content,<Dialog><DialogContent>,<Alert> styled as modal,High,https://ui.shadcn.com/docs/components/dialog
|
||||
12,Dialog,Handle dialog state properly,Use open and onOpenChange for controlled dialogs,Controlled state with useState,Uncontrolled with default open only,"<Dialog open={open} onOpenChange={setOpen}>","<Dialog defaultOpen={true}>",Medium,https://ui.shadcn.com/docs/components/dialog
|
||||
13,Dialog,Include proper dialog structure,Use DialogHeader DialogTitle DialogDescription,Complete semantic structure,Missing title or description,<DialogHeader><DialogTitle><DialogDescription>,<DialogContent><p>Content</p></DialogContent>,High,https://ui.shadcn.com/docs/components/dialog
|
||||
14,Sheet,Use Sheet for side panels,Sheet component for slide-out panels and drawers,Sheet for navigation filters settings,Dialog for side content,<Sheet side="right">,<Dialog> with slide animation,Medium,https://ui.shadcn.com/docs/components/sheet
|
||||
15,Sheet,Specify sheet side,Set side prop for sheet slide direction,Explicit side="left" or side="right",Default side without consideration,<Sheet><SheetContent side="left">,<Sheet><SheetContent>,Low,https://ui.shadcn.com/docs/components/sheet
|
||||
16,Form,Use Form with react-hook-form,Integrate Form component with react-hook-form for validation,useForm + Form + FormField pattern,Custom form handling without Form,<Form {...form}><FormField control={form.control}>,<form onSubmit={handleSubmit}>,High,https://ui.shadcn.com/docs/components/form
|
||||
17,Form,Use FormField for inputs,Wrap inputs in FormField for proper labeling and errors,FormField + FormItem + FormLabel + FormControl,Input without FormField wrapper,<FormField><FormItem><FormLabel><FormControl><Input>,<Input onChange={...}>,High,https://ui.shadcn.com/docs/components/form
|
||||
18,Form,Display form messages,Use FormMessage for validation error display,FormMessage after FormControl,Custom error text without FormMessage,<FormControl><Input/></FormControl><FormMessage/>,<Input/>{error && <span>{error}</span>},Medium,https://ui.shadcn.com/docs/components/form
|
||||
19,Form,Use Zod for validation,Define form schema with Zod for type-safe validation,zodResolver with form schema,Manual validation logic,zodResolver(formSchema),validate: (values) => { if (!values.email) },Medium,https://ui.shadcn.com/docs/components/form
|
||||
20,Select,Use Select for dropdowns,Select component for option selection,Select for choosing from list,Native select element,<Select><SelectTrigger><SelectContent>,<select><option>,Medium,https://ui.shadcn.com/docs/components/select
|
||||
21,Select,Structure Select properly,Include Trigger Value Content and Items,Complete Select structure,Missing SelectValue or SelectContent,<SelectTrigger><SelectValue/></SelectTrigger><SelectContent><SelectItem>,<Select><option>,High,https://ui.shadcn.com/docs/components/select
|
||||
22,Command,Use Command for search,Command component for searchable lists and palettes,Command for command palette search,Input with custom dropdown,<Command><CommandInput><CommandList>,<Input><div className="dropdown">,Medium,https://ui.shadcn.com/docs/components/command
|
||||
23,Command,Group command items,Use CommandGroup for categorized items,CommandGroup with heading for sections,Flat list without grouping,<CommandGroup heading="Suggestions"><CommandItem>,<CommandItem> without groups,Low,https://ui.shadcn.com/docs/components/command
|
||||
24,Table,Use Table for data display,Table component for structured data,Table for tabular data display,Div grid for table-like layouts,<Table><TableHeader><TableBody><TableRow>,<div className="grid">,Medium,https://ui.shadcn.com/docs/components/table
|
||||
25,Table,Include proper table structure,Use TableHeader TableBody TableRow TableCell,Semantic table structure,Missing thead or tbody,<TableHeader><TableRow><TableHead>,<Table><TableRow> without header,High,https://ui.shadcn.com/docs/components/table
|
||||
26,DataTable,Use DataTable for complex tables,Combine Table with TanStack Table for features,DataTable pattern for sorting filtering pagination,Custom table implementation,useReactTable + Table components,Custom sort filter pagination logic,Medium,https://ui.shadcn.com/docs/components/data-table
|
||||
27,Tabs,Use Tabs for content switching,Tabs component for tabbed interfaces,Tabs for related content sections,Custom tab implementation,<Tabs><TabsList><TabsTrigger><TabsContent>,<div onClick={() => setTab(...)},Medium,https://ui.shadcn.com/docs/components/tabs
|
||||
28,Tabs,Set default tab value,Specify defaultValue for initial tab,defaultValue on Tabs component,No default leaving first tab,<Tabs defaultValue="account">,<Tabs> without defaultValue,Low,https://ui.shadcn.com/docs/components/tabs
|
||||
29,Accordion,Use Accordion for collapsible,Accordion for expandable content sections,Accordion for FAQ settings panels,Custom collapse implementation,<Accordion><AccordionItem><AccordionTrigger>,<div onClick={() => setOpen(!open)}>,Medium,https://ui.shadcn.com/docs/components/accordion
|
||||
30,Accordion,Choose accordion type,Use type="single" or type="multiple" appropriately,type="single" for one open type="multiple" for many,Default type without consideration,<Accordion type="single" collapsible>,<Accordion> without type,Low,https://ui.shadcn.com/docs/components/accordion
|
||||
31,Toast,Use Sonner for toasts,Sonner integration for toast notifications,toast() from sonner for notifications,Custom toast implementation,toast("Event created"),setShowToast(true),Medium,https://ui.shadcn.com/docs/components/sonner
|
||||
32,Toast,Add Toaster to layout,Include Toaster component in root layout,<Toaster /> in app layout,Toaster in individual pages,app/layout.tsx: <Toaster />,page.tsx: <Toaster />,High,https://ui.shadcn.com/docs/components/sonner
|
||||
33,Toast,Use toast variants,Apply toast.success toast.error for context,Semantic toast methods,Generic toast for all messages,toast.success("Saved!") toast.error("Failed"),toast("Saved!") toast("Failed"),Medium,https://ui.shadcn.com/docs/components/sonner
|
||||
34,Popover,Use Popover for floating content,Popover for dropdown menus and floating panels,Popover for contextual actions,Absolute positioned divs,<Popover><PopoverTrigger><PopoverContent>,<div className="relative"><div className="absolute">,Medium,https://ui.shadcn.com/docs/components/popover
|
||||
35,Popover,Handle popover alignment,Use align and side props for positioning,Explicit alignment configuration,Default alignment for all,<PopoverContent align="start" side="bottom">,<PopoverContent>,Low,https://ui.shadcn.com/docs/components/popover
|
||||
36,DropdownMenu,Use DropdownMenu for actions,DropdownMenu for action lists and context menus,DropdownMenu for user menu actions,Popover for action lists,<DropdownMenu><DropdownMenuTrigger><DropdownMenuContent>,<Popover> for menu actions,Medium,https://ui.shadcn.com/docs/components/dropdown-menu
|
||||
37,DropdownMenu,Group menu items,Use DropdownMenuGroup and DropdownMenuSeparator,Organized menu with separators,Flat list of items,<DropdownMenuGroup><DropdownMenuItem><DropdownMenuSeparator>,<DropdownMenuItem> without organization,Low,https://ui.shadcn.com/docs/components/dropdown-menu
|
||||
38,Tooltip,Use Tooltip for hints,Tooltip for icon buttons and truncated text,Tooltip for additional context,Title attribute for tooltips,<Tooltip><TooltipTrigger><TooltipContent>,<button title="Delete">,Medium,https://ui.shadcn.com/docs/components/tooltip
|
||||
39,Tooltip,Add TooltipProvider,Wrap app or section in TooltipProvider,TooltipProvider at app level,TooltipProvider per tooltip,<TooltipProvider><App/></TooltipProvider>,<Tooltip><TooltipProvider>,High,https://ui.shadcn.com/docs/components/tooltip
|
||||
40,Skeleton,Use Skeleton for loading,Skeleton component for loading placeholders,Skeleton matching content layout,Spinner for content loading,<Skeleton className="h-4 w-[200px]"/>,<Spinner/> for card loading,Medium,https://ui.shadcn.com/docs/components/skeleton
|
||||
41,Skeleton,Match skeleton dimensions,Size skeleton to match loaded content,Skeleton same size as expected content,Generic skeleton size,<Skeleton className="h-12 w-12 rounded-full"/>,<Skeleton/> without sizing,Medium,https://ui.shadcn.com/docs/components/skeleton
|
||||
42,AlertDialog,Use AlertDialog for confirms,AlertDialog for destructive action confirmation,AlertDialog for delete confirmations,Dialog for confirmations,<AlertDialog><AlertDialogTrigger><AlertDialogContent>,<Dialog> for delete confirmation,High,https://ui.shadcn.com/docs/components/alert-dialog
|
||||
43,AlertDialog,Include action buttons,Use AlertDialogAction and AlertDialogCancel,Standard confirm/cancel pattern,Custom buttons in AlertDialog,<AlertDialogCancel>Cancel</AlertDialogCancel><AlertDialogAction>,<Button>Cancel</Button><Button>Confirm</Button>,Medium,https://ui.shadcn.com/docs/components/alert-dialog
|
||||
44,Sidebar,Use Sidebar for navigation,Sidebar component for app navigation,Sidebar for main app navigation,Custom sidebar implementation,<SidebarProvider><Sidebar><SidebarContent>,<div className="w-64 fixed">,Medium,https://ui.shadcn.com/docs/components/sidebar
|
||||
45,Sidebar,Wrap in SidebarProvider,Use SidebarProvider for sidebar state management,SidebarProvider at layout level,Sidebar without provider,<SidebarProvider><Sidebar></SidebarProvider>,<Sidebar> without provider,High,https://ui.shadcn.com/docs/components/sidebar
|
||||
46,Sidebar,Use SidebarTrigger,Include SidebarTrigger for mobile toggle,SidebarTrigger for responsive toggle,Custom toggle button,<SidebarTrigger/>,<Button onClick={() => toggleSidebar()}>,Medium,https://ui.shadcn.com/docs/components/sidebar
|
||||
47,Chart,Use Chart for data viz,Chart component with Recharts integration,Chart component for dashboards,Direct Recharts without wrapper,<ChartContainer config={chartConfig}>,<ResponsiveContainer><BarChart>,Medium,https://ui.shadcn.com/docs/components/chart
|
||||
48,Chart,Define chart config,Create chartConfig for consistent theming,chartConfig with color definitions,Inline colors in charts,"{ desktop: { label: ""Desktop"", color: ""#2563eb"" } }",<Bar fill="#2563eb"/>,Medium,https://ui.shadcn.com/docs/components/chart
|
||||
49,Chart,Use ChartTooltip,Apply ChartTooltip for interactive charts,ChartTooltip with ChartTooltipContent,Recharts Tooltip directly,<ChartTooltip content={<ChartTooltipContent/>}/>,<Tooltip/> from recharts,Low,https://ui.shadcn.com/docs/components/chart
|
||||
50,Blocks,Use blocks for scaffolding,Start from shadcn blocks for common layouts,npx shadcn@latest add dashboard-01,Build dashboard from scratch,npx shadcn@latest add login-01,Custom login page from scratch,Medium,https://ui.shadcn.com/blocks
|
||||
51,Blocks,Customize block components,Modify copied block code to fit needs,Edit block files after installation,Use blocks without modification,Customize dashboard-01 layout,Use dashboard-01 as-is,Low,https://ui.shadcn.com/blocks
|
||||
52,A11y,Use semantic components,Shadcn components have built-in ARIA,Rely on component accessibility,Override ARIA attributes,<Button> has button role,<div role="button">,High,https://ui.shadcn.com/docs/components/button
|
||||
53,A11y,Maintain focus management,Dialog Sheet handle focus automatically,Let components manage focus,Custom focus handling,<Dialog> traps focus,document.querySelector().focus(),High,https://ui.shadcn.com/docs/components/dialog
|
||||
54,A11y,Provide labels,Use FormLabel and aria-label appropriately,FormLabel for form inputs,Placeholder as only label,<FormLabel>Email</FormLabel><Input/>,<Input placeholder="Email"/>,High,https://ui.shadcn.com/docs/components/form
|
||||
55,Performance,Import components individually,Import only needed components,Named imports from component files,Import all from index,import { Button } from "@/components/ui/button",import { Button Card Dialog } from "@/components/ui",Medium,
|
||||
56,Performance,Lazy load dialogs,Dynamic import for heavy dialog content,React.lazy for dialog content,Import all dialogs upfront,const HeavyContent = lazy(() => import('./Heavy')),import HeavyContent from './Heavy',Medium,
|
||||
57,Customization,Extend variants with cva,Add new variants using class-variance-authority,Extend buttonVariants for new styles,Inline classes for variants,"variants: { size: { xl: ""h-14 px-8"" } }",className="h-14 px-8",Medium,https://ui.shadcn.com/docs/components/button
|
||||
58,Customization,Create custom components,Build new components following shadcn patterns,Use cn() and cva for custom components,Different patterns for custom,const Custom = ({ className }) => <div className={cn("base" className)}>,const Custom = ({ style }) => <div style={style}>,Medium,
|
||||
59,Patterns,Use asChild for composition,asChild prop for component composition,Slot pattern with asChild,Wrapper divs for composition,<Button asChild><Link href="/">,<Button><Link href="/"></Link></Button>,Medium,https://ui.shadcn.com/docs/components/button
|
||||
60,Patterns,Combine with React Hook Form,Form + useForm for complete forms,RHF Controller with shadcn inputs,Custom form state management,<FormField control={form.control} name="email">,<Input value={email} onChange={(e) => setEmail(e.target.value)},High,https://ui.shadcn.com/docs/components/form
|
||||
|
Can't render this file because it contains an unexpected character in line 4 and column 188.
|
|
|
@ -1,54 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Reactivity,Use $: for reactive statements,Automatic dependency tracking,$: for derived values,Manual recalculation,$: doubled = count * 2,let doubled; count && (doubled = count * 2),Medium,https://svelte.dev/docs/svelte-components#script-3-$-marks-a-statement-as-reactive
|
||||
2,Reactivity,Trigger reactivity with assignment,Svelte tracks assignments not mutations,Reassign arrays/objects to trigger update,Mutate without reassignment,"items = [...items, newItem]",items.push(newItem),High,https://svelte.dev/docs/svelte-components#script-2-assignments-are-reactive
|
||||
3,Reactivity,Use $state in Svelte 5,Runes for explicit reactivity,let count = $state(0),Implicit reactivity in Svelte 5,let count = $state(0),let count = 0 (Svelte 5),Medium,https://svelte.dev/blog/runes
|
||||
4,Reactivity,Use $derived for computed values,$derived replaces $: in Svelte 5,let doubled = $derived(count * 2),$: in Svelte 5,let doubled = $derived(count * 2),$: doubled = count * 2 (Svelte 5),Medium,
|
||||
5,Reactivity,Use $effect for side effects,$effect replaces $: side effects,Use $effect for subscriptions,$: for side effects in Svelte 5,$effect(() => console.log(count)),$: console.log(count) (Svelte 5),Medium,
|
||||
6,Props,Export let for props,Declare props with export let,export let propName,Props without export,export let count = 0,let count = 0,High,https://svelte.dev/docs/svelte-components#script-1-export-creates-a-component-prop
|
||||
7,Props,Use $props in Svelte 5,$props rune for prop access,let { name } = $props(),export let in Svelte 5,"let { name, age = 0 } = $props()",export let name; export let age = 0,Medium,
|
||||
8,Props,Provide default values,Default props with assignment,export let count = 0,Required props without defaults,export let count = 0,export let count,Low,
|
||||
9,Props,Use spread props,Pass through unknown props,{...$$restProps} on elements,Manual prop forwarding,<button {...$$restProps}>,<button class={$$props.class}>,Low,https://svelte.dev/docs/basic-markup#attributes-and-props
|
||||
10,Bindings,Use bind: for two-way binding,Simplified input handling,bind:value for inputs,on:input with manual update,<input bind:value={name}>,<input value={name} on:input={e => name = e.target.value}>,Low,https://svelte.dev/docs/element-directives#bind-property
|
||||
11,Bindings,Bind to DOM elements,Reference DOM nodes,bind:this for element reference,querySelector in onMount,<div bind:this={el}>,onMount(() => el = document.querySelector()),Medium,
|
||||
12,Bindings,Use bind:group for radios/checkboxes,Simplified group handling,bind:group for radio/checkbox groups,Manual checked handling,"<input type=""radio"" bind:group={selected}>","<input type=""radio"" checked={selected === value}>",Low,
|
||||
13,Events,Use on: for event handlers,Event directive syntax,on:click={handler},addEventListener in onMount,<button on:click={handleClick}>,onMount(() => btn.addEventListener()),Medium,https://svelte.dev/docs/element-directives#on-eventname
|
||||
14,Events,Forward events with on:event,Pass events to parent,on:click without handler,createEventDispatcher for DOM events,<button on:click>,"dispatch('click', event)",Low,
|
||||
15,Events,Use createEventDispatcher,Custom component events,dispatch for custom events,on:event for custom events,"dispatch('save', { data })",on:save without dispatch,Medium,https://svelte.dev/docs/svelte#createeventdispatcher
|
||||
16,Lifecycle,Use onMount for initialization,Run code after component mounts,onMount for setup and data fetching,Code in script body for side effects,onMount(() => fetchData()),fetchData() in script body,High,https://svelte.dev/docs/svelte#onmount
|
||||
17,Lifecycle,Return cleanup from onMount,Automatic cleanup on destroy,Return function from onMount,Separate onDestroy for paired cleanup,onMount(() => { sub(); return unsub }),onMount(sub); onDestroy(unsub),Medium,
|
||||
18,Lifecycle,Use onDestroy sparingly,Only when onMount cleanup not possible,onDestroy for non-mount cleanup,onDestroy for mount-related cleanup,onDestroy for store unsubscribe,onDestroy(() => clearInterval(id)),Low,
|
||||
19,Lifecycle,Avoid beforeUpdate/afterUpdate,Usually not needed,Reactive statements instead,beforeUpdate for derived state,$: if (x) doSomething(),beforeUpdate(() => doSomething()),Low,
|
||||
20,Stores,Use writable for mutable state,Basic reactive store,writable for shared mutable state,Local variables for shared state,const count = writable(0),let count = 0 in module,Medium,https://svelte.dev/docs/svelte-store#writable
|
||||
21,Stores,Use readable for read-only state,External data sources,readable for derived/external data,writable for read-only data,"readable(0, set => interval(set))",writable(0) for timer,Low,https://svelte.dev/docs/svelte-store#readable
|
||||
22,Stores,Use derived for computed stores,Combine or transform stores,derived for computed values,Manual subscription for derived,"derived(count, $c => $c * 2)",count.subscribe(c => doubled = c * 2),Medium,https://svelte.dev/docs/svelte-store#derived
|
||||
23,Stores,Use $ prefix for auto-subscription,Automatic subscribe/unsubscribe,$storeName in components,Manual subscription,{$count},count.subscribe(c => value = c),High,
|
||||
24,Stores,Clean up custom subscriptions,Unsubscribe when component destroys,Return unsubscribe from onMount,Leave subscriptions open,onMount(() => store.subscribe(fn)),store.subscribe(fn) in script,High,
|
||||
25,Slots,Use slots for composition,Content projection,<slot> for flexible content,Props for all content,<slot>Default</slot>,"<Component content=""text""/>",Medium,https://svelte.dev/docs/special-elements#slot
|
||||
26,Slots,Name slots for multiple areas,Multiple content areas,"<slot name=""header"">",Single slot for complex layouts,"<slot name=""header""><slot name=""footer"">",<slot> with complex conditionals,Low,
|
||||
27,Slots,Check slot content with $$slots,Conditional slot rendering,$$slots.name for conditional rendering,Always render slot wrapper,"{#if $$slots.footer}<slot name=""footer""/>{/if}","<div><slot name=""footer""/></div>",Low,
|
||||
28,Styling,Use scoped styles by default,Styles scoped to component,<style> for component styles,Global styles for component,:global() only when needed,<style> all global,Medium,https://svelte.dev/docs/svelte-components#style
|
||||
29,Styling,Use :global() sparingly,Escape scoping when needed,:global for third-party styling,Global for all styles,:global(.external-lib),<style> without scoping,Medium,
|
||||
30,Styling,Use CSS variables for theming,Dynamic styling,CSS custom properties,Inline styles for themes,"style=""--color: {color}""","style=""color: {color}""",Low,
|
||||
31,Transitions,Use built-in transitions,Svelte transition directives,transition:fade for simple effects,Manual CSS transitions,<div transition:fade>,<div class:fade={visible}>,Low,https://svelte.dev/docs/element-directives#transition-fn
|
||||
32,Transitions,Use in: and out: separately,Different enter/exit animations,in:fly out:fade for asymmetric,Same transition for both,<div in:fly out:fade>,<div transition:fly>,Low,
|
||||
33,Transitions,Add local modifier,Prevent ancestor trigger,transition:fade|local,Global transitions for lists,<div transition:slide|local>,<div transition:slide>,Medium,
|
||||
34,Actions,Use actions for DOM behavior,Reusable DOM logic,use:action for DOM enhancements,onMount for each usage,<div use:clickOutside>,onMount(() => setupClickOutside(el)),Medium,https://svelte.dev/docs/element-directives#use-action
|
||||
35,Actions,Return update and destroy,Lifecycle methods for actions,"Return { update, destroy }",Only initial setup,"return { update(params) {}, destroy() {} }",return destroy only,Medium,
|
||||
36,Actions,Pass parameters to actions,Configure action behavior,use:action={params},Hardcoded action behavior,<div use:tooltip={options}>,<div use:tooltip>,Low,
|
||||
37,Logic,Use {#if} for conditionals,Template conditionals,{#if} {:else if} {:else},Ternary in expressions,{#if cond}...{:else}...{/if},{cond ? a : b} for complex,Low,https://svelte.dev/docs/logic-blocks#if
|
||||
38,Logic,Use {#each} for lists,List rendering,{#each} with key,Map in expression,{#each items as item (item.id)},{items.map(i => `<div>${i}</div>`)},Medium,
|
||||
39,Logic,Always use keys in {#each},Proper list reconciliation,(item.id) for unique key,Index as key or no key,{#each items as item (item.id)},"{#each items as item, i (i)}",High,
|
||||
40,Logic,Use {#await} for promises,Handle async states,{#await} for loading/error states,Manual promise handling,{#await promise}...{:then}...{:catch},{#if loading}...{#if error},Medium,https://svelte.dev/docs/logic-blocks#await
|
||||
41,SvelteKit,Use +page.svelte for routes,File-based routing,+page.svelte for route components,Custom routing setup,routes/about/+page.svelte,routes/About.svelte,Medium,https://kit.svelte.dev/docs/routing
|
||||
42,SvelteKit,Use +page.js for data loading,Load data before render,load function in +page.js,onMount for data fetching,export function load() {},onMount(() => fetchData()),High,https://kit.svelte.dev/docs/load
|
||||
43,SvelteKit,Use +page.server.js for server-only,Server-side data loading,+page.server.js for sensitive data,+page.js for API keys,+page.server.js with DB access,+page.js with DB access,High,
|
||||
44,SvelteKit,Use form actions,Server-side form handling,+page.server.js actions,API routes for forms,export const actions = { default },fetch('/api/submit'),Medium,https://kit.svelte.dev/docs/form-actions
|
||||
45,SvelteKit,Use $app/stores for app state,$page $navigating $updated,$page for current page data,Manual URL parsing,import { page } from '$app/stores',window.location.pathname,Medium,https://kit.svelte.dev/docs/modules#$app-stores
|
||||
46,Performance,Use {#key} for forced re-render,Reset component state,{#key id} for fresh instance,Manual destroy/create,{#key item.id}<Component/>{/key},on:change={() => component = null},Low,https://svelte.dev/docs/logic-blocks#key
|
||||
47,Performance,Avoid unnecessary reactivity,Not everything needs $:,$: only for side effects,$: for simple assignments,$: if (x) console.log(x),$: y = x (when y = x works),Low,
|
||||
48,Performance,Use immutable compiler option,Skip equality checks,immutable: true for large lists,Default for all components,<svelte:options immutable/>,Default without immutable,Low,
|
||||
49,TypeScript,"Use lang=""ts"" in script",TypeScript support,"<script lang=""ts"">",JavaScript for typed projects,"<script lang=""ts"">",<script> with JSDoc,Medium,https://svelte.dev/docs/typescript
|
||||
50,TypeScript,Type props with interface,Explicit prop types,interface $$Props for types,Untyped props,interface $$Props { name: string },export let name,Medium,
|
||||
51,TypeScript,Type events with createEventDispatcher,Type-safe events,createEventDispatcher<Events>(),Untyped dispatch,createEventDispatcher<{ save: Data }>(),createEventDispatcher(),Medium,
|
||||
52,Accessibility,Use semantic elements,Proper HTML in templates,button nav main appropriately,div for everything,<button on:click>,<div on:click>,High,
|
||||
53,Accessibility,Add aria to dynamic content,Accessible state changes,aria-live for updates,Silent dynamic updates,"<div aria-live=""polite"">{message}</div>",<div>{message}</div>,Medium,
|
||||
|
|
|
@ -1,51 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Views,Use struct for views,SwiftUI views are value types,struct MyView: View,class MyView: View,struct ContentView: View { var body: some View },class ContentView: View,High,https://developer.apple.com/documentation/swiftui/view
|
||||
2,Views,Keep views small and focused,Single responsibility for each view,Extract subviews for complex layouts,Large monolithic views,Extract HeaderView FooterView,500+ line View struct,Medium,
|
||||
3,Views,Use body computed property,body returns the view hierarchy,var body: some View { },func body() -> some View,"var body: some View { Text(""Hello"") }",func body() -> Text,High,
|
||||
4,Views,Prefer composition over inheritance,Compose views using ViewBuilder,Combine smaller views,Inheritance hierarchies,VStack { Header() Content() },class SpecialView extends BaseView,Medium,
|
||||
5,State,Use @State for local state,Simple value types owned by view,@State for view-local primitives,@State for shared data,@State private var count = 0,@State var sharedData: Model,High,https://developer.apple.com/documentation/swiftui/state
|
||||
6,State,Use @Binding for two-way data,Pass mutable state to child views,@Binding for child input,@State in child for parent data,@Binding var isOn: Bool,$isOn to pass binding,Medium,https://developer.apple.com/documentation/swiftui/binding
|
||||
7,State,Use @StateObject for reference types,ObservableObject owned by view,@StateObject for view-created objects,@ObservedObject for owned objects,@StateObject private var vm = ViewModel(),@ObservedObject var vm = ViewModel(),High,https://developer.apple.com/documentation/swiftui/stateobject
|
||||
8,State,Use @ObservedObject for injected objects,Reference types passed from parent,@ObservedObject for injected dependencies,@StateObject for injected objects,@ObservedObject var vm: ViewModel,@StateObject var vm: ViewModel (injected),High,https://developer.apple.com/documentation/swiftui/observedobject
|
||||
9,State,Use @EnvironmentObject for shared state,App-wide state injection,@EnvironmentObject for global state,Prop drilling through views,@EnvironmentObject var settings: Settings,Pass settings through 5 views,Medium,https://developer.apple.com/documentation/swiftui/environmentobject
|
||||
10,State,Use @Published in ObservableObject,Automatically publish property changes,@Published for observed properties,Manual objectWillChange calls,@Published var items: [Item] = [],var items: [Item] { didSet { objectWillChange.send() } },Medium,
|
||||
11,Observable,Use @Observable macro (iOS 17+),Modern observation without Combine,@Observable class for view models,ObservableObject for new projects,@Observable class ViewModel { },class ViewModel: ObservableObject,Medium,https://developer.apple.com/documentation/observation
|
||||
12,Observable,Use @Bindable for @Observable,Create bindings from @Observable,@Bindable var vm for bindings,@Binding with @Observable,@Bindable var viewModel,$viewModel.name with @Observable,Medium,
|
||||
13,Layout,Use VStack HStack ZStack,Standard stack-based layouts,Stacks for linear arrangements,GeometryReader for simple layouts,VStack { Text() Image() },GeometryReader for vertical list,Medium,https://developer.apple.com/documentation/swiftui/vstack
|
||||
14,Layout,Use LazyVStack LazyHStack for lists,Lazy loading for performance,Lazy stacks for long lists,Regular stacks for 100+ items,LazyVStack { ForEach(items) },VStack { ForEach(largeArray) },High,https://developer.apple.com/documentation/swiftui/lazyvstack
|
||||
15,Layout,Use GeometryReader sparingly,Only when needed for sizing,GeometryReader for responsive layouts,GeometryReader everywhere,GeometryReader for aspect ratio,GeometryReader wrapping everything,Medium,
|
||||
16,Layout,Use spacing and padding consistently,Consistent spacing throughout app,Design system spacing values,Magic numbers for spacing,.padding(16) or .padding(),".padding(13), .padding(17)",Low,
|
||||
17,Layout,Use frame modifiers correctly,Set explicit sizes when needed,.frame(maxWidth: .infinity),Fixed sizes for responsive content,.frame(maxWidth: .infinity),.frame(width: 375),Medium,
|
||||
18,Modifiers,Order modifiers correctly,Modifier order affects rendering,Background before padding for full coverage,Wrong modifier order,.padding().background(Color.red),.background(Color.red).padding(),High,
|
||||
19,Modifiers,Create custom ViewModifiers,Reusable modifier combinations,ViewModifier for repeated styling,Duplicate modifier chains,struct CardStyle: ViewModifier,.shadow().cornerRadius() everywhere,Medium,https://developer.apple.com/documentation/swiftui/viewmodifier
|
||||
20,Modifiers,Use conditional modifiers carefully,Avoid changing view identity,if-else with same view type,Conditional that changes view identity,Text(title).foregroundColor(isActive ? .blue : .gray),if isActive { Text().bold() } else { Text() },Medium,
|
||||
21,Navigation,Use NavigationStack (iOS 16+),Modern navigation with type-safe paths,NavigationStack with navigationDestination,NavigationView for new projects,NavigationStack { },NavigationView { } (deprecated),Medium,https://developer.apple.com/documentation/swiftui/navigationstack
|
||||
22,Navigation,Use navigationDestination,Type-safe navigation destinations,.navigationDestination(for:),NavigationLink(destination:),.navigationDestination(for: Item.self),NavigationLink(destination: DetailView()),Medium,
|
||||
23,Navigation,Use @Environment for dismiss,Programmatic navigation dismissal,@Environment(\.dismiss) var dismiss,presentationMode (deprecated),@Environment(\.dismiss) var dismiss,@Environment(\.presentationMode),Low,
|
||||
24,Lists,Use List for scrollable content,Built-in scrolling and styling,List for standard scrollable content,ScrollView + VStack for simple lists,List { ForEach(items) { } },ScrollView { VStack { ForEach } },Low,https://developer.apple.com/documentation/swiftui/list
|
||||
25,Lists,Provide stable identifiers,Use Identifiable or explicit id,Identifiable protocol or id parameter,Index as identifier,ForEach(items) where Item: Identifiable,"ForEach(items.indices, id: \.self)",High,
|
||||
26,Lists,Use onDelete and onMove,Standard list editing,onDelete for swipe to delete,Custom delete implementation,.onDelete(perform: delete),.onTapGesture for delete,Low,
|
||||
27,Forms,Use Form for settings,Grouped input controls,Form for settings screens,Manual grouping for forms,Form { Section { Toggle() } },VStack { Toggle() },Low,https://developer.apple.com/documentation/swiftui/form
|
||||
28,Forms,Use @FocusState for keyboard,Manage keyboard focus,@FocusState for text field focus,Manual first responder handling,@FocusState private var isFocused: Bool,UIKit first responder,Medium,https://developer.apple.com/documentation/swiftui/focusstate
|
||||
29,Forms,Validate input properly,Show validation feedback,Real-time validation feedback,Submit without validation,TextField with validation state,TextField without error handling,Medium,
|
||||
30,Async,Use .task for async work,Automatic cancellation on view disappear,.task for view lifecycle async,onAppear with Task,.task { await loadData() },onAppear { Task { await loadData() } },Medium,https://developer.apple.com/documentation/swiftui/view/task(priority:_:)
|
||||
31,Async,Handle loading states,Show progress during async operations,ProgressView during loading,Empty view during load,if isLoading { ProgressView() },No loading indicator,Medium,
|
||||
32,Async,Use @MainActor for UI updates,Ensure UI updates on main thread,@MainActor on view models,Manual DispatchQueue.main,@MainActor class ViewModel,DispatchQueue.main.async,Medium,
|
||||
33,Animation,Use withAnimation,Animate state changes,withAnimation for state transitions,No animation for state changes,withAnimation { isExpanded.toggle() },isExpanded.toggle(),Low,https://developer.apple.com/documentation/swiftui/withanimation(_:_:)
|
||||
34,Animation,Use .animation modifier,Apply animations to views,.animation(.spring()) on view,Manual animation timing,.animation(.easeInOut),CABasicAnimation equivalent,Low,
|
||||
35,Animation,Respect reduced motion,Check accessibility settings,Check accessibilityReduceMotion,Ignore motion preferences,@Environment(\.accessibilityReduceMotion),Always animate regardless,High,
|
||||
36,Preview,Use #Preview macro (Xcode 15+),Modern preview syntax,#Preview for view previews,PreviewProvider protocol,#Preview { ContentView() },struct ContentView_Previews: PreviewProvider,Low,
|
||||
37,Preview,Create multiple previews,Test different states and devices,Multiple previews for states,Single preview only,"#Preview(""Light"") { } #Preview(""Dark"") { }",Single preview configuration,Low,
|
||||
38,Preview,Use preview data,Dedicated preview mock data,Static preview data,Production data in previews,Item.preview for preview,Fetch real data in preview,Low,
|
||||
39,Performance,Avoid expensive body computations,Body should be fast to compute,Precompute in view model,Heavy computation in body,vm.computedValue in body,Complex calculation in body,High,
|
||||
40,Performance,Use Equatable views,Skip unnecessary view updates,Equatable for complex views,Default equality for all views,struct MyView: View Equatable,No Equatable conformance,Medium,
|
||||
41,Performance,Profile with Instruments,Measure before optimizing,Use SwiftUI Instruments,Guess at performance issues,Profile with Instruments,Optimize without measuring,Medium,
|
||||
42,Accessibility,Add accessibility labels,Describe UI elements,.accessibilityLabel for context,Missing labels,".accessibilityLabel(""Close button"")",Button without label,High,https://developer.apple.com/documentation/swiftui/view/accessibilitylabel(_:)-1d7jv
|
||||
43,Accessibility,Support Dynamic Type,Respect text size preferences,Scalable fonts and layouts,Fixed font sizes,.font(.body) with Dynamic Type,.font(.system(size: 16)),High,
|
||||
44,Accessibility,Use semantic views,Proper accessibility traits,Correct accessibilityTraits,Wrong semantic meaning,Button for actions Image for display,Image that acts like button,Medium,
|
||||
45,Testing,Use ViewInspector for testing,Third-party view testing,ViewInspector for unit tests,UI tests only,ViewInspector assertions,Only XCUITest,Medium,
|
||||
46,Testing,Test view models,Unit test business logic,XCTest for view model,Skip view model testing,Test ViewModel methods,No unit tests,Medium,
|
||||
47,Testing,Use preview as visual test,Previews catch visual regressions,Multiple preview configurations,No visual verification,Preview different states,Single preview only,Low,
|
||||
48,Architecture,Use MVVM pattern,Separate view and logic,ViewModel for business logic,Logic in View,ObservableObject ViewModel,@State for complex logic,Medium,
|
||||
49,Architecture,Keep views dumb,Views display view model state,View reads from ViewModel,Business logic in View,view.items from vm.items,Complex filtering in View,Medium,
|
||||
50,Architecture,Use dependency injection,Inject dependencies for testing,Initialize with dependencies,Hard-coded dependencies,init(service: ServiceProtocol),let service = RealService(),Medium,
|
||||
|
|
|
@ -1,54 +0,0 @@
|
|||
Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
Setup,CDN Version Lock,Always use Three.js r128 from cdnjs. It is the stable CDN baseline. Never use a floating 'latest' URL — it silently breaks when the CDN updates without warning.,Pin to the exact r128 cdnjs URL in every HTML file,Use unpkg@latest or any unversioned CDN URL that can silently update,"<script src=""https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js""></script>","<script src=""https://unpkg.com/three@latest""></script>",Critical,https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js
|
||||
Setup,CapsuleGeometry Does Not Exist in r128,THREE.CapsuleGeometry was introduced in r142. Using it on the r128 CDN throws 'CapsuleGeometry is not a constructor' and crashes the entire scene. Build a capsule from primitives instead.,Build a capsule from CylinderGeometry plus two SphereGeometry end caps,Call THREE.CapsuleGeometry on r128 — it is undefined and throws immediately,"const body = new THREE.Mesh(new THREE.CylinderGeometry(0.5, 0.5, 1, 16), mat); const topCap = new THREE.Mesh(new THREE.SphereGeometry(0.5, 16, 8), mat); const botCap = new THREE.Mesh(new THREE.SphereGeometry(0.5, 16, 8), mat); topCap.position.y = 0.5; botCap.position.y = -0.5; const group = new THREE.Group(); group.add(body, topCap, botCap);","const cap = new THREE.CapsuleGeometry(0.5, 1, 4, 8); // TypeError: CapsuleGeometry is not a constructor on r128",Critical,https://threejs.org/docs/#api/en/geometries/CapsuleGeometry
|
||||
Setup,OrbitControls Must Be Loaded Separately,OrbitControls is NOT bundled in the core Three.js r128 CDN file. It lives in examples/js and must be loaded from a separate cdnjs script tag. THREE.OrbitControls is undefined without it.,Load the OrbitControls script from cdnjs examples path before your scene script,Expect THREE.OrbitControls to exist after loading only the core Three.js CDN script,"<!-- Load AFTER core Three.js script --> <script src=""https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/examples/js/controls/OrbitControls.min.js""></script>","<!-- Core only loaded — OrbitControls undefined --> <script src=""https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js""></script>",Critical,https://cdnjs.com/libraries/three.js/r128
|
||||
Setup,Custom Drag Orbit Fallback,When OrbitControls cannot be loaded implement spherical orbit using mousedown/mousemove/mouseup. The key is rotating in spherical coordinates so both horizontal AND vertical drag work correctly.,Rotate camera in spherical coordinates so both axes respond correctly to drag,Move camera.position.x directly — vertical drag is silently ignored and the orbit is incorrect,"let dragging = false; let prev = { x: 0, y: 0 }; const radius = camera.position.length(); let theta = 0; let phi = Math.PI / 2; canvas.addEventListener('mousedown', () => dragging = true); canvas.addEventListener('mouseup', () => dragging = false); canvas.addEventListener('mousemove', e => { if (!dragging) return; theta -= (e.clientX - prev.x) * 0.005; phi = Math.max(0.1, Math.min(Math.PI - 0.1, phi - (e.clientY - prev.y) * 0.005)); camera.position.set(radius * Math.sin(phi) * Math.sin(theta), radius * Math.cos(phi), radius * Math.sin(phi) * Math.cos(theta)); camera.lookAt(scene.position); prev = { x: e.clientX, y: e.clientY }; });","let dragging = false; let prev = { x: 0, y: 0 }; canvas.addEventListener('mousemove', e => { if (!dragging) return; camera.position.x += (e.clientX - prev.x) * 0.005; camera.lookAt(scene.position); prev = { x: e.clientX, y: e.clientY }; }); // BUG: Y-drag ignored; orbit is a horizontal slide not a sphere",High,https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent
|
||||
Setup,ESM vs CDN Import,When using a bundler import Three.js as an ES module. When using CDN the THREE global is already available — do not import it again. Mixing both loads Three.js twice and causes subtle runtime errors.,Match import style to build environment: ESM import for bundlers; rely on the window.THREE global for CDN pages,Mix a CDN script tag with an ES module import in the same file,"// Bundler project (Vite / webpack): import * as THREE from 'three'; // CDN project — no import needed; THREE is already global after the script tag","<!-- CDN script --> <script src=""r128.cdn""></script> <script type=""module""> import * as THREE from 'three'; // loads Three.js twice — version mismatch risk </script>",Critical,https://threejs.org/docs/#manual/en/introduction/Installation
|
||||
Setup,Single Renderer Per Page,Create one WebGLRenderer instance for the lifetime of the page. Multiple renderers compete for the browser GPU context limit (8–16 contexts) and cause context-lost errors especially on mobile.,Reuse a single renderer and swap scene content instead of recreating the renderer,Create a new renderer on each component mount or scene transition,"const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(canvas.clientWidth, canvas.clientHeight); // renderer lives for the page lifetime","function showScene() { const renderer = new THREE.WebGLRenderer(); document.body.appendChild(renderer.domElement); } showScene(); showScene(); // two GPU contexts — crashes on mobile",Critical,https://threejs.org/docs/#api/en/renderers/WebGLRenderer
|
||||
Setup,Pixel Ratio Cap at 2,Cap devicePixelRatio at 2. Retina displays report 3x or higher. Going from 2x to 3x multiplies pixel count by 2.25x with no visible quality improvement at normal viewing distance.,"Apply Math.min(window.devicePixelRatio, 2) — cap is at 2 not at 3",Pass window.devicePixelRatio directly without any cap,"renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));",renderer.setPixelRatio(window.devicePixelRatio); // 3x display = 9 pixels per CSS pixel = 2.25x GPU cost for zero quality gain,High,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.setPixelRatio
|
||||
Setup,Alpha Canvas Plus CSS Background,Set alpha:true on the renderer and control the background color through CSS rather than a renderer clear color. This composites the canvas correctly over any HTML content behind it.,Set alpha:true on renderer and let body or a parent div provide the background color,Set a solid renderer clear color when the canvas must composite over HTML behind it,"const renderer = new THREE.WebGLRenderer({ alpha: true }); renderer.setClearColor(0x000000, 0); // fully transparent canvas // body { background: #0d0d0d; } handles the visible color","renderer.setClearColor(0x111827); // fully opaque — HTML behind the canvas is blocked",Medium,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.setClearColor
|
||||
Camera,Aspect Ratio on Resize,Always update camera.aspect and call camera.updateProjectionMatrix() inside every resize handler. A stale aspect ratio causes the entire scene to appear stretched or squashed horizontally.,Update camera.aspect then call updateProjectionMatrix() on every resize,Let aspect ratio become stale after the browser window changes size,"window.addEventListener('resize', () => { camera.aspect = canvas.clientWidth / canvas.clientHeight; camera.updateProjectionMatrix(); renderer.setSize(canvas.clientWidth, canvas.clientHeight); });","// No resize handler — scene stretches to fill a wider window without correcting the projection",High,https://threejs.org/docs/#api/en/cameras/PerspectiveCamera
|
||||
Camera,FOV Range 45 to 75,Use a field of view between 45 and 75 degrees. Below 45 creates compressed telephoto distortion. Above 90 creates visible fisheye distortion at frame edges.,Start at 75 for general interactive scenes; use 45–55 for product close-ups,Use FOV above 90 or below 30 without a deliberate artistic reason,"const camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000); // general const camera = new THREE.PerspectiveCamera(50, aspect, 0.1, 1000); // product shot","const camera = new THREE.PerspectiveCamera(120, aspect, 0.1, 1000); // fisheye distortion at all edges",Medium,https://threejs.org/docs/#api/en/cameras/PerspectiveCamera
|
||||
Camera,Explicit Position and lookAt,Always set an explicit camera position and call camera.lookAt() before the first render. The default camera at the origin pointing down -Z makes subjects at arbitrary coordinates invisible or tiny.,Set camera.position.set() and camera.lookAt() to frame the subject before the first render,Leave the camera at default position (0 0 0) with no lookAt — subject may be behind the camera or microscopic,"camera.position.set(0, 1.5, 5); camera.lookAt(new THREE.Vector3(0, 0, 0));","// No position or lookAt set — subject at y:2 is behind or above the default camera view",Medium,https://threejs.org/docs/#api/en/cameras/Camera.lookAt
|
||||
Camera,OrbitControls vs GSAP Camera Rig,Use OrbitControls for model viewers and exploratory scenes where the user needs free-look. Use a GSAP scroll-driven camera rig for product reveals or storytelling where the camera path must stay fixed.,Match camera control approach to the UX intent of the scene,Use OrbitControls for a scripted reveal — users can orbit away from the reveal before it completes,"// Scroll storytelling — GSAP controls the path: gsap.to(camera.position, { z: 2, scrollTrigger: { trigger: '.scene', scrub: 1 } }); // Free-look model viewer — OrbitControls: const controls = new THREE.OrbitControls(camera, renderer.domElement); controls.enableDamping = true; // call controls.update() in animate()","// Scripted product reveal: const controls = new THREE.OrbitControls(camera, renderer.domElement); // user can rotate away before the animation completes",High,https://threejs.org/docs/#examples/en/controls/OrbitControls
|
||||
Geometry,Never Create Geometry Per Frame,Creating a new geometry inside animate() allocates a fresh GPU buffer every frame and exhausts VRAM within seconds. Create all geometry exactly once before the loop starts. Use attribute mutation if positions must change per frame.,Create all geometry before the animation loop; mutate BufferAttribute arrays in-place if needed,Call any new XxxGeometry() constructor inside the animation loop,"const geo = new THREE.SphereGeometry(1, 32, 32); // created once const mesh = new THREE.Mesh(geo, mat); scene.add(mesh); const clock = new THREE.Clock(); function animate() { requestAnimationFrame(animate); mesh.rotation.y += clock.getDelta() * 0.8; // delta time renderer.render(scene, camera); }","function animate() { requestAnimationFrame(animate); const geo = new THREE.BoxGeometry(1, 1, 1); // NEW GPU buffer every frame — VRAM exhaustion }",Critical,https://threejs.org/docs/#api/en/core/BufferGeometry
|
||||
Geometry,Share Geometry Across Meshes,When multiple objects share the same shape create one geometry instance and pass it to every Mesh. Each Mesh gets its own transform and material while all share a single GPU buffer.,Create one geometry and pass the same reference to every Mesh constructor,Create a separate identical geometry inside a loop for each object,"const geo = new THREE.BoxGeometry(1, 1, 1); // one GPU buffer for (let i = 0; i < 200; i++) { const m = new THREE.Mesh(geo, mat); m.position.set(Math.random() * 10, 0, Math.random() * 10); scene.add(m); }","for (let i = 0; i < 200; i++) { const geo = new THREE.BoxGeometry(1, 1, 1); // 200 separate GPU buffers scene.add(new THREE.Mesh(geo, mat)); }",Critical,https://threejs.org/docs/#api/en/core/BufferGeometry
|
||||
Geometry,dispose on Scene Removal,Call geometry.dispose() and material.dispose() and texture.dispose() for every texture map when removing objects from the scene. Three.js never releases GPU resources automatically — they stay in VRAM until explicitly freed.,Dispose of geometry + material + every texture map before calling scene.remove(),Call scene.remove() alone without any dispose calls,"function removeMesh(mesh) { scene.remove(mesh); mesh.geometry.dispose(); if (mesh.material.map) mesh.material.map.dispose(); if (mesh.material.normalMap) mesh.material.normalMap.dispose(); mesh.material.dispose(); }","scene.remove(mesh); // geometry and all texture maps stay in GPU VRAM forever",Critical,https://threejs.org/docs/#api/en/core/BufferGeometry.dispose
|
||||
Geometry,Segment Count Budget,Use the minimum segment count that achieves the desired silhouette quality. Hero objects: 32–64 segments. Background objects: 8–16. Particle stand-ins: 6–8. High counts on background geometry waste GPU draw calls with zero visible benefit.,Apply a tiered segment budget based on the visual priority of each object in the scene,Default every sphere and cylinder to 64+ segments regardless of its role,"const bgSphere = new THREE.SphereGeometry(0.5, 8, 8); // background const heroSphere = new THREE.SphereGeometry(1, 64, 64); // foreground product","const particleSphere = new THREE.SphereGeometry(0.1, 64, 64); // 64 segments × 1000 particles = massive overdraw",Medium,https://threejs.org/docs/#api/en/geometries/SphereGeometry
|
||||
Geometry,BufferGeometry for Custom Vertex Data,For any custom shape use BufferGeometry with setAttribute('position' ...) and a Float32Array. The legacy THREE.Geometry class was removed in r125 and throws ReferenceError in r128.,Use THREE.BufferGeometry with a Float32Array position attribute for custom vertex data,Reference or instantiate the removed THREE.Geometry class,"const geo = new THREE.BufferGeometry(); geo.setAttribute('position', new THREE.BufferAttribute(new Float32Array(vertices), 3)); geo.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(normals), 3));","const geo = new THREE.Geometry(); geo.vertices.push(new THREE.Vector3(0, 0, 0)); // ReferenceError: Geometry is not defined in r128",High,https://threejs.org/docs/#api/en/core/BufferGeometry
|
||||
Materials,MeshBasicMaterial vs MeshStandardMaterial,MeshBasicMaterial ignores all lights and is significantly cheaper — use it for UI overlays HUDs and flat-colored decorative elements. MeshStandardMaterial is PBR-accurate and requires lights. Never use StandardMaterial where BasicMaterial suffices.,Use MeshBasicMaterial for any object that does not need lighting; use MeshStandardMaterial for physical objects,Apply MeshStandardMaterial to flat UI elements that never receive light — lights still run for them,"const uiMat = new THREE.MeshBasicMaterial({ color: 0xffffff }); // no lighting cost const physMat = new THREE.MeshStandardMaterial({ color: 0x4f46e5, roughness: 0.4, metalness: 0.6 });","const mat = new THREE.MeshStandardMaterial({ color: 0xffffff }); // on a 2D HUD card — lighting calculation runs with no visual benefit",Medium,https://threejs.org/docs/#api/en/materials/MeshStandardMaterial
|
||||
Materials,Share Material Instances,Share one material instance across all meshes that have identical properties. Call mat.clone() only when individual meshes genuinely need different property values. Duplicate materials waste GPU VRAM.,Assign the same material reference to all meshes with identical visual properties,Create a new material inside a loop for objects that look identical,"const mat = new THREE.MeshStandardMaterial({ color: 0x4f46e5, roughness: 0.5 }); meshA.material = mat; meshB.material = mat; meshC.material = mat; // one GPU material","for (const m of meshes) { m.material = new THREE.MeshStandardMaterial({ color: 0x4f46e5 }); } // N redundant GPU materials",High,https://threejs.org/docs/#api/en/materials/Material
|
||||
Materials,Dispose Textures Explicitly,Textures are the single largest consumer of GPU VRAM in most Three.js scenes. Call texture.dispose() when switching scenes or removing objects — Three.js does not garbage-collect GPU resources automatically.,Track all loaded textures and call dispose() on each one during scene teardown or on object removal,Load textures without any cleanup path — they persist in VRAM for the entire page lifetime,"const tex = new THREE.TextureLoader().load('img.jpg'); mesh.material.map = tex; // on teardown: tex.dispose(); mesh.material.dispose();","const tex = new THREE.TextureLoader().load('img.jpg'); scene.remove(mesh); // tex occupies GPU VRAM until page reload",High,https://threejs.org/docs/#api/en/textures/Texture.dispose
|
||||
Lighting,Ambient Plus Directional Minimum,Any scene using MeshStandardMaterial or MeshPhongMaterial requires at minimum one AmbientLight (fill) and one DirectionalLight (shading direction). Without both the objects render as solid black — the material is there but no light reaches it.,Add AmbientLight for fill and DirectionalLight for shading whenever PBR or Phong materials are used,Use MeshStandardMaterial without adding any lights to the scene,"scene.add(new THREE.AmbientLight(0xffffff, 0.4)); const dirLight = new THREE.DirectionalLight(0xffffff, 1.0); dirLight.position.set(5, 10, 7.5); scene.add(dirLight);","const mesh = new THREE.Mesh(geo, new THREE.MeshStandardMaterial({ color: 0x4f46e5 })); scene.add(mesh); // renders completely black — no lights in scene",Critical,https://threejs.org/docs/#api/en/lights/DirectionalLight
|
||||
Lighting,Enable shadowMap Before castShadow,renderer.shadowMap.enabled = true must be set before any castShadow or receiveShadow flags. Without it the shadow map is never allocated and all shadow flags are silently ignored.,Set renderer.shadowMap.enabled = true first then set castShadow and receiveShadow on lights and meshes,Set castShadow on a light or mesh without enabling renderer.shadowMap.enabled — shadows never render,"renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFSoftShadowMap; dirLight.castShadow = true; dirLight.shadow.mapSize.width = 2048; dirLight.shadow.mapSize.height = 2048; heroMesh.castShadow = true; ground.receiveShadow = true;","dirLight.castShadow = true; heroMesh.castShadow = true; // renderer.shadowMap.enabled never set — shadows silently do not render",High,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.shadowMap
|
||||
Lighting,Selective Shadow Casting,Shadow map rendering redraws the entire scene from the light's perspective every frame. Enable castShadow only on the primary directional light and receiveShadow only on hero meshes and the ground plane.,Enable shadows only on the key light and the most important meshes,Enable castShadow and receiveShadow on every object in the scene including particles,"renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFSoftShadowMap; dirLight.castShadow = true; heroMesh.castShadow = true; ground.receiveShadow = true; // particles and background meshes: no shadow flags","for (const m of allMeshes) { m.castShadow = true; m.receiveShadow = true; } // shadow map pass over particle system — expensive with no visible gain",High,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.shadowMap
|
||||
Lighting,Skip Lights for MeshBasicMaterial,MeshBasicMaterial completely ignores all scene lights. Adding lights solely to illuminate BasicMaterial objects wastes a light pass on every frame with zero visible effect.,Omit lights entirely when every material in the scene is MeshBasicMaterial,Add AmbientLight and DirectionalLight to a scene that uses only MeshBasicMaterial,"// Scene uses only MeshBasicMaterial — no lights needed const mat = new THREE.MeshBasicMaterial({ color: 0x00ffff }); const mesh = new THREE.Mesh(geo, mat); scene.add(mesh); // MeshBasicMaterial is always fully lit by definition","scene.add(new THREE.AmbientLight(0xffffff, 1.0)); // wasted per-frame light pass — BasicMaterial ignores it entirely",Low,https://threejs.org/docs/#api/en/materials/MeshBasicMaterial
|
||||
Raycasting,Single Shared Raycaster,Create exactly one Raycaster instance outside all event handlers. Store mouse coordinates in pointermove (cheap). Call setFromCamera and intersectObjects together inside the animate() loop — once per frame instead of once per mouse event.,Create one Raycaster; store mouse in pointermove; call setFromCamera + intersectObjects inside animate(),Create a new THREE.Raycaster() inside a mousemove handler or call setFromCamera inside the event listener,"const raycaster = new THREE.Raycaster(); const mouse = new THREE.Vector2(); canvas.addEventListener('pointermove', e => { // only store coords — no raycasting here mouse.x = (e.clientX / canvas.clientWidth) * 2 - 1; mouse.y = -(e.clientY / canvas.clientHeight) * 2 + 1; }); // setFromCamera and intersectObjects run once per frame in animate()","window.addEventListener('mousemove', e => { const rc = new THREE.Raycaster(); // new allocation per event rc.setFromCamera(mouse, camera); rc.intersectObjects(targets, true); // fires 200+ times/sec });",Critical,https://threejs.org/docs/#api/en/core/Raycaster
|
||||
Raycasting,NDC Mouse Coordinates,Raycasting requires mouse in Normalized Device Coordinates: X from -1 (left) to +1 (right) and Y from +1 (top) to -1 (bottom). The Y axis is inverted relative to screen space. A missing negation on Y causes all raycasts to miss or hit the wrong objects.,Apply the full NDC formula — including the negation on the Y axis,Forget to negate Y — raycasting appears to work but hits objects mirrored vertically,"mouse.x = (e.clientX / canvas.clientWidth) * 2 - 1; mouse.y = -(e.clientY / canvas.clientHeight) * 2 + 1; // Y is INVERTED","mouse.x = (e.clientX / canvas.clientWidth) * 2 - 1; mouse.y = (e.clientY / canvas.clientHeight) * 2 - 1; // BUG: Y not negated — raycasting is mirrored",Critical,https://threejs.org/docs/#api/en/core/Raycaster.setFromCamera
|
||||
Raycasting,setFromCamera and intersectObjects in animate,Call raycaster.setFromCamera(mouse camera) and then raycaster.intersectObjects(targets true) inside the animate() loop. setFromCamera must come before intersectObjects every frame — without it the raycaster uses a stale ray direction.,Call setFromCamera then intersectObjects in order inside every animate() frame,Call intersectObjects without calling setFromCamera first — the raycaster uses a stale or zero ray,"function animate() { requestAnimationFrame(animate); raycaster.setFromCamera(mouse, camera); // update ray direction first const hits = raycaster.intersectObjects(targets, true); // then test intersections if (hits.length > 0) { document.body.style.cursor = 'pointer'; } else { document.body.style.cursor = 'auto'; } renderer.render(scene, camera); }","function animate() { requestAnimationFrame(animate); const hits = raycaster.intersectObjects(targets, true); // BUG: setFromCamera never called — stale ray — hits is always empty renderer.render(scene, camera); }",Critical,https://threejs.org/docs/#api/en/core/Raycaster
|
||||
Raycasting,Recursive Flag for Groups and GLTF,Pass true as the second argument to intersectObjects when testing Groups or GLTF loaded models. Geometry lives on child Mesh objects — without recursive:true the parent group is tested but has no geometry and hits is always empty.,Use intersectObjects(targets true) for Groups or any loaded model,Raycast against a parent Group without the recursive flag,"const hits = raycaster.intersectObjects(scene.children, true); // catches all descendant meshes","const hits = raycaster.intersectObjects([modelGroup]); // recursive defaults to false — misses all children",High,https://threejs.org/docs/#api/en/core/Raycaster.intersectObjects
|
||||
Raycasting,Cursor Feedback on Hover,Set document.body.style.cursor = 'pointer' when intersections are found and reset to 'auto' when none are found. Without cursor feedback users cannot discover that 3D objects are interactive.,Update cursor to pointer on hit; reset to auto on miss in the same animate loop block,Run raycasting and read hits without ever updating the cursor style,"if (hits.length > 0) { document.body.style.cursor = 'pointer'; } else { document.body.style.cursor = 'auto'; }","raycaster.setFromCamera(mouse, camera); raycaster.intersectObjects(targets, true); // hits ignored — cursor never changes — objects feel non-interactive",Medium,https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
|
||||
Animation,requestAnimationFrame Loop Only,Drive the render loop exclusively with requestAnimationFrame or renderer.setAnimationLoop(). Never use setInterval or setTimeout — they are not synchronized to the display refresh rate and keep running when the tab is hidden draining battery.,Use requestAnimationFrame or renderer.setAnimationLoop() as the sole render loop driver,Use setInterval or setTimeout for render timing,"function animate() { requestAnimationFrame(animate); renderer.render(scene, camera); } animate();","setInterval(() => renderer.render(scene, camera), 16); // not display-synced; runs at full speed even when tab is hidden",Critical,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.setAnimationLoop
|
||||
Animation,THREE.Clock for Delta Time,"Use THREE.Clock and clock.getDelta() for all time-based motion. A hardcoded increment like += 0.01 runs at 2x speed on 120Hz displays and at unpredictable speed when frames drop under load. CRITICAL: call getDelta() exactly ONCE per animate() frame and store the result in a local dt variable. getDelta() resets the internal clock on every call — a second call in the same frame always returns ~0, silently breaking any animation block that uses it.","Call clock.getDelta() once at the top of animate(); store result in dt; reuse dt everywhere in that frame","Call clock.getDelta() more than once per frame or inside a helper called from animate()","const clock = new THREE.Clock(); function animate() { requestAnimationFrame(animate); const dt = clock.getDelta(); // called ONCE — reuse dt below mesh.rotation.y += dt * 0.8; particles.rotation.y += dt * 0.1; // reuse dt, not a second getDelta() renderer.render(scene, camera); }","function animate() { requestAnimationFrame(animate); mesh.rotation.y += 0.01; // 0.01 rad/frame — runs 2x faster on 120Hz than on 60Hz }",High,https://threejs.org/docs/#api/en/core/Clock
|
||||
Animation,Lerp for Smooth Pointer Follow,Use value += (target - value) * alpha each frame to smoothly interpolate toward a moving target. An alpha of 0.03–0.1 produces organic easing for camera follow pointer-tracking and hover scale effects without requiring GSAP.,Apply the lerp formula each frame with a small alpha for smooth organic motion,Snap a value directly to the target producing an instant jarring jump,"// In animate(): cameraTargetX = mouse.x * 3; camera.position.x += (cameraTargetX - camera.position.x) * 0.05; camera.position.y += (cameraTargetY - camera.position.y) * 0.05; camera.lookAt(scene.position);","// In animate(): camera.position.x = mouse.x * 3; // instant snap — jarring with no easing",Medium,https://threejs.org/docs/#api/en/math/MathUtils.lerp
|
||||
Animation,GSAP for Multi-Step Sequences,Use GSAP timelines for any animation with more than two sequential steps or for scroll-linked camera paths. GSAP timelines can be paused reversed and scrubbed — far more maintainable than boolean state machines.,Use GSAP timelines for sequences with more than two steps and for scroll-driven animations,Implement multi-step sequences with boolean flags and manual frame counters,"const tl = gsap.timeline({ defaults: { ease: 'power2.out' } }); tl.from(mesh.position, { y: -3, duration: 1 }) .to(mesh.rotation, { y: Math.PI, duration: 1 }, '-=0.3') .to(camera.position, { z: 2, duration: 1.5 });","let step = 0; let t = 0; function animate() { if (step === 0 && (t += 0.01) >= 1) step = 1; } // grows unmanageable with 3+ steps",High,https://gsap.com/docs/v3/GSAP/Timeline/
|
||||
Animation,Pause Render Loop on Tab Hidden,Use renderer.setAnimationLoop() as the loop driver so you can pass null to pause and a function to resume. Continuous rendering in a hidden tab wastes CPU GPU and battery with no user benefit.,Use renderer.setAnimationLoop(animate) to drive the loop; pass null to pause on visibilitychange,Drive with internal requestAnimationFrame and never stop the loop when the tab is hidden,"renderer.setAnimationLoop(animate); // use setAnimationLoop as the driver — not requestAnimationFrame inside animate function animate() { const dt = clock.getDelta(); renderer.render(scene, camera); } document.addEventListener('visibilitychange', () => { if (document.hidden) renderer.setAnimationLoop(null); else renderer.setAnimationLoop(animate); });","function animate() { requestAnimationFrame(animate); // self-referencing RAF cannot be stopped externally renderer.render(scene, camera); } animate(); // runs forever in background tab — drains battery",High,https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API
|
||||
GSAP,Load GSAP Before Scene Script,Load GSAP from its own CDN script tag before your scene script. In bundler projects install via npm and import. GSAP is a completely separate library from Three.js — never try to import it from the Three.js package.,Load GSAP CDN before the scene script; or npm install gsap and import separately,Import gsap from three or expect it to be defined without a separate load,"<!-- CDN: load GSAP before your scene script --> <script src=""https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js""></script> <!-- Bundler: --> // import gsap from 'gsap'; import { ScrollTrigger } from 'gsap/ScrollTrigger';","import gsap from 'three'; // undefined — GSAP has nothing to do with Three.js",Critical,https://gsap.com/docs/v3/Installation
|
||||
GSAP,Register ScrollTrigger Before Use,Call gsap.registerPlugin(ScrollTrigger) once at the top of your script before any scrollTrigger config object. Without registration the ScrollTrigger name is undefined and the tween throws immediately.,Call gsap.registerPlugin(ScrollTrigger) as the first line before any gsap.to/from/timeline with scrollTrigger,Include scrollTrigger config in gsap.to() calls without first registering the plugin,"gsap.registerPlugin(ScrollTrigger); gsap.to(camera.position, { z: 2, scrollTrigger: { trigger: '.hero-section', scrub: 1 } });","gsap.to(mesh.position, { scrollTrigger: { trigger: '.section', scrub: true } }); // TypeError: ScrollTrigger is not a constructor — not registered",Critical,https://gsap.com/docs/v3/Plugins/ScrollTrigger/
|
||||
GSAP,Tween Three.js Properties Directly,GSAP can tween any numeric JavaScript property including mesh.position.x mesh.rotation.y and material.opacity. No wrapper or adaptor is needed. Note: to tween material.opacity the material must have transparent:true set before the tween starts.,Pass Three.js object properties directly to gsap.to(); set transparent:true before tweening opacity,Use a plain proxy object then manually copy values to Three.js properties every frame,"gsap.to(mesh.rotation, { y: Math.PI * 2, duration: 2, ease: 'power1.inOut' }); mesh.material.transparent = true; // required before tweening opacity gsap.to(mesh.material, { opacity: 0, duration: 1 });","const tw = { v: 0 }; gsap.to(tw, { v: Math.PI * 2, onUpdate: () => mesh.rotation.y = tw.v }); // unnecessary proxy wrapper",Medium,https://gsap.com/docs/v3/GSAP/gsap.to()
|
||||
GSAP,scrub for Scroll-Driven Camera Path,Use scrub:true or scrub:1 to link camera movement continuously to scroll position as a 0–1 ratio. scrub:1 adds a 1-second lag for cinematic smoothness. onEnter/onLeave fire only once and create jarring snaps — not the right tool for a camera path.,Use scrub:1 for any scroll-controlled camera movement,Use onEnter or onLeave callbacks for camera motion — they snap instead of scrubbing,"gsap.registerPlugin(ScrollTrigger); gsap.to(camera.position, { x: 5, y: 2, z: 0, ease: 'none', scrollTrigger: { trigger: '.canvas-wrapper', start: 'top top', end: 'bottom bottom', scrub: 1 } });","gsap.to(camera.position, { z: 0, scrollTrigger: { trigger: '.section', onEnter: () => {} } }); // fires once at scroll threshold — not a continuous scrub",High,https://gsap.com/docs/v3/Plugins/ScrollTrigger/
|
||||
Performance,InstancedMesh for Repeated Objects,Use THREE.InstancedMesh when rendering 50 or more identical objects. It submits all N transforms in one draw call instead of N draw calls and reduces CPU-GPU communication overhead dramatically.,Use InstancedMesh for any group of 50+ meshes sharing the same geometry and material,Create 50+ separate Mesh objects with the same geometry and material,"const COUNT = 500; const iMesh = new THREE.InstancedMesh(geo, mat, COUNT); const matrix = new THREE.Matrix4(); for (let i = 0; i < COUNT; i++) { matrix.setPosition(Math.random()*10, Math.random()*10, Math.random()*10); iMesh.setMatrixAt(i, matrix); } iMesh.instanceMatrix.needsUpdate = true; scene.add(iMesh);","for (let i = 0; i < 500; i++) { scene.add(new THREE.Mesh(geo, mat)); } // 500 separate draw calls per frame",High,https://threejs.org/docs/#api/en/objects/InstancedMesh
|
||||
Performance,Tone Mapping and sRGB Encoding,Enable ACESFilmicToneMapping and sRGBEncoding on the renderer for accurate perceptual color. Without tone mapping colors appear washed out or over-saturated. These are renderer properties set after construction and take effect immediately.,Set renderer.toneMapping and renderer.outputEncoding after construction for all production scenes,Leave tone mapping and output encoding at defaults when the scene targets realistic visuals,"renderer.toneMapping = THREE.ACESFilmicToneMapping; renderer.toneMappingExposure = 1.0; renderer.outputEncoding = THREE.sRGBEncoding; // correct for r128","const renderer = new THREE.WebGLRenderer(); // defaults: NoToneMapping + LinearEncoding — colors appear flat and incorrect",Medium,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.toneMapping
|
||||
Performance,antialias Set at Construction Only,The antialias option can only be set at WebGLRenderer construction time. Setting renderer.antialias after construction has absolutely no effect — the WebGL context is already created without it. Decide before instantiating.,Set antialias:true inside the WebGLRenderer constructor options object,Construct the renderer without antialias then try to enable it by assigning the property,"const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true }); // antialias baked into the WebGL context","const renderer = new THREE.WebGLRenderer(); renderer.antialias = true; // no effect — context created without AA — edges remain aliased",High,https://threejs.org/docs/#api/en/renderers/WebGLRenderer
|
||||
Performance,FogExp2 for Depth and Far Culling,Use scene.fog to create atmospheric depth. As a secondary benefit objects that disappear into fog before the far plane stop contributing to draw calls — useful in scenes with large view distances.,Add FogExp2 to scenes with view distances above 100 units for both visual atmosphere and implicit far culling,Ignore fog in scenes with far:1000+ and many distant objects that contribute tiny pixels per draw call,"scene.fog = new THREE.FogExp2(0x0a0a0a, 0.02); // exponential — density feels more natural than linear","// far: 2000 with no fog — hundreds of distant objects too small to see still cost draw calls per frame",Low,https://threejs.org/docs/#api/en/scenes/FogExp2
|
||||
Particles,BufferGeometry Plus Points for Particle Systems,Build all particle systems with BufferGeometry plus a Float32Array position attribute rendered as Points. Never use individual Mesh objects as particles — they cannot scale past a few hundred with good performance.,Use Points plus BufferGeometry for all particle effects,Create hundreds of individual Mesh objects to simulate a particle system,"const COUNT = 3000; const geo = new THREE.BufferGeometry(); const pos = new Float32Array(COUNT * 3); for (let i = 0; i < COUNT * 3; i++) pos[i] = (Math.random() - 0.5) * 20; geo.setAttribute('position', new THREE.BufferAttribute(pos, 3)); const particles = new THREE.Points(geo, new THREE.PointsMaterial({ size: 0.05, color: 0xffffff })); scene.add(particles);","for (let i = 0; i < 500; i++) { scene.add(new THREE.Mesh(new THREE.SphereGeometry(0.05, 8, 8), mat)); } // 500 separate draw calls per frame",High,https://threejs.org/docs/#api/en/objects/Points
|
||||
Particles,Particle Count Ceiling,Start particle systems at 1000–3000 particles. Beyond 50000 causes sustained frame drops on mid-range mobile. Always test on a real device before increasing the count — desktop and mobile GPU performance ratios can be 10:1.,Start at 3000 particles and profile on actual mobile hardware before raising the limit,Set particle count at 100000 or higher without any mobile profiling,"const COUNT = 3000; // safe mobile baseline — profile before going higher const pos = new Float32Array(COUNT * 3);","const COUNT = 150000; // 60fps on desktop — 8fps on a mid-range Android phone",High,https://threejs.org/docs/#api/en/objects/Points
|
||||
Particles,needsUpdate After Buffer Mutation,After mutating any BufferAttribute array values per frame you must set geometry.attributes.position.needsUpdate = true so Three.js re-uploads the changed buffer to the GPU. Without it the GPU still uses the old data and particles appear completely frozen.,Set needsUpdate = true on the position attribute after every per-frame mutation of the array,Mutate the Float32Array values without flagging needsUpdate — positions update in JS but not on the GPU,"// In animate(): const pos = geo.attributes.position.array; for (let i = 0; i < pos.length; i += 3) { pos[i + 1] += Math.sin(clock.getElapsedTime() + i) * 0.001; // Y component } geo.attributes.position.needsUpdate = true; // GPU re-upload","// In animate(): pos[1] += 0.001; // JS array updated — GPU buffer is stale — particles do not move",Critical,https://threejs.org/docs/#api/en/core/BufferAttribute.needsUpdate
|
||||
Responsive,Canvas Dimensions Not Window,Size the renderer and camera to the canvas element's clientWidth and clientHeight — not window.innerWidth and innerHeight. This is correct when the canvas is inside a flex or grid container that does not fill the full viewport.,Use canvas.clientWidth and canvas.clientHeight for all renderer and camera sizing,Hardcode renderer size to window.innerWidth/innerHeight when the canvas may be inside a container,"renderer.setSize(canvas.clientWidth, canvas.clientHeight); camera.aspect = canvas.clientWidth / canvas.clientHeight; camera.updateProjectionMatrix();","renderer.setSize(window.innerWidth, window.innerHeight); // wrong when canvas lives inside a sidebar or grid column",High,https://threejs.org/docs/#api/en/renderers/WebGLRenderer.setSize
|
||||
Responsive,ResizeObserver Over window resize Event,Use ResizeObserver on the canvas container instead of the window resize event. ResizeObserver fires when the container element changes size independently of the browser window — common in split-pane layouts and sidebar collapsing.,Attach ResizeObserver to the canvas parent element for accurate container-aware resize detection,Use only window.addEventListener('resize') for canvas sizing when the canvas is not fullscreen,"const ro = new ResizeObserver(entries => { const { width, height } = entries[0].contentRect; renderer.setSize(width, height); camera.aspect = width / height; camera.updateProjectionMatrix(); }); ro.observe(canvas.parentElement);","window.addEventListener('resize', () => { renderer.setSize(window.innerWidth, window.innerHeight); }); // misses container-only resize events in split-pane UIs",Medium,https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
|
||||
Responsive,Touch Events for Mobile Interaction,Add touchstart and touchmove listeners alongside mouse events so the scene remains interactive on mobile. Normalize touch coordinates to the same NDC range as mouse events and pass passive:false on touchmove if you call preventDefault.,Handle both mouse and touch input for any interactive 3D scene,Add only mouse event listeners and leave touch users with no interaction,"canvas.addEventListener('touchmove', e => { e.preventDefault(); const t = e.touches[0]; mouse.x = (t.clientX / canvas.clientWidth) * 2 - 1; mouse.y = -(t.clientY / canvas.clientHeight) * 2 + 1; }, { passive: false }); canvas.addEventListener('touchstart', e => { e.preventDefault(); }, { passive: false });","canvas.addEventListener('mousemove', handleMouse); // touch events unhandled — mobile users get no interaction",Medium,https://developer.mozilla.org/en-US/docs/Web/API/Touch_events
|
||||
Accessibility,prefers-reduced-motion,"Check window.matchMedia('(prefers-reduced-motion: reduce)') before starting any auto-rotation, particle animation, or camera movement. Users who enable this OS preference have motion sickness or vestibular disorders. IMPORTANT: reading .matches once at page load is a one-time snapshot — if the user changes their OS accessibility setting mid-session the scene will not react. Attach a 'change' listener to the MediaQueryList so noMotion stays in sync at runtime.","Use matchMedia.addEventListener('change') to keep noMotion reactive; gate all auto-animation on the live value","Read .matches once at startup and never update it — the scene ignores mid-session OS setting changes","const mq = window.matchMedia('(prefers-reduced-motion: reduce)'); let noMotion = mq.matches; mq.addEventListener('change', e => { noMotion = e.matches; }); // In animate(): if (!noMotion) { mesh.rotation.y += dt * 0.8; particles.rotation.y += dt * 0.1; }","const noMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches; // one-time snapshot — mid-session OS change is ignored entirely",High,https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
|
||||
Accessibility,Canvas aria-label,Add role='img' and a descriptive aria-label to renderer.domElement after appending it to the DOM. Screen readers receive no information from a WebGL canvas — the aria-label is the only description they can announce to users.,Set role='img' and a meaningful aria-label on renderer.domElement before or after appending it,Append the canvas to the DOM with no accessibility attributes — invisible to screen readers,"renderer.domElement.setAttribute('role', 'img'); renderer.domElement.setAttribute('aria-label', 'Interactive 3D product viewer. Drag to rotate. Scroll to zoom.'); document.body.appendChild(renderer.domElement);","document.body.appendChild(renderer.domElement); // bare canvas — screen readers announce nothing",Medium,https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas#accessibility_concerns
|
||||
Production,Bundler Stack for Production,For production use Three.js via npm plus Vite. You get full tree-shaking reduced bundle size access to the complete examples/jsm library including OrbitControls GLTFLoader and EffectComposer and TypeScript support.,Use npm install three plus Vite or Webpack for any production client-facing project,Serve raw CDN script tags in a production application that needs tree-shaking or TypeScript,"npm install three gsap // then in your JS: import * as THREE from 'three'; import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'; import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';","<!-- In a Vite/React production build: --> <script src=""https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js""></script> // no tree-shaking — entire Three.js ships",Medium,https://threejs.org/docs/#manual/en/introduction/Installation
|
||||
Production,GLTFLoader with scene traverse,Load 3D models using GLTFLoader and traverse gltf.scene to configure castShadow receiveShadow and material overrides on all child Mesh nodes. Calling scene.add(gltf.scene) alone silently skips all shadow and material configuration.,Use GLTFLoader and traverse the entire gltf.scene graph to set up shadows and materials on every Mesh child,Load a GLTF model and pass gltf.scene directly to scene.add without traversing child meshes,"import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'; const loader = new GLTFLoader(); loader.load('model.glb', gltf => { gltf.scene.traverse(child => { if (child.isMesh) { child.castShadow = true; child.receiveShadow = true; } }); scene.add(gltf.scene); });","loader.load('model.glb', gltf => { scene.add(gltf.scene); // shadows and material setup silently skipped on all children });",Medium,https://threejs.org/docs/#examples/en/loaders/GLTFLoader
|
||||
Production,LOD for Distance-Based Detail,Use THREE.LOD to automatically swap high-detail and low-detail geometry as objects move closer or farther from the camera. This maintains frame rate in scenes with many objects spread across a large depth range.,Use THREE.LOD to reduce triangle count on distant objects automatically,Render the same high-polygon geometry for every object regardless of its distance from the camera,"const lod = new THREE.LOD(); lod.addLevel(highDetailMesh, 0); // used when < 15 units away lod.addLevel(medDetailMesh, 15); // 15–50 units lod.addLevel(lowDetailMesh, 50); // 50+ units scene.add(lod);","scene.add(highDetailMesh); // 64k-triangle mesh rendered at full cost whether 1 unit or 100 units from camera",Medium,https://threejs.org/docs/#api/en/objects/LOD
|
||||
|
|
|
@ -1,50 +0,0 @@
|
|||
No,Category,Guideline,Description,Do,Don't,Code Good,Code Bad,Severity,Docs URL
|
||||
1,Composition,Use Composition API for new projects,Composition API offers better TypeScript support and logic reuse,<script setup> for components,Options API for new projects,<script setup>,export default { data() },Medium,https://vuejs.org/guide/extras/composition-api-faq.html
|
||||
2,Composition,Use script setup syntax,Cleaner syntax with automatic exports,<script setup> with defineProps,setup() function manually,<script setup>,<script> setup() { return {} },Low,https://vuejs.org/api/sfc-script-setup.html
|
||||
3,Reactivity,Use ref for primitives,ref() for primitive values that need reactivity,ref() for strings numbers booleans,reactive() for primitives,const count = ref(0),const count = reactive(0),Medium,https://vuejs.org/guide/essentials/reactivity-fundamentals.html
|
||||
4,Reactivity,Use reactive for objects,reactive() for complex objects and arrays,reactive() for objects with multiple properties,ref() for complex objects,const state = reactive({ user: null }),const state = ref({ user: null }),Medium,
|
||||
5,Reactivity,Access ref values with .value,Remember .value in script unwrap in template,Use .value in script,Forget .value in script,count.value++,count++ (in script),High,
|
||||
6,Reactivity,Use computed for derived state,Computed properties cache and update automatically,computed() for derived values,Methods for derived values,const doubled = computed(() => count.value * 2),const doubled = () => count.value * 2,Medium,https://vuejs.org/guide/essentials/computed.html
|
||||
7,Reactivity,Use shallowRef for large objects,Avoid deep reactivity for performance,shallowRef for large data structures,ref for large nested objects,const bigData = shallowRef(largeObject),const bigData = ref(largeObject),Medium,https://vuejs.org/api/reactivity-advanced.html#shallowref
|
||||
8,Watchers,Use watchEffect for simple cases,Auto-tracks dependencies,watchEffect for simple reactive effects,watch with explicit deps when not needed,watchEffect(() => console.log(count.value)),"watch(count, (val) => console.log(val))",Low,https://vuejs.org/guide/essentials/watchers.html
|
||||
9,Watchers,Use watch for specific sources,Explicit control over what to watch,watch with specific refs,watchEffect for complex conditional logic,"watch(userId, fetchUser)",watchEffect with conditionals,Medium,
|
||||
10,Watchers,Clean up side effects,Return cleanup function in watchers,Return cleanup in watchEffect,Leave subscriptions open,watchEffect((onCleanup) => { onCleanup(unsub) }),watchEffect without cleanup,High,
|
||||
11,Props,Define props with defineProps,Type-safe prop definitions,defineProps with TypeScript,Props without types,defineProps<{ msg: string }>(),defineProps(['msg']),Medium,https://vuejs.org/guide/typescript/composition-api.html#typing-component-props
|
||||
12,Props,Use withDefaults for default values,Provide defaults for optional props,withDefaults with defineProps,Defaults in destructuring,"withDefaults(defineProps<Props>(), { count: 0 })",const { count = 0 } = defineProps(),Medium,
|
||||
13,Props,Avoid mutating props,Props should be read-only,Emit events to parent for changes,Direct prop mutation,"emit('update:modelValue', newVal)",props.modelValue = newVal,High,
|
||||
14,Emits,Define emits with defineEmits,Type-safe event emissions,defineEmits with types,Emit without definition,defineEmits<{ change: [id: number] }>(),"emit('change', id) without define",Medium,https://vuejs.org/guide/typescript/composition-api.html#typing-component-emits
|
||||
15,Emits,Use v-model for two-way binding,Simplified parent-child data flow,v-model with modelValue prop,:value + @input manually,"<Child v-model=""value""/>","<Child :value=""value"" @input=""value = $event""/>",Low,https://vuejs.org/guide/components/v-model.html
|
||||
16,Lifecycle,Use onMounted for DOM access,DOM is ready in onMounted,onMounted for DOM operations,Access DOM in setup directly,onMounted(() => el.value.focus()),el.value.focus() in setup,High,https://vuejs.org/api/composition-api-lifecycle.html
|
||||
17,Lifecycle,Clean up in onUnmounted,Remove listeners and subscriptions,onUnmounted for cleanup,Leave listeners attached,onUnmounted(() => window.removeEventListener()),No cleanup on unmount,High,
|
||||
18,Lifecycle,Avoid onBeforeMount for data,Use onMounted or setup for data fetching,Fetch in onMounted or setup,Fetch in onBeforeMount,onMounted(async () => await fetchData()),onBeforeMount(async () => await fetchData()),Low,
|
||||
19,Components,Use single-file components,Keep template script style together,.vue files for components,Separate template/script files,Component.vue with all parts,Component.js + Component.html,Low,
|
||||
20,Components,Use PascalCase for components,Consistent component naming,PascalCase in imports and templates,kebab-case in script,<MyComponent/>,<my-component/>,Low,https://vuejs.org/style-guide/rules-strongly-recommended.html
|
||||
21,Components,Prefer composition over mixins,Composables replace mixins,Composables for shared logic,Mixins for code reuse,const { data } = useApi(),mixins: [apiMixin],Medium,
|
||||
22,Composables,Name composables with use prefix,Convention for composable functions,useFetch useAuth useForm,getData or fetchApi,export function useFetch(),export function fetchData(),Medium,https://vuejs.org/guide/reusability/composables.html
|
||||
23,Composables,Return refs from composables,Maintain reactivity when destructuring,Return ref values,Return reactive objects that lose reactivity,return { data: ref(null) },return reactive({ data: null }),Medium,
|
||||
24,Composables,Accept ref or value params,Use toValue for flexible inputs,toValue() or unref() for params,Only accept ref or only value,const val = toValue(maybeRef),const val = maybeRef.value,Low,https://vuejs.org/api/reactivity-utilities.html#tovalue
|
||||
25,Templates,Use v-bind shorthand,Cleaner template syntax,:prop instead of v-bind:prop,Full v-bind syntax,"<div :class=""cls"">","<div v-bind:class=""cls"">",Low,
|
||||
26,Templates,Use v-on shorthand,Cleaner event binding,@event instead of v-on:event,Full v-on syntax,"<button @click=""handler"">","<button v-on:click=""handler"">",Low,
|
||||
27,Templates,Avoid v-if with v-for,v-if has higher priority causes issues,Wrap in template or computed filter,v-if on same element as v-for,<template v-for><div v-if>,<div v-for v-if>,High,https://vuejs.org/style-guide/rules-essential.html#avoid-v-if-with-v-for
|
||||
28,Templates,Use key with v-for,Proper list rendering and updates,Unique key for each item,Index as key for dynamic lists,"v-for=""item in items"" :key=""item.id""","v-for=""(item, i) in items"" :key=""i""",High,
|
||||
29,State,Use Pinia for global state,Official state management for Vue 3,Pinia stores for shared state,Vuex for new projects,const store = useCounterStore(),Vuex with mutations,Medium,https://pinia.vuejs.org/
|
||||
30,State,Define stores with defineStore,Composition API style stores,Setup stores with defineStore,Options stores for complex state,"defineStore('counter', () => {})","defineStore('counter', { state })",Low,
|
||||
31,State,Use storeToRefs for destructuring,Maintain reactivity when destructuring,storeToRefs(store),Direct destructuring,const { count } = storeToRefs(store),const { count } = store,High,https://pinia.vuejs.org/core-concepts/#destructuring-from-a-store
|
||||
32,Routing,Use useRouter and useRoute,Composition API router access,useRouter() useRoute() in setup,this.$router this.$route,const router = useRouter(),this.$router.push(),Medium,https://router.vuejs.org/guide/advanced/composition-api.html
|
||||
33,Routing,Lazy load route components,Code splitting for routes,() => import() for components,Static imports for all routes,component: () => import('./Page.vue'),component: Page,Medium,https://router.vuejs.org/guide/advanced/lazy-loading.html
|
||||
34,Routing,Use navigation guards,Protect routes and handle redirects,beforeEach for auth checks,Check auth in each component,router.beforeEach((to) => {}),Check auth in onMounted,Medium,
|
||||
35,Performance,Use v-once for static content,Skip re-renders for static elements,v-once on never-changing content,v-once on dynamic content,<div v-once>{{ staticText }}</div>,<div v-once>{{ dynamicText }}</div>,Low,https://vuejs.org/api/built-in-directives.html#v-once
|
||||
36,Performance,Use v-memo for expensive lists,Memoize list items,v-memo with dependency array,Re-render entire list always,"<div v-for v-memo=""[item.id]"">",<div v-for> without memo,Medium,https://vuejs.org/api/built-in-directives.html#v-memo
|
||||
37,Performance,Use shallowReactive for flat objects,Avoid deep reactivity overhead,shallowReactive for flat state,reactive for simple objects,shallowReactive({ count: 0 }),reactive({ count: 0 }),Low,
|
||||
38,Performance,Use defineAsyncComponent,Lazy load heavy components,defineAsyncComponent for modals dialogs,Import all components eagerly,defineAsyncComponent(() => import()),import HeavyComponent from,Medium,https://vuejs.org/guide/components/async.html
|
||||
39,TypeScript,Use generic components,Type-safe reusable components,Generic with defineComponent,Any types in components,"<script setup lang=""ts"" generic=""T"">",<script setup> without types,Medium,https://vuejs.org/guide/typescript/composition-api.html
|
||||
40,TypeScript,Type template refs,Proper typing for DOM refs,ref<HTMLInputElement>(null),ref(null) without type,const input = ref<HTMLInputElement>(null),const input = ref(null),Medium,
|
||||
41,TypeScript,Use PropType for complex props,Type complex prop types,PropType<User> for object props,Object without type,type: Object as PropType<User>,type: Object,Medium,
|
||||
42,Testing,Use Vue Test Utils,Official testing library,mount shallowMount for components,Manual DOM testing,import { mount } from '@vue/test-utils',document.createElement,Medium,https://test-utils.vuejs.org/
|
||||
43,Testing,Test component behavior,Focus on inputs and outputs,Test props emit and rendered output,Test internal implementation,expect(wrapper.text()).toContain(),expect(wrapper.vm.internalState),Medium,
|
||||
44,Forms,Use v-model modifiers,Built-in input handling,.lazy .number .trim modifiers,Manual input parsing,"<input v-model.number=""age"">","<input v-model=""age""> then parse",Low,https://vuejs.org/guide/essentials/forms.html#modifiers
|
||||
45,Forms,Use VeeValidate or FormKit,Form validation libraries,VeeValidate for complex forms,Manual validation logic,useField useForm from vee-validate,Custom validation in each input,Medium,
|
||||
46,Accessibility,Use semantic elements,Proper HTML elements in templates,button nav main for purpose,div for everything,<button @click>,<div @click>,High,
|
||||
47,Accessibility,Bind aria attributes dynamically,Keep ARIA in sync with state,":aria-expanded=""isOpen""",Static ARIA values,":aria-expanded=""menuOpen""","aria-expanded=""true""",Medium,
|
||||
48,SSR,Use Nuxt for SSR,Full-featured SSR framework,Nuxt 3 for SSR apps,Manual SSR setup,npx nuxi init my-app,Custom SSR configuration,Medium,https://nuxt.com/
|
||||
49,SSR,Handle hydration mismatches,Client/server content must match,ClientOnly for browser-only content,Different content server/client,<ClientOnly><BrowserWidget/></ClientOnly>,<div>{{ Date.now() }}</div>,High,
|
||||
|
|
|
@ -1,85 +0,0 @@
|
|||
No,Style Category,Type,Keywords,Primary Colors,Secondary Colors,Effects & Animation,Best For,Do Not Use For,Light Mode ✓,Dark Mode ✓,Performance,Accessibility,Mobile-Friendly,Conversion-Focused,Framework Compatibility,Era/Origin,Complexity,AI Prompt Keywords,CSS/Technical Keywords,Implementation Checklist,Design System Variables
|
||||
1,Minimalism & Swiss Style,General,"Clean, simple, spacious, functional, white space, high contrast, geometric, sans-serif, grid-based, essential","Monochromatic, Black #000000, White #FFFFFF","Neutral (Beige #F5F1E8, Grey #808080, Taupe #B38B6D), Primary accent","Subtle hover (200-250ms), smooth transitions, sharp shadows if any, clear type hierarchy, fast loading","Enterprise apps, dashboards, documentation sites, SaaS platforms, professional tools","Creative portfolios, entertainment, playful brands, artistic experiments",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,◐ Medium,"Tailwind 10/10, Bootstrap 9/10, MUI 9/10",1950s Swiss,Low,"Design a minimalist landing page. Use: white space, geometric layouts, sans-serif fonts, high contrast, grid-based structure, essential elements only. Avoid shadows and gradients. Focus on clarity and functionality.","display: grid, gap: 2rem, font-family: sans-serif, color: #000 or #FFF, max-width: 1200px, clean borders, no box-shadow unless necessary","☐ Grid-based layout 12-16 columns, ☐ Typography hierarchy clear, ☐ No unnecessary decorations, ☐ WCAG AAA contrast verified, ☐ Mobile responsive grid","--spacing: 2rem, --border-radius: 0px, --font-weight: 400-700, --shadow: none, --accent-color: single primary only"
|
||||
2,Neumorphism,General,"Soft UI, embossed, debossed, convex, concave, light source, subtle depth, rounded (12-16px), monochromatic","Light pastels: Soft Blue #C8E0F4, Soft Pink #F5E0E8, Soft Grey #E8E8E8","Tints/shades (±30%), gradient subtlety, color harmony","Soft box-shadow (multiple: -5px -5px 15px, 5px 5px 15px), smooth press (150ms), inner subtle shadow","Health/wellness apps, meditation platforms, fitness trackers, minimal interaction UIs","Complex apps, critical accessibility, data-heavy dashboards, high-contrast required",✓ Full,◐ Partial,⚡ Good,⚠ Low contrast,✓ Good,◐ Medium,"Tailwind 8/10, CSS-in-JS 9/10",2020s Modern,Medium,"Create a neumorphic UI with soft 3D effects. Use light pastels, rounded corners (12-16px), subtle soft shadows (multiple layers), no hard lines, monochromatic color scheme with light/dark variations. Embossed/debossed effect on interactive elements.","border-radius: 12-16px, box-shadow: -5px -5px 15px rgba(0,0,0,0.1), 5px 5px 15px rgba(255,255,255,0.8), background: linear-gradient(145deg, color1, color2), transform: scale on press","☐ Rounded corners 12-16px consistent, ☐ Multiple shadow layers (2-3), ☐ Pastel color verified, ☐ Monochromatic palette checked, ☐ Press animation smooth 150ms","--border-radius: 14px, --shadow-soft-1: -5px -5px 15px, --shadow-soft-2: 5px 5px 15px, --color-light: #F5F5F5, --color-primary: single pastel"
|
||||
3,Glassmorphism,General,"Frosted glass, transparent, blurred background, layered, vibrant background, light source, depth, multi-layer","Translucent white: rgba(255,255,255,0.1-0.3)","Vibrant: Electric Blue #0080FF, Neon Purple #8B00FF, Vivid Pink #FF1493, Teal #20B2AA","Backdrop blur (10-20px), subtle border (1px solid rgba white 0.2), light reflection, Z-depth","Modern SaaS, financial dashboards, high-end corporate, lifestyle apps, modal overlays, navigation","Low-contrast backgrounds, critical accessibility, performance-limited, dark text on dark",✓ Full,✓ Full,⚠ Good,⚠ Ensure 4.5:1,✓ Good,✓ High,"Tailwind 9/10, MUI 8/10, Chakra 8/10",2020s Modern,Medium,"Design a glassmorphic interface with frosted glass effect. Use backdrop blur (10-20px), translucent overlays (rgba 10-30% opacity), vibrant background colors, subtle borders, light source reflection, layered depth. Perfect for modern overlays and cards.","backdrop-filter: blur(15px), background: rgba(255, 255, 255, 0.15), border: 1px solid rgba(255,255,255,0.2), -webkit-backdrop-filter: blur(15px), z-index layering for depth","☐ Backdrop-filter blur 10-20px, ☐ Translucent white 15-30% opacity, ☐ Subtle border 1px light, ☐ Vibrant background verified, ☐ Text contrast 4.5:1 checked","--blur-amount: 15px, --glass-opacity: 0.15, --border-color: rgba(255,255,255,0.2), --background: vibrant color, --text-color: light/dark based on BG"
|
||||
4,Brutalism,General,"Raw, unpolished, stark, high contrast, plain text, default fonts, visible borders, asymmetric, anti-design","Primary: Red #FF0000, Blue #0000FF, Yellow #FFFF00, Black #000000, White #FFFFFF","Limited: Neon Green #00FF00, Hot Pink #FF00FF, minimal secondary","No smooth transitions (instant), sharp corners (0px), bold typography (700+), visible grid, large blocks","Design portfolios, artistic projects, counter-culture brands, editorial/media sites, tech blogs","Corporate environments, conservative industries, critical accessibility, customer-facing professional",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,◐ Medium,✗ Low,"Tailwind 10/10, Bootstrap 7/10",1950s Brutalist,Low,"Create a brutalist design with raw, unpolished, stark aesthetic. Use pure primary colors (red, blue, yellow), black & white, no smooth transitions (instant), sharp corners, bold large typography, visible grid lines, default system fonts, intentional 'broken' design elements.","border-radius: 0px, transition: none or 0s, font-family: system-ui or monospace, font-weight: 700+, border: visible 2-4px, colors: #FF0000, #0000FF, #FFFF00, #000000, #FFFFFF","☐ No border-radius (0px), ☐ No transitions (instant), ☐ Bold typography (700+), ☐ Pure primary colors used, ☐ Visible grid/borders, ☐ Asymmetric layout intentional","--border-radius: 0px, --transition-duration: 0s, --font-weight: 700-900, --colors: primary only, --border-style: visible, --grid-visible: true"
|
||||
5,3D & Hyperrealism,General,"Depth, realistic textures, 3D models, spatial navigation, tactile, skeuomorphic elements, rich detail, immersive","Deep Navy #001F3F, Forest Green #228B22, Burgundy #800020, Gold #FFD700, Silver #C0C0C0","Complex gradients (5-10 stops), realistic lighting, shadow variations (20-40% darker)","WebGL/Three.js 3D, realistic shadows (layers), physics lighting, parallax (3-5 layers), smooth 3D (300-400ms)","Gaming, product showcase, immersive experiences, high-end e-commerce, architectural viz, VR/AR","Low-end mobile, performance-limited, critical accessibility, data tables/forms",◐ Partial,◐ Partial,❌ Poor,⚠ Not accessible,✗ Low,◐ Medium,"Three.js 10/10, R3F 10/10, Babylon.js 10/10",2020s Modern,High,"Build an immersive 3D interface using realistic textures, 3D models (Three.js/Babylon.js), complex shadows, realistic lighting, parallax scrolling (3-5 layers), physics-based motion. Include skeuomorphic elements with tactile detail.","transform: translate3d, perspective: 1000px, WebGL canvas, Three.js/Babylon.js library, box-shadow: complex multi-layer, background: complex gradients, filter: drop-shadow()","☐ WebGL/Three.js integrated, ☐ 3D models loaded, ☐ Parallax 3-5 layers, ☐ Realistic lighting verified, ☐ Complex shadows rendered, ☐ Physics animation smooth 300-400ms","--perspective: 1000px, --parallax-layers: 5, --lighting-intensity: realistic, --shadow-depth: 20-40%, --animation-duration: 300-400ms"
|
||||
6,Vibrant & Block-based,General,"Bold, energetic, playful, block layout, geometric shapes, high color contrast, duotone, modern, energetic","Neon Green #39FF14, Electric Purple #BF00FF, Vivid Pink #FF1493, Bright Cyan #00FFFF, Sunburst #FFAA00","Complementary: Orange #FF7F00, Shocking Pink #FF006E, Lime #CCFF00, triadic schemes","Large sections (48px+ gaps), animated patterns, bold hover (color shift), scroll-snap, large type (32px+), 200-300ms","Startups, creative agencies, gaming, social media, youth-focused, entertainment, consumer","Financial institutions, healthcare, formal business, government, conservative, elderly",✓ Full,✓ Full,⚡ Good,◐ Ensure WCAG,✓ High,✓ High,"Tailwind 10/10, Chakra 9/10, Styled 9/10",2020s Modern,Medium,"Design an energetic, vibrant interface with bold block layouts, geometric shapes, high color contrast, large typography (32px+), animated background patterns, duotone effects. Perfect for startups and youth-focused apps. Use 4-6 contrasting colors from complementary/triadic schemes.","display: flex/grid with large gaps (48px+), font-size: 32px+, background: animated patterns (CSS), color: neon/vibrant colors, animation: continuous pattern movement","☐ Block layout with 48px+ gaps, ☐ Large typography 32px+, ☐ 4-6 vibrant colors max, ☐ Animated patterns active, ☐ Scroll-snap enabled, ☐ High contrast verified (7:1+)","--block-gap: 48px, --typography-size: 32px+, --color-palette: 4-6 vibrant colors, --animation: continuous pattern, --contrast-ratio: 7:1+"
|
||||
7,Dark Mode (OLED),General,"Dark theme, low light, high contrast, deep black, midnight blue, eye-friendly, OLED, night mode, power efficient","Deep Black #000000, Dark Grey #121212, Midnight Blue #0A0E27","Vibrant accents: Neon Green #39FF14, Electric Blue #0080FF, Gold #FFD700, Plasma Purple #BF00FF","Minimal glow (text-shadow: 0 0 10px), dark-to-light transitions, low white emission, high readability, visible focus","Night-mode apps, coding platforms, entertainment, eye-strain prevention, OLED devices, low-light","Print-first content, high-brightness outdoor, color-accuracy-critical",✗ No,✓ Only,⚡ Excellent,✓ WCAG AAA,✓ High,◐ Low,"Tailwind 10/10, MUI 10/10, Chakra 10/10",2020s Modern,Low,"Create an OLED-optimized dark interface with deep black (#000000), dark grey (#121212), midnight blue accents. Use minimal glow effects, vibrant neon accents (green, blue, gold, purple), high contrast text. Optimize for eye comfort and OLED power saving.","background: #000000 or #121212, color: #FFFFFF or #E0E0E0, text-shadow: 0 0 10px neon-color (sparingly), filter: brightness(0.8) if needed, color-scheme: dark","☐ Deep black #000000 or #121212, ☐ Vibrant neon accents used, ☐ Text contrast 7:1+, ☐ Minimal glow effects, ☐ OLED power optimization, ☐ No white (#FFFFFF) background","--bg-black: #000000, --bg-dark-grey: #121212, --text-primary: #FFFFFF, --accent-neon: neon colors, --glow-effect: minimal, --oled-optimized: true"
|
||||
8,Accessible & Ethical,General,"High contrast, large text (16px+), keyboard navigation, screen reader friendly, WCAG compliant, focus state, semantic","WCAG AA/AAA (4.5:1 min), simple primary, clear secondary, high luminosity (7:1+)","Symbol-based colors (not color-only), supporting patterns, inclusive combinations","Clear focus rings (3-4px), ARIA labels, skip links, responsive design, reduced motion, 44x44px touch targets","Government, healthcare, education, inclusive products, large audience, legal compliance, public",None - accessibility universal,✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ High,All frameworks 10/10,Universal,Low,"Design with WCAG AAA compliance. Include: high contrast (7:1+), large text (16px+), keyboard navigation, screen reader compatibility, focus states visible (3-4px ring), semantic HTML, ARIA labels, skip links, reduced motion support (prefers-reduced-motion), 44x44px touch targets.","color-contrast: 7:1+, font-size: 16px+, outline: 3-4px on :focus-visible, aria-label, role attributes, @media (prefers-reduced-motion), touch-target: 44x44px, cursor: pointer","☐ WCAG AAA verified, ☐ 7:1+ contrast checked, ☐ Keyboard navigation tested, ☐ Screen reader tested, ☐ Focus visible 3-4px, ☐ Semantic HTML used, ☐ Touch targets 44x44px","--contrast-ratio: 7:1, --font-size-min: 16px, --focus-ring: 3-4px, --touch-target: 44x44px, --wcag-level: AAA, --keyboard-accessible: true, --sr-tested: true"
|
||||
9,Claymorphism,General,"Soft 3D, chunky, playful, toy-like, bubbly, thick borders (3-4px), double shadows, rounded (16-24px)","Pastel: Soft Peach #FDBCB4, Baby Blue #ADD8E6, Mint #98FF98, Lilac #E6E6FA, light BG","Soft gradients (pastel-to-pastel), light/dark variations (20-30%), gradient subtle","Inner+outer shadows (subtle, no hard lines), soft press (200ms ease-out), fluffy elements, smooth transitions","Educational apps, children's apps, SaaS platforms, creative tools, fun-focused, onboarding, casual games","Formal corporate, professional services, data-critical, serious/medical, legal apps, finance",✓ Full,◐ Partial,⚡ Good,⚠ Ensure 4.5:1,✓ High,✓ High,"Tailwind 9/10, CSS-in-JS 9/10",2020s Modern,Medium,"Design a playful, toy-like interface with soft 3D, chunky elements, bubbly aesthetic, rounded edges (16-24px), thick borders (3-4px), double shadows (inner + outer), pastel colors, smooth animations. Perfect for children's apps and creative tools.","border-radius: 16-24px, border: 3-4px solid, box-shadow: inset -2px -2px 8px, 4px 4px 8px, background: pastel-gradient, animation: soft bounce (cubic-bezier 0.34, 1.56)","☐ Border-radius 16-24px, ☐ Thick borders 3-4px, ☐ Double shadows (inner+outer), ☐ Pastel colors used, ☐ Soft bounce animations, ☐ Playful interactions","--border-radius: 20px, --border-width: 3-4px, --shadow-inner: inset -2px -2px 8px, --shadow-outer: 4px 4px 8px, --color-palette: pastels, --animation: bounce"
|
||||
10,Aurora UI,General,"Vibrant gradients, smooth blend, Northern Lights effect, mesh gradient, luminous, atmospheric, abstract","Complementary: Blue-Orange, Purple-Yellow, Electric Blue #0080FF, Magenta #FF1493, Cyan #00FFFF","Smooth transitions (Blue→Purple→Pink→Teal), iridescent effects, blend modes (screen, multiply)","Large flowing CSS/SVG gradients, subtle 8-12s animations, depth via color layering, smooth morph","Modern SaaS, creative agencies, branding, music platforms, lifestyle, premium products, hero sections","Data-heavy dashboards, critical accessibility, content-heavy where distraction issues",✓ Full,✓ Full,⚠ Good,⚠ Text contrast,✓ Good,✓ High,"Tailwind 9/10, CSS-in-JS 10/10",2020s Modern,Medium,"Create a vibrant gradient interface inspired by Northern Lights with mesh gradients, smooth color blends, flowing animations. Use complementary color pairs (blue-orange, purple-yellow), flowing background gradients, subtle continuous animations (8-12s loops), iridescent effects.","background: conic-gradient or radial-gradient with multiple stops, animation: @keyframes gradient (8-12s), background-size: 200% 200%, filter: saturate(1.2), blend-mode: screen or multiply","☐ Mesh/flowing gradients applied, ☐ 8-12s animation loop, ☐ Complementary colors used, ☐ Smooth color transitions, ☐ Iridescent effect subtle, ☐ Text contrast verified","--gradient-colors: complementary pairs, --animation-duration: 8-12s, --blend-mode: screen, --color-saturation: 1.2, --effect: iridescent, --loop-smooth: true"
|
||||
11,Retro-Futurism,General,"Vintage sci-fi, 80s aesthetic, neon glow, geometric patterns, CRT scanlines, pixel art, cyberpunk, synthwave","Neon Blue #0080FF, Hot Pink #FF006E, Cyan #00FFFF, Deep Black #1A1A2E, Purple #5D34D0","Metallic Silver #C0C0C0, Gold #FFD700, duotone, 80s Pink #FF10F0, neon accents","CRT scanlines (::before overlay), neon glow (text-shadow+box-shadow), glitch effects (skew/offset keyframes)","Gaming, entertainment, music platforms, tech brands, artistic projects, nostalgic, cyberpunk","Conservative industries, critical accessibility, professional/corporate, elderly, legal/finance",✓ Full,✓ Dark focused,⚠ Moderate,⚠ High contrast/strain,◐ Medium,◐ Medium,"Tailwind 8/10, CSS-in-JS 9/10",1980s Retro,Medium,"Build a retro-futuristic (cyberpunk/vaporwave) interface with neon colors (blue, pink, cyan), deep black background, 80s aesthetic, CRT scanlines, glitch effects, neon glow text/borders, monospace fonts, geometric patterns. Use neon text-shadow and animated glitch effects.","color: neon colors (#0080FF, #FF006E, #00FFFF), text-shadow: 0 0 10px neon, background: #000 or #1A1A2E, font-family: monospace, animation: glitch (skew+offset), filter: hue-rotate","☐ Neon colors used, ☐ CRT scanlines effect, ☐ Glitch animations active, ☐ Monospace font, ☐ Deep black background, ☐ Glow effects applied, ☐ 80s patterns present","--neon-colors: #0080FF #FF006E #00FFFF, --background: #000000, --font-family: monospace, --effect: glitch+glow, --scanline-opacity: 0.3, --crt-effect: true"
|
||||
12,Flat Design,General,"2D, minimalist, bold colors, no shadows, clean lines, simple shapes, typography-focused, modern, icon-heavy","Solid bright: Red, Orange, Blue, Green, limited palette (4-6 max)","Complementary colors, muted secondaries, high saturation, clean accents","No gradients/shadows, simple hover (color/opacity shift), fast loading, clean transitions (150-200ms ease), minimal icons","Web apps, mobile apps, cross-platform, startup MVPs, user-friendly, SaaS, dashboards, corporate","Complex 3D, premium/luxury, artistic portfolios, immersive experiences, high-detail",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ High,"Tailwind 10/10, Bootstrap 10/10, MUI 9/10",2010s Modern,Low,"Create a flat, 2D interface with bold colors, no shadows/gradients, clean lines, simple geometric shapes, icon-heavy, typography-focused, minimal ornamentation. Use 4-6 solid, bright colors in a limited palette with high saturation.","box-shadow: none, background: solid color, border-radius: 0-4px, color: solid (no gradients), fill: solid, stroke: 1-2px, font: bold sans-serif, icons: simplified SVG","☐ No shadows/gradients, ☐ 4-6 solid colors max, ☐ Clean lines consistent, ☐ Simple shapes used, ☐ Icon-heavy layout, ☐ High saturation colors, ☐ Fast loading verified","--shadow: none, --color-palette: 4-6 solid, --border-radius: 2px, --gradient: none, --icons: simplified SVG, --animation: minimal 150-200ms"
|
||||
13,Skeuomorphism,General,"Realistic, texture, depth, 3D appearance, real-world metaphors, shadows, gradients, tactile, detailed, material","Rich realistic: wood, leather, metal colors, detailed gradients (8-12 stops), metallic effects","Realistic lighting gradients, shadow variations (30-50% darker), texture overlays, material colors","Realistic shadows (layers), depth (perspective), texture details (noise, grain), realistic animations (300-500ms)","Legacy apps, gaming, immersive storytelling, premium products, luxury, realistic simulations, education","Modern enterprise, critical accessibility, low-performance, web (use Flat/Modern)",◐ Partial,◐ Partial,❌ Poor,⚠ Textures reduce readability,✗ Low,◐ Medium,"CSS-in-JS 7/10, Custom 8/10",2007-2012 iOS,High,"Design a realistic, textured interface with 3D depth, real-world metaphors (leather, wood, metal), complex gradients (8-12 stops), realistic shadows, grain/texture overlays, tactile press animations. Perfect for premium/luxury products.","background: complex gradient (8-12 stops), box-shadow: realistic multi-layer, background-image: texture overlay (noise, grain), filter: drop-shadow, transform: scale on press (300-500ms)","☐ Realistic textures applied, ☐ Complex gradients 8-12 stops, ☐ Multi-layer shadows, ☐ Texture overlays present, ☐ Tactile animations smooth, ☐ Depth effect pronounced","--gradient-stops: 8-12, --texture-overlay: noise+grain, --shadow-layers: 3+, --animation-duration: 300-500ms, --depth-effect: pronounced, --tactile: true"
|
||||
14,Liquid Glass,General,"Flowing glass, morphing, smooth transitions, fluid effects, translucent, animated blur, iridescent, chromatic aberration","Vibrant iridescent (rainbow spectrum), translucent base with opacity shifts, gradient fluidity","Chromatic aberration (Red-Cyan), iridescent oil-spill, fluid gradient blends, holographic effects","Morphing elements (SVG/CSS), fluid animations (400-600ms curves), dynamic blur (backdrop-filter), color transitions","Premium SaaS, high-end e-commerce, creative platforms, branding experiences, luxury portfolios","Performance-limited, critical accessibility, complex data, budget projects",✓ Full,✓ Full,⚠ Moderate-Poor,⚠ Text contrast,◐ Medium,✓ High,"Framer Motion 10/10, GSAP 10/10",2020s Modern,High,"Create a premium liquid glass effect with morphing shapes, flowing animations, chromatic aberration, iridescent gradients, smooth 400-600ms transitions. Use SVG morphing for shape changes, dynamic blur, smooth color transitions creating a fluid, premium feel.","animation: morphing SVG paths (400-600ms), backdrop-filter: blur + saturate, filter: hue-rotate + brightness, blend-mode: screen, background: iridescent gradient","☐ Morphing animations 400-600ms, ☐ Chromatic aberration applied, ☐ Dynamic blur active, ☐ Iridescent gradients, ☐ Smooth color transitions, ☐ Premium feel achieved","--morph-duration: 400-600ms, --blur-amount: 15px, --chromatic-aberration: true, --iridescent: true, --blend-mode: screen, --smooth-transitions: true"
|
||||
15,Motion-Driven,General,"Animation-heavy, microinteractions, smooth transitions, scroll effects, parallax, entrance anim, page transitions","Bold colors emphasize movement, high contrast animated, dynamic gradients, accent action colors","Transitional states, success (Green #22C55E), error (Red #EF4444), neutral feedback","Scroll anim (Intersection Observer), hover (300-400ms), entrance, parallax (3-5 layers), page transitions","Portfolio sites, storytelling platforms, interactive experiences, entertainment apps, creative, SaaS","Data dashboards, critical accessibility, low-power devices, content-heavy, motion-sensitive",✓ Full,✓ Full,⚠ Good,⚠ Prefers-reduced-motion,✓ Good,✓ High,"GSAP 10/10, Framer Motion 10/10",2020s Modern,High,"Build an animation-heavy interface with scroll-triggered animations, microinteractions, parallax scrolling (3-5 layers), smooth transitions (300-400ms), entrance animations, page transitions. Use Intersection Observer for scroll effects, transform for performance, GPU acceleration.","animation: @keyframes scroll-reveal, transform: translateY/X, Intersection Observer API, will-change: transform, scroll-behavior: smooth, animation-duration: 300-400ms","☐ Scroll animations active, ☐ Parallax 3-5 layers, ☐ Entrance animations smooth, ☐ Page transitions fluid, ☐ GPU accelerated, ☐ Prefers-reduced-motion respected","--animation-duration: 300-400ms, --parallax-layers: 5, --scroll-behavior: smooth, --gpu-accelerated: true, --entrance-animation: true, --page-transition: smooth"
|
||||
16,Micro-interactions,General,"Small animations, gesture-based, tactile feedback, subtle animations, contextual interactions, responsive","Subtle color shifts (10-20%), feedback: Green #22C55E, Red #EF4444, Amber #F59E0B","Accent feedback, neutral supporting, clear action indicators","Small hover (50-100ms), loading spinners, success/error state anim, gesture-triggered (swipe/pinch), haptic","Mobile apps, touchscreen UIs, productivity tools, user-friendly, consumer apps, interactive components","Desktop-only, critical performance, accessibility-first (alternatives needed)",✓ Full,✓ Full,⚡ Excellent,✓ Good,✓ High,✓ High,"Framer Motion 10/10, React Spring 9/10",2020s Modern,Medium,"Design with delightful micro-interactions: small 50-100ms animations, gesture-based responses, tactile feedback, loading spinners, success/error states, subtle hover effects, haptic feedback triggers for mobile. Focus on responsive, contextual interactions.","animation: short 50-100ms, transition: hover states, @media (hover: hover) for desktop, :active for press, haptic-feedback CSS/API, loading animation smooth loop","☐ Micro-animations 50-100ms, ☐ Gesture-responsive, ☐ Tactile feedback visual/haptic, ☐ Loading spinners smooth, ☐ Success/error states clear, ☐ Hover effects subtle","--micro-animation-duration: 50-100ms, --gesture-responsive: true, --haptic-feedback: true, --loading-animation: smooth, --state-feedback: success+error"
|
||||
17,Inclusive Design,General,"Accessible, color-blind friendly, high contrast, haptic feedback, voice interaction, screen reader, WCAG AAA, universal","WCAG AAA (7:1+ contrast), avoid red-green only, symbol-based indicators, high contrast primary","Supporting patterns (stripes, dots, hatch), symbols, combinations, clear non-color indicators","Haptic feedback (vibration), voice guidance, focus indicators (4px+ ring), motion options, alt content, semantic","Public services, education, healthcare, finance, government, accessible consumer, inclusive",None - accessibility universal,✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ High,All frameworks 10/10,Universal,Low,"Design for universal accessibility: high contrast (7:1+), large text (16px+), keyboard-only navigation, screen reader optimization, WCAG AAA compliance, symbol-based color indicators (not color-only), haptic feedback, voice interaction support, reduced motion options.","aria-* attributes complete, role attributes semantic, focus-visible: 3-4px ring, color-contrast: 7:1+, @media (prefers-reduced-motion), alt text on all images, form labels properly associated","☐ WCAG AAA verified, ☐ 7:1+ contrast all text, ☐ Keyboard accessible (Tab/Enter), ☐ Screen reader tested, ☐ Focus visible 3-4px, ☐ No color-only indicators, ☐ Haptic fallback","--contrast-ratio: 7:1, --font-size: 16px+, --keyboard-accessible: true, --sr-compatible: true, --wcag-level: AAA, --color-symbols: true, --haptic: enabled"
|
||||
18,Zero Interface,General,"Minimal visible UI, voice-first, gesture-based, AI-driven, invisible controls, predictive, context-aware, ambient","Neutral backgrounds: Soft white #FAFAFA, light grey #F0F0F0, warm off-white #F5F1E8","Subtle feedback: light green, light red, minimal UI elements, soft accents","Voice recognition UI, gesture detection, AI predictions (smooth reveal), progressive disclosure, smart suggestions","Voice assistants, AI platforms, future-forward UX, smart home, contextual computing, ambient experiences","Complex workflows, data-entry heavy, traditional systems, legacy support, explicit control",✓ Full,✓ Full,⚡ Excellent,✓ Excellent,✓ High,✓ High,"Tailwind 10/10, Custom 10/10",2020s AI-Era,Low,"Create a voice-first, gesture-based, AI-driven interface with minimal visible UI, progressive disclosure, voice recognition UI, gesture detection, AI predictions, smart suggestions, context-aware actions. Hide controls until needed.","voice-commands: Web Speech API, gesture-detection: touch events, AI-predictions: hidden by default (reveal on hover), progressive-disclosure: show on demand, minimal UI visible","☐ Voice commands responsive, ☐ Gesture detection active, ☐ AI predictions hidden/revealed, ☐ Progressive disclosure working, ☐ Minimal visible UI, ☐ Smart suggestions contextual","--voice-ui: enabled, --gesture-detection: active, --ai-predictions: smart, --progressive-disclosure: true, --visible-ui: minimal, --context-aware: true"
|
||||
19,Soft UI Evolution,General,"Evolved soft UI, better contrast, modern aesthetics, subtle depth, accessibility-focused, improved shadows, hybrid","Improved contrast pastels: Soft Blue #87CEEB, Soft Pink #FFB6C1, Soft Green #90EE90, better hierarchy","Better combinations, accessible secondary, supporting with improved contrast, modern accents","Improved shadows (softer than flat, clearer than neumorphism), modern (200-300ms), focus visible, WCAG AA/AAA","Modern enterprise apps, SaaS platforms, health/wellness, modern business tools, professional, hybrid","Extreme minimalism, critical performance, systems without modern OS",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA+,✓ High,✓ High,"Tailwind 9/10, MUI 9/10, Chakra 9/10",2020s Modern,Medium,"Design evolved neumorphism with improved contrast (WCAG AA+), modern aesthetics, subtle depth, accessibility focus. Use soft shadows (softer than flat but clearer than pure neumorphism), better color hierarchy, improved focus states, modern 200-300ms animations.","box-shadow: softer multi-layer (0 2px 4px), background: improved contrast pastels, border-radius: 8-12px, animation: 200-300ms smooth, outline: 2-3px on focus, contrast: 4.5:1+","☐ Improved contrast AA/AAA, ☐ Soft shadows modern, ☐ Border-radius 8-12px, ☐ Animations 200-300ms, ☐ Focus states visible, ☐ Color hierarchy clear","--shadow-soft: modern blend, --border-radius: 10px, --animation-duration: 200-300ms, --contrast-ratio: 4.5:1+, --color-hierarchy: improved, --wcag-level: AA+"
|
||||
20,Hero-Centric Design,Landing Page,"Large hero section, compelling headline, high-contrast CTA, product showcase, value proposition, hero image/video, dramatic visual","Brand primary color, white/light backgrounds for contrast, accent color for CTA","Supporting colors for secondary CTAs, accent highlights, trust elements (testimonials, logos)","Smooth scroll reveal, fade-in animations on hero, subtle background parallax, CTA glow/pulse effect","SaaS landing pages, product launches, service landing pages, B2B platforms, tech companies","Complex navigation, multi-page experiences, data-heavy applications",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,✓ Full,✓ Very High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a hero-centric landing page. Use: full-width hero section, compelling headline (60-80 chars), high-contrast CTA button, product screenshot or video, value proposition above fold, gradient or image background, clear visual hierarchy.","min-height: 100vh, display: flex, align-items: center, background: linear-gradient or image, text-shadow for readability, max-width: 800px for text, button with hover scale (1.05)","☐ Hero section full viewport height, ☐ Headline visible above fold, ☐ CTA button high contrast, ☐ Background image optimized (WebP), ☐ Text readable on background, ☐ Mobile responsive layout","--hero-min-height: 100vh, --headline-size: clamp(2rem, 5vw, 4rem), --cta-padding: 1rem 2rem, --overlay-opacity: 0.5, --text-shadow: 0 2px 4px rgba(0,0,0,0.3)"
|
||||
21,Conversion-Optimized,Landing Page,"Form-focused, minimalist design, single CTA focus, high contrast, urgency elements, trust signals, social proof, clear value","Primary brand color, high-contrast white/light backgrounds, warning/urgency colors for time-limited offers","Secondary CTA color (muted), trust element colors (testimonial highlights), accent for key benefits","Hover states on CTA (color shift, slight scale), form field focus animations, loading spinner, success feedback","E-commerce product pages, free trial signups, lead generation, SaaS pricing pages, limited-time offers","Complex feature explanations, multi-product showcases, technical documentation",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ Full (mobile-optimized),✓ Very High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a conversion-optimized landing page. Use: single primary CTA, minimal distractions, trust badges, urgency elements (limited time), social proof (testimonials), clear value proposition, form above fold, progress indicators.","form with focus states, input:focus ring, button: primary color high contrast, position: sticky for CTA, max-width: 600px for form, loading spinner, success/error states","☐ Single primary CTA visible, ☐ Form fields minimal (3-5), ☐ Trust badges present, ☐ Social proof above fold, ☐ Mobile form optimized, ☐ Loading states implemented, ☐ A/B test ready","--cta-color: high contrast primary, --form-max-width: 600px, --input-height: 48px, --focus-ring: 3px solid accent, --success-color: #22C55E, --error-color: #EF4444"
|
||||
22,Feature-Rich Showcase,Landing Page,"Multiple feature sections, grid layout, benefit cards, visual feature demonstrations, interactive elements, problem-solution pairs","Primary brand, bright secondary colors for feature cards, contrasting accent for CTAs","Supporting colors for: benefits (green), problems (red/orange), features (blue/purple), social proof (neutral)","Card hover effects (lift/scale), icon animations on scroll, feature toggle animations, smooth section transitions","Enterprise SaaS, software tools landing pages, platform services, complex product explanations, B2B products","Simple product pages, early-stage startups with few features, entertainment landing pages",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,✓ Good,✓ High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a feature showcase landing page. Use: grid layout for features (3-4 columns), feature cards with icons, benefit-focused copy, alternating sections, comparison tables, interactive demos, problem-solution pairs.","display: grid, grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)), gap: 2rem, card hover effects (translateY -4px), icon containers, alternating background colors","☐ Feature grid responsive, ☐ Icons consistent style, ☐ Card hover effects smooth, ☐ Alternating sections contrast, ☐ Benefits clearly stated, ☐ Mobile stacks properly","--card-padding: 2rem, --card-radius: 12px, --icon-size: 48px, --grid-gap: 2rem, --section-padding: 4rem 0, --hover-transform: translateY(-4px)"
|
||||
23,Minimal & Direct,Landing Page,"Minimal text, white space heavy, single column layout, direct messaging, clean typography, visual-centric, fast-loading","Monochromatic primary, white background, single accent color for CTA, black/dark grey text","Minimal secondary colors, reserved for critical CTAs only, neutral supporting elements","Very subtle hover effects, minimal animations, fast page load (no heavy animations), smooth scroll","Simple service landing pages, indie products, consulting services, micro SaaS, freelancer portfolios","Feature-heavy products, complex explanations, multi-product showcases",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ Full,✓ High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a minimal direct landing page. Use: single column layout, maximum white space, essential content only, one CTA, clean typography, no decorative elements, fast loading, direct messaging.","max-width: 680px, margin: 0 auto, padding: 4rem 2rem, font-size: 18-20px, line-height: 1.6, minimal animations, no box-shadow, clean borders only","☐ Single column centered, ☐ White space generous, ☐ One primary CTA only, ☐ No decorative images, ☐ Page weight < 500KB, ☐ Load time < 2s","--content-max-width: 680px, --spacing-large: 4rem, --font-size-body: 18px, --line-height: 1.6, --color-text: #1a1a1a, --color-bg: #ffffff"
|
||||
24,Social Proof-Focused,Landing Page,"Testimonials prominent, client logos displayed, case studies sections, reviews/ratings, user avatars, success metrics, credibility markers","Primary brand, trust colors (blue), success/growth colors (green), neutral backgrounds","Testimonial highlight colors, logo grid backgrounds (light grey), badge/achievement colors","Testimonial carousel animations, logo grid fade-in, stat counter animations (number count-up), review star ratings","B2B SaaS, professional services, premium products, e-commerce conversion pages, established brands","Startup MVPs, products without users, niche/experimental products",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,✓ Full,✓ High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a social proof landing page. Use: testimonials with photos, client logos grid, case study cards, review ratings (stars), user count metrics, success stories, trust indicators, before/after comparisons.","testimonial cards with avatar, logo grid (grayscale filter), star rating SVGs, counter animations (count-up), blockquote styling, carousel for testimonials, metric cards","☐ Testimonials with real photos, ☐ Logo grid 6-12 logos, ☐ Star ratings accessible, ☐ Metrics animated on scroll, ☐ Case studies linked, ☐ Mobile carousel works","--avatar-size: 64px, --logo-height: 40px, --star-color: #FBBF24, --metric-font-size: 3rem, --testimonial-bg: #F9FAFB, --blockquote-border: 4px solid accent"
|
||||
25,Interactive Product Demo,Landing Page,"Embedded product mockup/video, interactive elements, product walkthrough, step-by-step guides, hover-to-reveal features, embedded demos","Primary brand, interface colors matching product, demo highlight colors for interactive elements","Product UI colors, tutorial step colors (numbered progression), hover state indicators","Product animation playback, step progression animations, hover reveal effects, smooth zoom on interaction","SaaS platforms, tool/software products, productivity apps landing pages, developer tools, productivity software","Simple services, consulting, non-digital products, complexity-averse audiences",✓ Full,✓ Full,⚠ Good (video/interactive),✓ WCAG AA,✓ Good,✓ Very High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design an interactive demo landing page. Use: embedded product mockup, video walkthrough, step-by-step guide, hover-to-reveal features, live demo button, screenshot carousel, feature highlights on interaction.","video element with controls, position: relative for overlays, hover reveal (opacity transition), step indicators, modal for full demo, screenshot lightbox, play button overlay","☐ Demo video loads fast, ☐ Fallback for no-JS, ☐ Step indicators clear, ☐ Hover states obvious, ☐ Mobile touch friendly, ☐ Demo CTA prominent","--video-aspect-ratio: 16/9, --overlay-bg: rgba(0,0,0,0.7), --step-indicator-size: 32px, --play-button-size: 80px, --transition-duration: 300ms"
|
||||
26,Trust & Authority,Landing Page,"Certificates/badges displayed, expert credentials, case studies with metrics, before/after comparisons, industry recognition, security badges","Professional colors (blue/grey), trust colors, certification badge colors (gold/silver accents)","Certificate highlight colors, metric showcase colors, comparison highlight (success green)","Badge hover effects, metric pulse animations, certificate carousel, smooth stat reveal","Healthcare/medical landing pages, financial services, enterprise software, premium/luxury products, legal services","Casual products, entertainment, viral/social-first products",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ Full,✓ High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a trust-focused landing page. Use: certification badges, security indicators, expert credentials, industry awards, case study metrics, compliance logos (GDPR, SOC2), guarantee badges, professional photography.","badge grid layout, shield icons, lock icons for security, certificate styling, metric cards with icons, professional color scheme (blue/grey), subtle shadows for depth","☐ Security badges visible, ☐ Certifications verified, ☐ Metrics with sources, ☐ Professional imagery, ☐ Guarantee clearly stated, ☐ Contact info accessible","--badge-height: 48px, --trust-color: #1E40AF, --security-green: #059669, --card-shadow: 0 4px 6px rgba(0,0,0,0.1), --metric-highlight: #F59E0B"
|
||||
27,Storytelling-Driven,Landing Page,"Narrative flow, visual story progression, section transitions, consistent character/brand voice, emotional messaging, journey visualization","Brand primary, warm/emotional colors, varied accent colors per story section, high visual variety","Story section color coding, emotional state colors (calm, excitement, success), transitional gradients","Section-to-section animations, scroll-triggered reveals, character/icon animations, morphing transitions, parallax narrative","Brand/startup stories, mission-driven products, premium/lifestyle brands, documentary-style products, educational","Technical/complex products (unless narrative-driven), traditional enterprise software",✓ Full,✓ Full,⚠ Moderate (animations),✓ WCAG AA,✓ Good,✓ High,"Tailwind 10/10, Bootstrap 9/10",2020s Modern,Medium,"Design a storytelling landing page. Use: narrative flow sections, scroll-triggered reveals, chapter-like structure, emotional imagery, brand journey visualization, founder story, mission statement, timeline progression.","scroll-snap sections, Intersection Observer for reveals, parallax backgrounds, section transitions, timeline CSS, narrative typography (varied sizes), image-text alternating","☐ Story flows naturally, ☐ Scroll reveals smooth, ☐ Sections timed well, ☐ Emotional hooks present, ☐ Mobile story readable, ☐ Skip option available","--section-min-height: 100vh, --reveal-duration: 600ms, --narrative-font: serif, --chapter-spacing: 8rem, --timeline-color: accent, --parallax-speed: 0.5"
|
||||
28,Data-Dense Dashboard,BI/Analytics,"Multiple charts/widgets, data tables, KPI cards, minimal padding, grid layout, space-efficient, maximum data visibility","Neutral primary (light grey/white #F5F5F5), data colors (blue/green/red), dark text #333333","Chart colors: success (green #22C55E), warning (amber #F59E0B), alert (red #EF4444), neutral (grey)","Hover tooltips, chart zoom on click, row highlighting on hover, smooth filter animations, data loading spinners","Business intelligence dashboards, financial analytics, enterprise reporting, operational dashboards, data warehousing","Marketing dashboards, consumer-facing analytics, simple reporting",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a data-dense dashboard. Use: multiple chart widgets, KPI cards row, data tables with sorting, minimal padding (8-12px), efficient grid layout, filter sidebar, dense but readable typography, maximum information density.","display: grid, grid-template-columns: repeat(12, 1fr), gap: 8px, padding: 12px, font-size: 12-14px, overflow: auto for tables, compact card design, sticky headers","☐ Grid layout 12 columns, ☐ KPI cards responsive, ☐ Tables sortable, ☐ Filters functional, ☐ Loading states for data, ☐ Export functionality","--grid-gap: 8px, --card-padding: 12px, --font-size-small: 12px, --table-row-height: 36px, --sidebar-width: 240px, --header-height: 56px"
|
||||
29,Heat Map & Heatmap Style,BI/Analytics,"Color-coded grid/matrix, data intensity visualization, geographical heat maps, correlation matrices, cell-based representation, gradient coloring","Gradient scale: Cool (blue #0080FF) to hot (red #FF0000), neutral middle (white/yellow)","Support gradients: Light (cool blue) to dark (warm red), divergent for positive/negative data, monochromatic options","Color gradient transitions on data change, cell highlighting on hover, tooltip reveal on click, smooth color animation","Geographical analysis, performance matrices, correlation analysis, user behavior heatmaps, temperature/intensity data","Linear data representation, categorical comparisons (use bar charts), small datasets",✓ Full,✓ Full (with adjustments),⚡ Excellent,⚠ Colorblind considerations,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a heatmap visualization. Use: color gradient scale (cool to hot), cell-based grid, intensity legend, hover tooltips, geographic or matrix layout, divergent color scheme for +/- values, accessible color alternatives.","display: grid, background: linear-gradient for legend, cell hover states, tooltip positioning, color scale (blue→white→red), SVG for geographic, canvas for large datasets","☐ Color scale clear, ☐ Legend visible, ☐ Tooltips informative, ☐ Colorblind alternatives, ☐ Zoom/pan for geo, ☐ Performance for large data","--heatmap-cool: #0080FF, --heatmap-neutral: #FFFFFF, --heatmap-hot: #FF0000, --cell-size: 24px, --legend-width: 200px, --tooltip-bg: rgba(0,0,0,0.9)"
|
||||
30,Executive Dashboard,BI/Analytics,"High-level KPIs, large key metrics, minimal detail, summary view, trend indicators, at-a-glance insights, executive summary","Brand colors, professional palette (blue/grey/white), accent for KPIs, red for alerts/concerns","KPI highlight colors: positive (green), negative (red), neutral (grey), trend arrow colors","KPI value animations (count-up), trend arrow direction animations, metric card hover lift, alert pulse effect","C-suite dashboards, business summary reports, decision-maker dashboards, strategic planning views","Detailed analyst dashboards, technical deep-dives, operational monitoring",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✗ Low (not mobile-optimized),✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design an executive dashboard. Use: large KPI cards (4-6 max), trend sparklines, high-level summary only, clean layout with white space, traffic light indicators (red/yellow/green), at-a-glance insights, minimal detail.","display: flex for KPI row, large font-size (24-48px) for metrics, sparkline SVG inline, status indicators (border-left color), card shadows for hierarchy, responsive breakpoints","☐ KPIs 4-6 maximum, ☐ Trends visible, ☐ Status colors clear, ☐ One-page view, ☐ Mobile simplified, ☐ Print-friendly layout","--kpi-font-size: 48px, --sparkline-height: 32px, --status-green: #22C55E, --status-yellow: #F59E0B, --status-red: #EF4444, --card-min-width: 280px"
|
||||
31,Real-Time Monitoring,BI/Analytics,"Live data updates, status indicators, alert notifications, streaming data visualization, active monitoring, streaming charts","Alert colors: critical (red #FF0000), warning (orange #FFA500), normal (green #22C55E), updating (blue animation)","Status indicator colors, chart line colors varying by metric, streaming data highlight colors","Real-time chart animations, alert pulse/glow, status indicator blink animation, smooth data stream updates, loading effect","System monitoring dashboards, DevOps dashboards, real-time analytics, stock market dashboards, live event tracking","Historical analysis, long-term trend reports, archived data dashboards",✓ Full,✓ Full,⚡ Good (real-time load),✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a real-time monitoring dashboard. Use: live status indicators (pulsing), streaming charts, alert notifications, connection status, auto-refresh indicators, critical alerts prominent, system health overview.","animation: pulse for live, WebSocket for streaming, position: fixed for alerts, status-dot with animation, chart real-time updates, notification toast, connection indicator","☐ Live updates working, ☐ Alert sounds optional, ☐ Connection status shown, ☐ Auto-refresh indicated, ☐ Critical alerts prominent, ☐ Offline fallback","--pulse-animation: pulse 2s infinite, --alert-z-index: 1000, --live-indicator: #22C55E, --critical-color: #DC2626, --update-interval: 5s, --toast-duration: 5s"
|
||||
32,Drill-Down Analytics,BI/Analytics,"Hierarchical data exploration, expandable sections, interactive drill-down paths, summary-to-detail flow, context preservation","Primary brand, breadcrumb colors, drill-level indicator colors, hierarchy depth colors","Drill-down path indicator colors, level-specific colors, highlight colors for selected level, transition colors","Drill-down expand animations, breadcrumb click transitions, smooth detail reveal, level change smooth, data reload animation","Sales analytics, product analytics, funnel analysis, multi-dimensional data exploration, business intelligence","Simple linear data, single-metric dashboards, streaming real-time dashboards",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a drill-down analytics dashboard. Use: breadcrumb navigation, expandable sections, summary-to-detail flow, back button prominent, level indicators, context preservation, hierarchical data display.","breadcrumb nav with separators, details/summary for expand, transition for drill animation, position: sticky breadcrumb, nested grid layouts, smooth scroll to detail","☐ Breadcrumbs clear, ☐ Back navigation easy, ☐ Expand animation smooth, ☐ Context preserved, ☐ Mobile drill works, ☐ Deep links supported","--breadcrumb-separator: /, --expand-duration: 300ms, --level-indent: 24px, --back-button-size: 40px, --context-bar-height: 48px, --drill-transition: 300ms ease"
|
||||
33,Comparative Analysis Dashboard,BI/Analytics,"Side-by-side comparisons, period-over-period metrics, A/B test results, regional comparisons, performance benchmarks","Comparison colors: primary (blue), comparison (orange/purple), delta indicator (green/red)","Winning metric color (green), losing metric color (red), neutral comparison (grey), benchmark colors","Comparison bar animations (grow to value), delta indicator animations (direction arrows), highlight on compare","Period-over-period reporting, A/B test dashboards, market comparison, competitive analysis, regional performance","Single metric dashboards, future projections (use forecasting), real-time only (no historical)",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a comparison dashboard. Use: side-by-side metrics, period selectors (vs last month), delta indicators (+/-), benchmark lines, A/B comparison tables, winning/losing highlights, percentage change badges.","display: flex for side-by-side, gap for comparison spacing, color coding (green up, red down), arrow indicators, diff highlighting, comparison table zebra striping","☐ Period selector works, ☐ Deltas calculated, ☐ Colors meaningful, ☐ Benchmarks shown, ☐ Mobile stacks properly, ☐ Export comparison","--positive-color: #22C55E, --negative-color: #EF4444, --neutral-color: #6B7280, --comparison-gap: 2rem, --arrow-size: 16px, --badge-padding: 4px 8px"
|
||||
34,Predictive Analytics,BI/Analytics,"Forecast lines, confidence intervals, trend projections, scenario modeling, AI-driven insights, anomaly detection visualization","Forecast line color (distinct from actual), confidence interval shading, anomaly highlight (red alert), trend colors","High confidence (dark color), low confidence (light color), anomaly colors (red/orange), normal trend (green/blue)","Forecast line animation on draw, confidence band fade-in, anomaly pulse alert, smoothing function animations","Forecasting dashboards, anomaly detection systems, trend prediction dashboards, AI-powered analytics, budget planning","Historical-only dashboards, simple reporting, real-time operational dashboards",✓ Full,✓ Full,⚠ Good (computation),✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a predictive analytics dashboard. Use: forecast lines (dashed), confidence intervals (shaded bands), trend projections, anomaly highlights, scenario toggles, AI insight cards, probability indicators.","stroke-dasharray for forecast lines, fill-opacity for confidence bands, anomaly markers (circles), tooltip for predictions, toggle switches for scenarios, gradient for probability","☐ Forecast line distinct, ☐ Confidence bands visible, ☐ Anomalies highlighted, ☐ Scenarios switchable, ☐ Predictions dated, ☐ Accuracy shown","--forecast-dash: 5 5, --confidence-opacity: 0.2, --anomaly-color: #F59E0B, --prediction-color: #8B5CF6, --scenario-toggle-width: 48px, --ai-accent: #6366F1"
|
||||
35,User Behavior Analytics,BI/Analytics,"Funnel visualization, user flow diagrams, conversion tracking, engagement metrics, user journey mapping, cohort analysis","Funnel stage colors: high engagement (green), drop-off (red), conversion (blue), user flow arrows (grey)","Stage completion colors (success), abandonment colors (warning), engagement levels (gradient), cohort colors","Funnel animation (fill-down), flow diagram animations (connection draw), conversion pulse, engagement bar fill","Conversion funnel analysis, user journey tracking, engagement analytics, cohort analysis, retention tracking","Real-time operational metrics, technical system monitoring, financial transactions",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,✓ Good,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a user behavior analytics dashboard. Use: funnel visualization, user flow diagrams (Sankey), conversion metrics, engagement heatmaps, cohort tables, retention curves, session replay indicators.","SVG funnel with gradients, Sankey diagram library, percentage labels, cohort grid cells, retention chart (line/area), click heatmap overlay, session timeline","☐ Funnel stages clear, ☐ Flow diagram readable, ☐ Conversions calculated, ☐ Cohorts comparable, ☐ Retention trends visible, ☐ Privacy compliant","--funnel-width: 100%, --stage-colors: gradient, --flow-opacity: 0.6, --cohort-cell-size: 40px, --retention-line-color: #3B82F6, --engagement-scale: 5 levels"
|
||||
36,Financial Dashboard,BI/Analytics,"Revenue metrics, profit/loss visualization, budget tracking, financial ratios, portfolio performance, cash flow, audit trail","Financial colors: profit (green #22C55E), loss (red #EF4444), neutral (grey), trust (dark blue #003366)","Revenue highlight (green), expenses (red), budget variance (orange/red), balance (grey), accuracy (blue)","Number animations (count-up), trend direction indicators, percentage change animations, profit/loss color transitions","Financial reporting, accounting dashboards, portfolio tracking, budget monitoring, banking analytics","Simple business dashboards, entertainment/social metrics, non-financial data",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✗ Low,✗ Not applicable,"Recharts 9/10, Chart.js 9/10, D3.js 10/10",2020s Modern,Medium,"Design a financial dashboard. Use: revenue/expense charts, profit margins, budget vs actual, cash flow waterfall, financial ratios, audit trail table, currency formatting, period comparisons.","number formatting (Intl.NumberFormat), waterfall chart (positive/negative bars), variance coloring, table with totals row, sparkline for trends, sticky column headers","☐ Currency formatted, ☐ Decimals consistent, ☐ P&L clear, ☐ Budget variance shown, ☐ Audit trail complete, ☐ Export to Excel","--currency-symbol: $, --decimal-places: 2, --profit-color: #22C55E, --loss-color: #EF4444, --variance-threshold: 10%, --table-header-bg: #F3F4F6"
|
||||
37,Sales Intelligence Dashboard,BI/Analytics,"Deal pipeline, sales metrics, territory performance, sales rep leaderboard, win-loss analysis, quota tracking, forecast accuracy","Sales colors: won (green), lost (red), in-progress (blue), blocked (orange), quota met (gold), quota missed (grey)","Pipeline stage colors, rep performance colors, quota achievement colors, forecast accuracy colors","Deal movement animations, metric updates, leaderboard ranking changes, gauge needle movements, status change highlights","CRM dashboards, sales management, opportunity tracking, performance management, quota planning","Marketing analytics, customer support metrics, HR dashboards",✓ Full,✓ Full,⚡ Good,✓ WCAG AA,◐ Medium,✗ Not applicable,"Recharts 9/10, Chart.js 9/10",2020s Modern,Medium,"Design a sales intelligence dashboard. Use: pipeline funnel, deal cards (kanban), quota gauges, leaderboard table, territory map, win/loss ratios, forecast accuracy, activity timeline.","kanban columns (flex), gauge chart (SVG arc), leaderboard ranking styles, map integration (Mapbox/Google), timeline vertical, deal card with status border","☐ Pipeline stages shown, ☐ Deals draggable, ☐ Quotas visualized, ☐ Rankings updated, ☐ Territory clickable, ☐ CRM integration","--pipeline-colors: stage gradient, --gauge-track: #E5E7EB, --gauge-fill: primary, --rank-1-color: #FFD700, --rank-2-color: #C0C0C0, --rank-3-color: #CD7F32"
|
||||
38,Neubrutalism,General,"Bold borders, black outlines, primary colors, thick shadows, no gradients, flat colors, 45° shadows, playful, Gen Z","#FFEB3B (Yellow), #FF5252 (Red), #2196F3 (Blue), #000000 (Black borders)","Limited accent colors, high contrast combinations, no gradients allowed","box-shadow: 4px 4px 0 #000, border: 3px solid #000, no gradients, sharp corners (0px), bold typography","Gen Z brands, startups, creative agencies, Figma-style apps, Notion-style interfaces, tech blogs","Luxury brands, finance, healthcare, conservative industries (too playful)",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ High,"Tailwind 10/10, Bootstrap 8/10",2020s Modern,Low,"Design a neubrutalist interface. Use: high contrast, hard black borders (3px+), bright pop colors, no blur, sharp or slightly rounded corners, bold typography, hard shadows (offset 4px 4px), raw aesthetic but functional.","border: 3px solid black, box-shadow: 5px 5px 0px black, colors: #FFDB58 #FF6B6B #4ECDC4, font-weight: 700, no gradients","☐ Hard borders (2-4px), ☐ Hard offset shadows, ☐ High saturation colors, ☐ Bold typography, ☐ No blurs/gradients, ☐ Distinctive 'ugly-cute' look","--border-width: 3px, --shadow-offset: 4px, --shadow-color: #000, --colors: high saturation, --font: bold sans"
|
||||
39,Bento Box Grid,General,"Modular cards, asymmetric grid, varied sizes, Apple-style, dashboard tiles, negative space, clean hierarchy, cards","Neutral base + brand accent, #FFFFFF, #F5F5F5, brand primary","Subtle gradients, shadow variations, accent highlights for interactive cards","grid-template with varied spans, rounded-xl (16px), subtle shadows, hover scale (1.02), smooth transitions","Dashboards, product pages, portfolios, Apple-style marketing, feature showcases, SaaS","Dense data tables, text-heavy content, real-time monitoring",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"Tailwind 10/10, CSS Grid 10/10",2020s Apple,Low,"Design a Bento Box grid layout. Use: modular cards with varied sizes (1x1, 2x1, 2x2), Apple-style aesthetic, rounded corners (16-24px), soft shadows, clean hierarchy, asymmetric grid, neutral backgrounds (#F5F5F7), hover effects.","display: grid, grid-template-columns: repeat(4, 1fr), grid-auto-rows: 200px, gap: 16px, border-radius: 24px, background: #FFFFFF, box-shadow: 0 4px 6px rgba(0,0,0,0.05)","☐ Grid responsive (4→2→1 cols), ☐ Card spans varied, ☐ Rounded corners consistent, ☐ Shadows subtle, ☐ Content fits cards, ☐ Hover scale (1.02)","--grid-gap: 16px, --card-radius: 24px, --card-bg: #FFFFFF, --page-bg: #F5F5F7, --shadow: 0 4px 6px rgba(0,0,0,0.05), --hover-scale: 1.02"
|
||||
40,Y2K Aesthetic,General,"Neon pink, chrome, metallic, bubblegum, iridescent, glossy, retro-futurism, 2000s, futuristic nostalgia","#FF69B4 (Hot Pink), #00FFFF (Cyan), #C0C0C0 (Silver), #9400D3 (Purple)","Metallic gradients, glossy overlays, iridescent effects, chrome textures","linear-gradient metallic, glossy buttons, 3D chrome effects, glow animations, bubble shapes","Fashion brands, music platforms, Gen Z brands, nostalgia marketing, entertainment, youth-focused","B2B enterprise, healthcare, finance, conservative industries, elderly users",✓ Full,◐ Partial,⚠ Good,⚠ Check contrast,✓ Good,✓ High,"Tailwind 8/10, CSS-in-JS 9/10",Y2K 2000s,Medium,"Design a Y2K aesthetic interface. Use: neon pink/cyan colors, chrome/metallic textures, bubblegum gradients, glossy buttons, iridescent effects, 2000s futurism, star/sparkle decorations, bubble shapes, tech-optimistic vibe.","background: linear-gradient(135deg, #FF69B4, #00FFFF), filter: drop-shadow for glow, border-radius: 50% for bubbles, metallic gradients (silver/chrome), text-shadow: neon glow, ::before for sparkles","☐ Neon colors balanced, ☐ Chrome effects visible, ☐ Glossy buttons styled, ☐ Bubble shapes decorative, ☐ Sparkle animations, ☐ Retro fonts loaded","--neon-pink: #FF69B4, --neon-cyan: #00FFFF, --chrome-silver: #C0C0C0, --glossy-gradient: linear-gradient(180deg, white 0%, transparent 50%), --glow-blur: 10px"
|
||||
41,Cyberpunk UI,General,"Neon, dark mode, terminal, HUD, sci-fi, glitch, dystopian, futuristic, matrix, tech noir","#00FF00 (Matrix Green), #FF00FF (Magenta), #00FFFF (Cyan), #0D0D0D (Dark)","Neon gradients, scanline overlays, glitch colors, terminal green accents","Neon glow (text-shadow), glitch animations (skew/offset), scanlines (::before overlay), terminal fonts","Gaming platforms, tech products, crypto apps, sci-fi applications, developer tools, entertainment","Corporate enterprise, healthcare, family apps, conservative brands, elderly users",✗ No,✓ Only,⚠ Moderate,⚠ Limited (dark+neon),◐ Medium,◐ Medium,"Tailwind 8/10, Custom CSS 10/10",2020s Cyberpunk,Medium,"Design a cyberpunk interface. Use: neon colors on dark (#0D0D0D), terminal/HUD aesthetic, glitch effects, scanlines overlay, matrix green accents, monospace fonts, angular shapes, dystopian tech feel.","background: #0D0D0D, color: #00FF00 or #FF00FF, font-family: monospace, text-shadow: 0 0 10px neon, animation: glitch (transform skew), ::before scanlines (repeating-linear-gradient)","☐ Dark background only, ☐ Neon accents visible, ☐ Glitch effect subtle, ☐ Scanlines optional, ☐ Monospace font, ☐ Terminal aesthetic","--bg-dark: #0D0D0D, --neon-green: #00FF00, --neon-magenta: #FF00FF, --neon-cyan: #00FFFF, --scanline-opacity: 0.1, --glitch-duration: 0.3s"
|
||||
42,Organic Biophilic,General,"Nature, organic shapes, green, sustainable, rounded, flowing, wellness, earthy, natural textures","#228B22 (Forest Green), #8B4513 (Earth Brown), #87CEEB (Sky Blue), #F5F5DC (Beige)","Natural gradients, earth tones, sky blues, organic textures, wood/stone colors","Rounded corners (16-24px), organic curves (border-radius variations), natural shadows, flowing SVG shapes","Wellness apps, sustainability brands, eco products, health apps, meditation, organic food brands","Tech-focused products, gaming, industrial, urban brands",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"Tailwind 10/10, CSS 10/10",2020s Sustainable,Low,"Design a biophilic organic interface. Use: nature-inspired colors (greens, browns), organic curved shapes, rounded corners (16-24px), natural textures (wood, stone), flowing SVG elements, wellness aesthetic, earthy palette.","border-radius: 16-24px (varied), background: earth tones, SVG organic shapes (blob), box-shadow: natural soft, color: #228B22 #8B4513 #87CEEB, texture overlays (subtle)","☐ Earth tones dominant, ☐ Organic curves present, ☐ Natural textures subtle, ☐ Green accents, ☐ Rounded everywhere, ☐ Calming feel","--forest-green: #228B22, --earth-brown: #8B4513, --sky-blue: #87CEEB, --cream-bg: #F5F5DC, --organic-radius: 24px, --shadow-soft: 0 8px 32px rgba(0,0,0,0.08)"
|
||||
43,AI-Native UI,General,"Chatbot, conversational, voice, assistant, agentic, ambient, minimal chrome, streaming text, AI interactions","Neutral + single accent, #6366F1 (AI Purple), #10B981 (Success), #F5F5F5 (Background)","Status indicators, streaming highlights, context card colors, subtle accent variations","Typing indicators (3-dot pulse), streaming text animations, pulse animations, context cards, smooth reveals","AI products, chatbots, voice assistants, copilots, AI-powered tools, conversational interfaces","Traditional forms, data-heavy dashboards, print-first content",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"Tailwind 10/10, React 10/10",2020s AI-Era,Low,"Design an AI-native interface. Use: minimal chrome, conversational layout, streaming text area, typing indicators (3-dot pulse), context cards, subtle AI accent color (#6366F1), clean input field, response bubbles.","chat bubble layout (flex-direction: column), typing animation (3 dots pulse), streaming text (overflow: hidden + animation), input: sticky bottom, context cards (border-left accent), minimal borders","☐ Chat layout responsive, ☐ Typing indicator smooth, ☐ Input always visible, ☐ Context cards styled, ☐ AI responses distinct, ☐ User messages aligned right","--ai-accent: #6366F1, --user-bubble-bg: #E0E7FF, --ai-bubble-bg: #F9FAFB, --input-height: 48px, --typing-dot-size: 8px, --message-gap: 16px"
|
||||
44,Memphis Design,General,"80s, geometric, playful, postmodern, shapes, patterns, squiggles, triangles, neon, abstract, bold","#FF71CE (Hot Pink), #FFCE5C (Yellow), #86CCCA (Teal), #6A7BB4 (Blue Purple)","Complementary geometric colors, pattern fills, contrasting accent shapes","transform: rotate(), clip-path: polygon(), mix-blend-mode, repeating patterns, bold shapes","Creative agencies, music sites, youth brands, event promotion, artistic portfolios, entertainment","Corporate finance, healthcare, legal, elderly users, conservative brands",✓ Full,✓ Full,⚡ Excellent,⚠ Check contrast,✓ Good,◐ Medium,"Tailwind 9/10, CSS 10/10",1980s Postmodern,Medium,"Design a Memphis style interface. Use: bold geometric shapes (triangles, squiggles, circles), bright clashing colors, 80s postmodern aesthetic, playful patterns, dotted textures, asymmetric layouts, decorative elements.","clip-path: polygon() for shapes, background: repeating patterns, transform: rotate() for tilted elements, mix-blend-mode for overlays, border: dashed/dotted patterns, bold sans-serif","☐ Geometric shapes visible, ☐ Colors bold/clashing, ☐ Patterns present, ☐ Layout asymmetric, ☐ Playful decorations, ☐ 80s vibe achieved","--memphis-pink: #FF71CE, --memphis-yellow: #FFCE5C, --memphis-teal: #86CCCA, --memphis-purple: #6A7BB4, --pattern-size: 20px, --shape-rotation: 15deg"
|
||||
45,Vaporwave,General,"Synthwave, retro-futuristic, 80s-90s, neon, glitch, nostalgic, sunset gradient, dreamy, aesthetic","#FF71CE (Pink), #01CDFE (Cyan), #05FFA1 (Mint), #B967FF (Purple)","Sunset gradients, glitch overlays, VHS effects, neon accents, pastel variations","text-shadow glow, linear-gradient, filter: hue-rotate(), glitch animations, retro scan lines","Music platforms, gaming, creative portfolios, tech startups, entertainment, artistic projects","Business apps, e-commerce, education, healthcare, enterprise software",✓ Full,✓ Dark focused,⚠ Moderate,⚠ Poor (motion),◐ Medium,◐ Medium,"Tailwind 8/10, CSS-in-JS 9/10",1980s-90s Retro,Medium,"Design a vaporwave aesthetic interface. Use: sunset gradients (pink/cyan/purple), 80s-90s nostalgia, glitch effects, Greek statue imagery, palm trees, grid patterns, neon glow, retro-futuristic feel, dreamy atmosphere.","background: linear-gradient(180deg, #FF71CE, #01CDFE, #B967FF), filter: hue-rotate(), text-shadow: neon glow, retro grid (perspective + linear-gradient), VHS scanlines","☐ Sunset gradient present, ☐ Neon glow applied, ☐ Retro grid visible, ☐ Glitch effects subtle, ☐ Dreamy atmosphere, ☐ 80s-90s aesthetic","--vapor-pink: #FF71CE, --vapor-cyan: #01CDFE, --vapor-mint: #05FFA1, --vapor-purple: #B967FF, --grid-color: rgba(255,255,255,0.1), --glow-intensity: 15px"
|
||||
46,Dimensional Layering,General,"Depth, overlapping, z-index, layers, 3D, shadows, elevation, floating, cards, spatial hierarchy","Neutral base (#FFFFFF, #F5F5F5, #E0E0E0) + brand accent for elevated elements","Shadow variations (sm/md/lg/xl), elevation colors, highlight colors for top layers","z-index stacking, box-shadow elevation (4 levels), transform: translateZ(), backdrop-filter, parallax","Dashboards, card layouts, modals, navigation, product showcases, SaaS interfaces","Print-style layouts, simple blogs, low-end devices, flat design requirements",✓ Full,✓ Full,⚠ Good,⚠ Moderate (SR issues),✓ Good,✓ High,"Tailwind 10/10, MUI 10/10, Chakra 10/10",2020s Modern,Medium,"Design with dimensional layering. Use: z-index depth (multiple layers), overlapping cards, elevation shadows (4 levels), floating elements, parallax depth, backdrop blur for hierarchy, spatial UI feel.","z-index: 1-4 levels, box-shadow: elevation scale (sm/md/lg/xl), transform: translateZ(), backdrop-filter: blur(), position: relative for stacking, parallax on scroll","☐ Layers clearly defined, ☐ Shadows show depth, ☐ Overlaps intentional, ☐ Hierarchy clear, ☐ Performance optimized, ☐ Mobile depth maintained","--elevation-1: 0 1px 3px rgba(0,0,0,0.1), --elevation-2: 0 4px 6px rgba(0,0,0,0.1), --elevation-3: 0 10px 20px rgba(0,0,0,0.1), --elevation-4: 0 20px 40px rgba(0,0,0,0.15), --blur-amount: 8px"
|
||||
47,Exaggerated Minimalism,General,"Bold minimalism, oversized typography, high contrast, negative space, loud minimal, statement design","#000000 (Black), #FFFFFF (White), single vibrant accent only","Minimal - single accent color, no secondary colors, extreme restraint","font-size: clamp(3rem 10vw 12rem), font-weight: 900, letter-spacing: -0.05em, massive whitespace","Fashion, architecture, portfolios, agency landing pages, luxury brands, editorial","E-commerce catalogs, dashboards, forms, data-heavy, elderly users, complex apps",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"Tailwind 10/10, Typography.js 10/10",2020s Modern,Low,"Design with exaggerated minimalism. Use: oversized typography (clamp 3rem-12rem), extreme negative space, black/white primary, single accent color only, bold statements, minimal elements, dramatic contrast.","font-size: clamp(3rem, 10vw, 12rem), font-weight: 900, letter-spacing: -0.05em, color: #000 or #FFF, padding: 8rem+, single accent, no decorations","☐ Typography oversized, ☐ White space extreme, ☐ Black/white dominant, ☐ Single accent only, ☐ Elements minimal, ☐ Statement clear","--type-giant: clamp(3rem, 10vw, 12rem), --type-weight: 900, --spacing-huge: 8rem, --color-primary: #000000, --color-bg: #FFFFFF, --accent: single color only"
|
||||
48,Kinetic Typography,General,"Motion text, animated type, moving letters, dynamic, typing effect, morphing, scroll-triggered text","Flexible - high contrast recommended, bold colors for emphasis, animation-friendly palette","Accent colors for emphasis, transition colors, gradient text fills","@keyframes text animation, typing effect, background-clip: text, GSAP ScrollTrigger, split text","Hero sections, marketing sites, video platforms, storytelling, creative portfolios, landing pages","Long-form content, accessibility-critical, data interfaces, forms, elderly users",✓ Full,✓ Full,⚠ Moderate,❌ Poor (motion),✓ Good,✓ Very High,"GSAP 10/10, Framer Motion 10/10",2020s Modern,High,"Design with kinetic typography. Use: animated text, scroll-triggered reveals, typing effects, letter-by-letter animations, morphing text, gradient text fills, oversized hero text, text as the main visual element.","@keyframes for text animation, background-clip: text, GSAP SplitText, typing effect (steps()), transform on letters, scroll-triggered (Intersection Observer), variable fonts for morphing","☐ Text animations smooth, ☐ Prefers-reduced-motion respected, ☐ Fallback for no-JS, ☐ Mobile performance ok, ☐ Typing effect timed, ☐ Scroll triggers work","--text-animation-duration: 1s, --letter-delay: 0.05s, --typing-speed: 100ms, --gradient-text: linear-gradient(90deg, #color1, #color2), --morph-duration: 0.5s"
|
||||
49,Parallax Storytelling,General,"Scroll-driven, narrative, layered scrolling, immersive, progressive disclosure, cinematic, scroll-triggered","Story-dependent, often gradients and natural colors, section-specific palettes","Section transition colors, depth layer colors, narrative mood colors","transform: translateY(scroll), position: fixed/sticky, perspective: 1px, scroll-triggered animations","Brand storytelling, product launches, case studies, portfolios, annual reports, marketing campaigns","E-commerce, dashboards, mobile-first, SEO-critical, accessibility-required",✓ Full,✓ Full,❌ Poor,❌ Poor (motion),✗ Low,✓ High,"GSAP ScrollTrigger 10/10, Locomotive Scroll 10/10",2020s Modern,High,"Design a parallax storytelling page. Use: scroll-driven narrative, layered backgrounds (3-5 layers), fixed/sticky sections, cinematic transitions, progressive disclosure, full-screen chapters, depth perception.","position: fixed/sticky, transform: translateY(calc()), perspective: 1px, z-index layering, scroll-snap-type, Intersection Observer for triggers, will-change: transform","☐ Layers parallax smoothly, ☐ Story flows naturally, ☐ Mobile alternative provided, ☐ Performance optimized, ☐ Skip option available, ☐ Reduced motion fallback","--parallax-speed-bg: 0.3, --parallax-speed-mid: 0.6, --parallax-speed-fg: 1, --section-height: 100vh, --transition-duration: 600ms, --perspective: 1px"
|
||||
50,Swiss Modernism 2.0,General,"Grid system, Helvetica, modular, asymmetric, international style, rational, clean, mathematical spacing","#000000, #FFFFFF, #F5F5F5, single vibrant accent only","Minimal secondary, accent for emphasis only, no gradients","display: grid, grid-template-columns: repeat(12 1fr), gap: 1rem, mathematical ratios, clear hierarchy","Corporate sites, architecture, editorial, SaaS, museums, professional services, documentation","Playful brands, children's sites, entertainment, gaming, emotional storytelling",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ High,"Tailwind 10/10, Bootstrap 9/10, Foundation 10/10",1950s Swiss + 2020s,Low,"Design with Swiss Modernism 2.0. Use: strict grid system (12 columns), Helvetica/Inter fonts, mathematical spacing, asymmetric balance, high contrast, minimal decoration, clean hierarchy, single accent color.","display: grid, grid-template-columns: repeat(12, 1fr), gap: 1rem (8px base unit), font-family: Inter/Helvetica, font-weight: 400-700, color: #000/#FFF, single accent","☐ 12-column grid strict, ☐ Spacing mathematical, ☐ Typography hierarchy clear, ☐ Single accent only, ☐ No decorations, ☐ High contrast verified","--grid-columns: 12, --grid-gap: 1rem, --base-unit: 8px, --font-primary: Inter, --color-text: #000000, --color-bg: #FFFFFF, --accent: single vibrant"
|
||||
51,HUD / Sci-Fi FUI,General,"Futuristic, technical, wireframe, neon, data, transparency, iron man, sci-fi, interface","Neon Cyan #00FFFF, Holographic Blue #0080FF, Alert Red #FF0000","Transparent Black, Grid Lines #333333","Glow effects, scanning animations, ticker text, blinking markers, fine line drawing","Sci-fi games, space tech, cybersecurity, movie props, immersive dashboards","Standard corporate, reading heavy content, accessible public services",✓ Low,✓ Full,⚠ Moderate (renders),⚠ Poor (thin lines),◐ Medium,✗ Low,"React 9/10, Canvas 10/10",2010s Sci-Fi,High,"Design a futuristic HUD (Heads Up Display) or FUI. Use: thin lines (1px), neon cyan/blue on black, technical markers, decorative brackets, data visualization, monospaced tech fonts, glowing elements, transparency.","border: 1px solid rgba(0,255,255,0.5), color: #00FFFF, background: transparent or rgba(0,0,0,0.8), font-family: monospace, text-shadow: 0 0 5px cyan","☐ Fine lines 1px, ☐ Neon glow text/borders, ☐ Monospaced font, ☐ Dark/Transparent BG, ☐ Decorative tech markers, ☐ Holographic feel","--hud-color: #00FFFF, --bg-color: rgba(0,10,20,0.9), --line-width: 1px, --glow: 0 0 5px, --font: monospace"
|
||||
52,Pixel Art,General,"Retro, 8-bit, 16-bit, gaming, blocky, nostalgic, pixelated, arcade","Primary colors (NES Palette), brights, limited palette","Black outlines, shading via dithering or block colors","Frame-by-frame sprite animation, blinking cursor, instant transitions, marquee text","Indie games, retro tools, creative portfolios, nostalgia marketing, Web3/NFT","Professional corporate, modern SaaS, high-res photography sites",✓ Full,✓ Full,⚡ Excellent,✓ Good (if contrast ok),✓ High,◐ Medium,"CSS (box-shadow) 8/10, Canvas 10/10",1980s Arcade,Medium,"Design a pixel art inspired interface. Use: pixelated fonts, 8-bit or 16-bit aesthetic, sharp edges (image-rendering: pixelated), limited color palette, blocky UI elements, retro gaming feel.","font-family: 'Press Start 2P', image-rendering: pixelated, box-shadow: 4px 0 0 #000 (pixel border), no anti-aliasing","☐ Pixelated fonts loaded, ☐ Images sharp (no blur), ☐ CSS box-shadow for pixel borders, ☐ Retro palette, ☐ Blocky layout","--pixel-size: 4px, --font: pixel font, --border-style: pixel-shadow, --anti-alias: none"
|
||||
53,Bento Grids,General,"Apple-style, modular, cards, organized, clean, hierarchy, grid, rounded, soft","Off-white #F5F5F7, Clean White #FFFFFF, Text #1D1D1F","Subtle accents, soft shadows, blurred backdrops","Hover scale (1.02), soft shadow expansion, smooth layout shifts, content reveal","Product features, dashboards, personal sites, marketing summaries, galleries","Long-form reading, data tables, complex forms",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"CSS Grid 10/10, Tailwind 10/10",2020s Apple/Linear,Low,"Design a Bento Grid layout. Use: modular grid system, rounded corners (16-24px), different card sizes (1x1, 2x1, 2x2), card-based hierarchy, soft backgrounds (#F5F5F7), subtle borders, content-first, Apple-style aesthetic.","display: grid, grid-template-columns: repeat(auto-fit, minmax(...)), gap: 1rem, border-radius: 20px, background: #FFF, box-shadow: subtle","☐ Grid layout (CSS Grid), ☐ Rounded corners 16-24px, ☐ Varied card spans, ☐ Content fits card size, ☐ Responsive re-flow, ☐ Apple-like aesthetic","--grid-gap: 20px, --card-radius: 24px, --card-bg: #FFFFFF, --page-bg: #F5F5F7, --shadow: soft"
|
||||
55,Spatial UI (VisionOS),General,"Glass, depth, immersion, spatial, translucent, gaze, gesture, apple, vision-pro","Frosted Glass #FFFFFF (15-30% opacity), System White","Vibrant system colors for active states, deep shadows for depth","Parallax depth, dynamic lighting response, gaze-hover effects, smooth scale on focus","Spatial computing apps, VR/AR interfaces, immersive media, futuristic dashboards","Text-heavy documents, high-contrast requirements, non-3D capable devices",✓ Full,✓ Full,⚠ Moderate (blur cost),⚠ Contrast risks,✓ High (if adapted),✓ High,"SwiftUI, React (Three.js/Fiber)",2024 Spatial Era,High,"Design a VisionOS-style spatial interface. Use: frosted glass panels, depth layers, translucent backgrounds (15-30% opacity), vibrant colors for active states, gaze-hover effects, floating windows, immersive feel.","backdrop-filter: blur(40px) saturate(180%), background: rgba(255,255,255,0.2), border-radius: 24px, box-shadow: 0 8px 32px rgba(0,0,0,0.1), transform: scale on focus, depth via shadows","☐ Glass effect visible, ☐ Depth layers clear, ☐ Hover states defined, ☐ Colors vibrant on active, ☐ Floating feel achieved, ☐ Contrast maintained","--glass-bg: rgba(255,255,255,0.2), --glass-blur: 40px, --glass-saturate: 180%, --window-radius: 24px, --depth-shadow: 0 8px 32px rgba(0,0,0,0.1), --focus-scale: 1.02"
|
||||
56,E-Ink / Paper,General,"Paper-like, matte, high contrast, texture, reading, calm, slow tech, monochrome","Off-White #FDFBF7, Paper White #F5F5F5, Ink Black #1A1A1A","Pencil Grey #4A4A4A, Highlighter Yellow #FFFF00 (accent)","No motion blur, distinct page turns, grain/noise texture, sharp transitions (no fade)","Reading apps, digital newspapers, minimal journals, distraction-free writing, slow-living brands","Gaming, video platforms, high-energy marketing, dark mode dependent apps",✓ Full,✗ Low (inverted only),⚡ Excellent,✓ WCAG AAA,✓ High,✓ Medium,"Tailwind 10/10, CSS 10/10",2020s Digital Well-being,Low,"Design an e-ink/paper style interface. Use: high contrast black on off-white, paper texture, no animations (instant transitions), reading-focused, minimal UI chrome, distraction-free, calm aesthetic, monochrome.","background: #FDFBF7 (paper white), color: #1A1A1A, transition: none, font-family: serif for reading, no gradients, border: 1px solid #E0E0E0, texture overlay (noise)","☐ Paper background color, ☐ High contrast text, ☐ No animations, ☐ Reading optimized, ☐ Distraction-free, ☐ Print-friendly","--paper-bg: #FDFBF7, --ink-color: #1A1A1A, --pencil-grey: #4A4A4A, --border-color: #E0E0E0, --font-reading: Georgia, --transition: none"
|
||||
57,Gen Z Chaos / Maximalism,General,"Chaos, clutter, stickers, raw, collage, mixed media, loud, internet culture, ironic","Clashing Brights: #FF00FF, #00FF00, #FFFF00, #0000FF","Gradients, rainbow, glitch, noise, heavily saturated mix","Marquee scrolls, jitter, sticker layering, GIF overload, random placement, drag-and-drop","Gen Z lifestyle brands, music artists, creative portfolios, viral marketing, fashion","Corporate, government, healthcare, banking, serious tools",✓ Full,✓ Full,⚠ Poor (heavy assets),❌ Poor,◐ Medium,✓ High (Viral),CSS-in-JS 8/10,2023+ Internet Core,High,"Design a Gen Z chaos maximalist interface. Use: clashing bright colors, sticker overlays, collage aesthetic, raw/unpolished feel, mixed media, ironic elements, loud typography, GIF-heavy, internet culture references.","mix-blend-mode: multiply/screen, transform: rotate(random), animation: jitter, marquee text, position: absolute for scattered elements, filter: saturate(150%), z-index chaos","☐ Colors clash intentionally, ☐ Stickers/overlays present, ☐ Layout chaotic but usable, ☐ GIFs optimized, ☐ Mobile scrollable, ☐ Performance acceptable","--chaos-pink: #FF00FF, --chaos-green: #00FF00, --chaos-yellow: #FFFF00, --chaos-blue: #0000FF, --jitter-amount: 5deg, --saturate: 150%"
|
||||
58,Biomimetic / Organic 2.0,General,"Nature-inspired, cellular, fluid, breathing, generative, algorithms, life-like","Cellular Pink #FF9999, Chlorophyll Green #00FF41, Bioluminescent Blue","Deep Ocean #001E3C, Coral #FF7F50, Organic gradients","Breathing animations, fluid morphing, generative growth, physics-based movement","Sustainability tech, biotech, advanced health, meditation, generative art platforms","Standard SaaS, data grids, strict corporate, accounting",✓ Full,✓ Full,⚠ Moderate,✓ Good,✓ Good,✓ High,"Canvas 10/10, WebGL 10/10",2024+ Generative,High,"Design a biomimetic organic interface. Use: cellular/fluid shapes, breathing animations, generative patterns, bioluminescent colors, physics-based movement, nature algorithms, life-like elements, flowing gradients.","SVG morphing (SMIL or GSAP), canvas for generative, animation: breathing (scale pulse), filter: blur for organic, clip-path for cellular, WebGL for advanced, physics libraries","☐ Organic shapes present, ☐ Animations feel alive, ☐ Generative elements, ☐ Performance monitored, ☐ Mobile fallback, ☐ Accessibility alt content","--cellular-pink: #FF9999, --chlorophyll: #00FF41, --bioluminescent: #00FFFF, --breathing-duration: 4s, --morph-ease: cubic-bezier(0.4, 0, 0.2, 1), --organic-blur: 20px"
|
||||
59,Anti-Polish / Raw Aesthetic,General,"Hand-drawn, collage, scanned textures, unfinished, imperfect, authentic, human, sketch, raw marks, creative process","Paper White #FAFAF8, Pencil Grey #4A4A4A, Marker Black #1A1A1A, Kraft Brown #C4A77D","Watercolor washes, pencil shading, ink splatters, tape textures, aged paper tones","No smooth transitions, hand-drawn animations, paper texture overlays, jitter effects, sketch reveal","Creative portfolios, artist sites, indie brands, handmade products, authentic storytelling, editorial","Corporate enterprise, fintech, healthcare, government, polished SaaS",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"CSS 10/10, SVG 10/10",2025+ Anti-Digital,Low,"Design with anti-polish raw aesthetic. Use: hand-drawn elements, scanned textures, unfinished look, paper/pencil textures, collage style, authentic imperfection, sketch marks, tape/sticker overlays, human touch.","background: url(paper-texture.png), filter: grayscale() contrast(), border: hand-drawn SVG, transform: rotate(small random), no smooth transitions, sketch-style fonts, opacity variations","☐ Textures loaded, ☐ Hand-drawn elements present, ☐ Imperfections intentional, ☐ Authentic feel achieved, ☐ Performance ok with textures, ☐ Accessibility maintained","--paper-bg: #FAFAF8, --pencil-color: #4A4A4A, --marker-black: #1A1A1A, --kraft-brown: #C4A77D, --sketch-rotation: random(-3deg, 3deg), --texture-opacity: 0.3"
|
||||
60,Tactile Digital / Deformable UI,General,"Jelly buttons, chrome, clay, squishy, deformable, bouncy, physical, tactile feedback, press response","Gradient metallics, Chrome Silver #C0C0C0, Jelly Pink #FF9ECD, Soft Blue #87CEEB","Glossy highlights, shadow depth, reflection effects, material-specific colors","Press deformation (scale + squish), bounce-back (cubic-bezier), material response, haptic-like feedback, spring physics","Modern mobile apps, playful brands, entertainment, gaming UI, consumer products, interactive demos","Enterprise software, data dashboards, accessibility-critical, professional tools",✓ Full,✓ Full,⚠ Good,⚠ Motion sensitive,✓ High,✓ Very High,"Framer Motion 10/10, React Spring 10/10, GSAP 10/10",2025+ Tactile Era,Medium,"Design a tactile deformable interface. Use: jelly/squishy buttons, press deformation effect, bounce-back animations, chrome/clay materials, spring physics, haptic-like feedback, material response, 3D depth on interaction.","transform: scale(0.95) on active, animation: bounce (cubic-bezier(0.34, 1.56, 0.64, 1)), box-shadow: inset for press, filter: brightness on press, spring physics (react-spring/framer-motion)","☐ Press effect visible, ☐ Bounce-back smooth, ☐ Material feels tactile, ☐ Spring physics tuned, ☐ Mobile touch responsive, ☐ Reduced motion option","--press-scale: 0.95, --bounce-duration: 400ms, --spring-stiffness: 300, --spring-damping: 20, --material-glossy: linear-gradient(135deg, white 0%, transparent 60%), --depth-shadow: 0 10px 30px rgba(0,0,0,0.2)"
|
||||
61,Nature Distilled,General,"Muted earthy, skin tones, wood, soil, sand, terracotta, warmth, organic materials, handmade warmth","Terracotta #C67B5C, Sand Beige #D4C4A8, Warm Clay #B5651D, Soft Cream #F5F0E1","Earth Brown #8B4513, Olive Green #6B7B3C, Warm Stone #9C8B7A, muted gradients","Subtle parallax, natural easing (ease-out), texture overlays, grain effects, soft shadows","Wellness brands, sustainable products, artisan goods, organic food, spa/beauty, home decor","Tech startups, gaming, nightlife, corporate finance, high-energy brands",✓ Full,◐ Partial,⚡ Excellent,✓ WCAG AA,✓ High,✓ High,"Tailwind 10/10, CSS 10/10",2025+ Handmade Warmth,Low,"Design with nature distilled aesthetic. Use: muted earthy colors (terracotta, sand, olive), organic materials feel, warm tones, handmade warmth, natural textures, artisan quality, sustainable vibe, soft gradients.","background: warm earth tones, color: #C67B5C #D4C4A8 #6B7B3C, border-radius: organic (varied), box-shadow: soft natural, texture overlays (grain), font: humanist sans-serif","☐ Earth tones dominant, ☐ Warm feel achieved, ☐ Textures subtle, ☐ Handmade quality, ☐ Sustainable messaging, ☐ Calming aesthetic","--terracotta: #C67B5C, --sand-beige: #D4C4A8, --warm-clay: #B5651D, --soft-cream: #F5F0E1, --olive-green: #6B7B3C, --grain-opacity: 0.1"
|
||||
62,Interactive Cursor Design,General,"Custom cursor, cursor as tool, hover effects, cursor feedback, pointer transformation, cursor trail, magnetic cursor","Brand-dependent, cursor accent color, high contrast for visibility","Trail colors, hover state colors, magnetic zone indicators, feedback colors","Cursor scale on hover, magnetic pull to elements, cursor morphing, trail effects, blend mode cursors, click feedback","Creative portfolios, interactive experiences, agency sites, product showcases, gaming, entertainment","Mobile-first (no cursor), accessibility-critical, data-heavy dashboards, forms",✓ Full,✓ Full,⚡ Good,⚠ Not for touch/SR,✗ No cursor,✓ High,"GSAP 10/10, Framer Motion 10/10, Custom JS 10/10",2025+ Interactive,Medium,"Design with interactive cursor effects. Use: custom cursor, cursor morphing on hover, magnetic cursor pull, cursor trails, blend mode cursors, click feedback animations, cursor as interaction tool, pointer transformation.","cursor: none (custom), position: fixed for cursor element, mix-blend-mode: difference, transform on hover targets, magnetic effect (JS position lerp), trail with opacity fade, scale on click","☐ Custom cursor works, ☐ Hover morph smooth, ☐ Magnetic pull subtle, ☐ Trail performance ok, ☐ Click feedback visible, ☐ Touch fallback provided","--cursor-size: 20px, --cursor-hover-scale: 1.5, --magnetic-distance: 100px, --trail-length: 10, --trail-fade: 0.1, --blend-mode: difference"
|
||||
63,Voice-First Multimodal,General,"Voice UI, multimodal, audio feedback, conversational, hands-free, ambient, contextual, speech recognition","Calm neutrals: Soft White #FAFAFA, Muted Blue #6B8FAF, Gentle Purple #9B8FBB","Audio waveform colors, status indicators (listening/processing/speaking), success/error tones","Voice waveform visualization, listening pulse, processing spinner, speak animation, smooth transitions","Voice assistants, accessibility apps, hands-free tools, smart home, automotive UI, cooking apps","Visual-heavy content, data entry, complex forms, noisy environments",✓ Full,✓ Full,⚡ Excellent,✓ Excellent,✓ High,✓ High,"Web Speech API 10/10, React 10/10",2025+ Voice Era,Medium,"Design a voice-first multimodal interface. Use: voice waveform visualization, listening state indicator, speaking animation, minimal visible UI, audio feedback cues, hands-free optimized, conversational flow, ambient design.","Web Speech API integration, canvas for waveform, animation: pulse for listening, status indicators (color change), audio visualization (Web Audio API), minimal chrome, large touch targets","☐ Voice recognition works, ☐ Visual feedback clear, ☐ Listening state obvious, ☐ Speaking animation smooth, ☐ Fallback UI provided, ☐ Accessibility excellent","--listening-color: #6B8FAF, --speaking-color: #22C55E, --waveform-height: 60px, --pulse-duration: 1.5s, --indicator-size: 24px, --voice-accent: #9B8FBB"
|
||||
64,3D Product Preview,General,"360 product view, rotatable, zoomable, touch-to-spin, AR preview, product configurator, interactive 3D model","Product-dependent, neutral backgrounds: Soft Grey #E8E8E8, Pure White #FFFFFF","Shadow gradients, reflection planes, environment lighting colors, accent highlights","Drag-to-rotate, pinch-to-zoom, spin animation, AR placement, material switching, smooth orbit controls","E-commerce, furniture, fashion, automotive, electronics, jewelry, product configurators","Content-heavy sites, blogs, dashboards, low-bandwidth, accessibility-critical",◐ Partial,◐ Partial,❌ Poor (3D rendering),⚠ Alt content needed,◐ Medium,✓ Very High,"Three.js 10/10, model-viewer 10/10, Spline 9/10",2025+ E-commerce 3D,High,"Design a 3D product preview interface. Use: 360° rotation, drag-to-spin, pinch-to-zoom, AR preview button, material/color switcher, hotspot annotations, orbit controls, product configurator, smooth rendering.","Three.js or model-viewer, OrbitControls, touch events for rotation, WebXR for AR, canvas with WebGL, loading placeholder, LOD for performance, environment lighting","☐ 3D model loads fast, ☐ Rotation smooth, ☐ Zoom works (pinch/scroll), ☐ AR button functional, ☐ Colors switchable, ☐ Mobile touch works","--canvas-bg: #F5F5F5, --hotspot-color: #3B82F6, --loading-spinner: primary, --rotation-speed: 0.5, --zoom-min: 0.5, --zoom-max: 2"
|
||||
65,Gradient Mesh / Aurora Evolved,General,"Complex gradients, mesh gradients, multi-color blend, aurora effect, flowing colors, iridescent, holographic, prismatic","Multi-stop gradients: Cyan #00FFFF, Magenta #FF00FF, Yellow #FFFF00, Blue #0066FF, Green #00FF66","Complementary mesh points, smooth color transitions, iridescent overlays, chromatic shifts","CSS mesh-gradient (experimental), SVG gradients, canvas gradients, smooth color morphing, flowing animation","Hero sections, backgrounds, creative brands, music platforms, fashion, lifestyle, premium products","Data interfaces, text-heavy content, accessibility-critical, conservative brands",✓ Full,✓ Full,⚠ Good,⚠ Text contrast,✓ Good,✓ High,"CSS 8/10, SVG 10/10, Canvas 10/10",2025+ Gradient Evolution,Medium,"Design with gradient mesh aurora effect. Use: multi-color mesh gradients, flowing color transitions, aurora/northern lights feel, iridescent overlays, holographic shimmer, prismatic effects, smooth color morphing.","background: conic-gradient or mesh (SVG), animation: gradient flow (background-position), filter: hue-rotate for shimmer, mix-blend-mode: screen, canvas for complex mesh, multiple gradient layers","☐ Mesh gradient visible, ☐ Colors flow smoothly, ☐ Aurora effect achieved, ☐ Performance acceptable, ☐ Text remains readable, ☐ Mobile renders ok","--mesh-color-1: #00FFFF, --mesh-color-2: #FF00FF, --mesh-color-3: #FFFF00, --mesh-color-4: #00FF66, --flow-duration: 10s, --shimmer-intensity: 0.3"
|
||||
66,Editorial Grid / Magazine,General,"Magazine layout, asymmetric grid, editorial typography, pull quotes, drop caps, column layout, print-inspired","High contrast: Black #000000, White #FFFFFF, accent brand color","Muted supporting, pull quote highlights, byline colors, section dividers","Smooth scroll, reveal on scroll, parallax images, text animations, page-flip transitions","News sites, blogs, magazines, editorial content, long-form articles, journalism, publishing","Dashboards, apps, e-commerce catalogs, real-time data, short-form content",✓ Full,✓ Full,⚡ Excellent,✓ WCAG AAA,✓ High,✓ Medium,"CSS Grid 10/10, Tailwind 10/10",2020s Editorial Digital,Low,"Design an editorial magazine layout. Use: asymmetric grid, pull quotes, drop caps, multi-column text, large imagery, bylines, section dividers, print-inspired typography, article hierarchy, white space balance.","display: grid with named areas, column-count for text, ::first-letter for drop caps, blockquote styling, figure/figcaption, gap variations, font: serif for body, variable widths","☐ Grid asymmetric, ☐ Typography editorial, ☐ Pull quotes styled, ☐ Drop caps present, ☐ Images large/impactful, ☐ Mobile reflows well","--grid-cols: asymmetric, --body-font: Georgia/Merriweather, --heading-font: bold sans, --drop-cap-size: 4em, --pull-quote-size: 1.5em, --column-gap: 2rem"
|
||||
67,Chromatic Aberration / RGB Split,General,"RGB split, color fringing, glitch, retro tech, VHS, analog error, distortion, lens effect","Offset RGB: Red #FF0000, Green #00FF00, Blue #0000FF, Black #000000","Neon accents, scan lines, noise overlays, error colors","RGB offset animation, glitch timing, scan line movement, noise flicker, distortion on hover","Music platforms, gaming, tech brands, creative portfolios, nightlife, entertainment, video platforms","Corporate, healthcare, finance, accessibility-critical, elderly users",✓ Full,✓ Dark preferred,⚠ Good,⚠ Can cause strain,◐ Medium,✓ High,"CSS filters 10/10, GSAP 10/10",2020s Retro-Tech,Medium,"Design with chromatic aberration RGB split effect. Use: color channel offset (R/G/B), glitch aesthetic, retro tech feel, VHS error look, lens distortion, scan lines, noise overlay, analog imperfection.","filter: drop-shadow with offset colors, text-shadow: RGB offset (-2px 0 red, 2px 0 cyan), animation: glitch (random offset), ::before for scanlines, mix-blend-mode: screen for overlays","☐ RGB split visible, ☐ Glitch effect controlled, ☐ Scan lines subtle, ☐ Performance ok, ☐ Readability maintained, ☐ Reduced motion option","--rgb-offset: 2px, --red-channel: #FF0000, --green-channel: #00FF00, --blue-channel: #0000FF, --glitch-duration: 0.3s, --scanline-opacity: 0.1"
|
||||
68,Vintage Analog / Retro Film,General,"Film grain, VHS, cassette tape, polaroid, analog warmth, faded colors, light leaks, vintage photography","Faded Cream #F5E6C8, Warm Sepia #D4A574, Muted Teal #4A7B7C, Soft Pink #E8B4B8","Grain overlays, light leak oranges, shadow blues, vintage paper tones, desaturated accents","Film grain overlay, VHS tracking effect, polaroid shake, fade-in transitions, light leak animations","Photography portfolios, music/vinyl brands, vintage fashion, nostalgia marketing, film industry, cafes","Modern tech, SaaS, healthcare, children's apps, corporate enterprise",✓ Full,◐ Partial,⚡ Good,✓ WCAG AA,✓ High,✓ High,"CSS filters 10/10, Canvas 9/10",1970s-90s Analog Revival,Medium,"Design with vintage analog film aesthetic. Use: film grain overlay, faded/desaturated colors, warm sepia tones, light leaks, VHS tracking effect, polaroid frame, analog warmth, nostalgic photography feel.","filter: sepia() contrast() saturate(0.8), background: noise texture overlay, animation: VHS tracking (transform skew), light leak gradient overlay, border for polaroid frame, grain via SVG filter","☐ Film grain visible, ☐ Colors faded/warm, ☐ Light leaks present, ☐ Nostalgic feel achieved, ☐ Performance with filters, ☐ Images look vintage","--sepia-amount: 20%, --contrast: 1.1, --saturation: 0.8, --grain-opacity: 0.15, --light-leak-color: rgba(255,200,100,0.2), --warm-tint: #F5E6C8"
|
||||
69,Bauhaus (包豪斯),Mobile,"bauhaus, geometric, constructivist, primary colors, hard shadow, bold, tactile, functional, poster, mechanical, architectural","Primary Red #D02020, Primary Blue #1040C0, Primary Yellow #F0C020","Background #F0F0F0 (Off-white), Foreground #121212 (Stark Black), Muted #E0E0E0","Hard offset shadows (4px 4px 0px black), mechanical press active:translate, no smooth hover — instant 0ms transitions, dot grid pattern on sections, slide-over transitions","Mobile-first apps needing high personality, onboarding flows, branding-forward product screens, artisan/design brands, editorial mobile experiences","Enterprise dashboards, accessibility-critical contexts (requires extra a11y work), data-heavy screens, conservative industries",✓ Full,◐ Partial (primary palette only),⚡ Excellent,⚠ WCAG AA (high contrast primaries; verify yellow text separately),✓ Mobile-First,◐ Medium,"React Native 10/10, Expo 10/10, SwiftUI 9/10, Flutter 9/10, Tailwind 9/10",1919 Bauhaus Movement,Medium,"Design a Bauhaus mobile app. Use strict geometric shapes (circles and squares only), primary color blocking (Red #D02020, Blue #1040C0, Yellow #F0C020), hard 4px offset black shadows, OFF-WHITE canvas (#F0F0F0), massive bold uppercase headlines (Outfit Black 900), rectangular full-width buttons with mechanical press animation. No gradients. No rounded cards. No soft transitions.","border-radius: 0px (cards/inputs) or 9999px (buttons/FAB), box-shadow: 4px 4px 0px 0px #121212, active:translate-x-[2px] active:translate-y-[2px] active:shadow-none, border: 2px solid #121212, font-family: Outfit, font-weight: 900 uppercase tracking-tighter (headlines)","☐ Geometric shapes only (circle/square), ☐ Primary color blocking applied, ☐ Hard offset shadows 4px, ☐ border-2 border-black on all elements, ☐ Mechanical press active state, ☐ Outfit Black 900 uppercase headlines, ☐ Safe area (pt-safe pb-safe) respected, ☐ Thumb-friendly h-12/h-14 touch targets, ☐ No hover states (mobile-only), ☐ Vertical rhythm single-column stack","--color-red: #D02020, --color-blue: #1040C0, --color-yellow: #F0C020, --color-bg: #F0F0F0, --color-fg: #121212, --border-width: 2px, --shadow-hard: 4px 4px 0px 0px #121212, --radius-block: 0px, --radius-pill: 9999px, --font-display: Outfit, --font-weight-hero: 900"
|
||||
70,Minimalist Monochrome,Mobile,"monochrome, black white, editorial, austere, typographic, sharp, zero radius, high contrast, brutalist, pocket editorial, serif, mechanical","Pure Black #000000, Pure White #FFFFFF","Muted #F5F5F5, Dark Gray #525252, Border Light #E5E5E5","Instant inversion active state (tap → bg-black text-white, zero transition-none), no shadows (strictly 2D), full-bleed horizontal rules (4px black section dividers), subtle paper noise texture (opacity: 0.03), slide-in page transitions with hard edge","Luxury fashion e-commerce mobile, editorial publications, high-end portfolio apps, experimental/avant-garde brands, digital exhibitions","Entertainment, colorful brands, friendly consumer apps, anything requiring visual warmth or gradient",✓ Full (Light Mode Enforced),◐ Dark by section only (inverted sections),⚡ Excellent,✓ WCAG AAA (pure black/white),✓ Mobile-First,◐ Medium,"React Native 10/10, Expo 10/10, SwiftUI 9/10, Tailwind 9/10",2020s Editorial Mobile,Medium,"Design a minimalist monochrome mobile app. Use ONLY black (#000000) and white (#FFFFFF). Zero border-radius on every element. No shadows — depth is created by 1–4px black borders and color inversion only. Typography is the primary visual: Playfair Display for heroes (text-5xl–text-6xl, tracking-tighter, leading-[0.9]), Source Serif 4 for body, JetBrains Mono for labels/tags. Tap states instantly invert (bg-black text-white). Full-width horizontal rules separate sections. Use the word 'MENU' instead of hamburger icon.","border-radius: 0px (ALL elements including modals), box-shadow: none, active:bg-black active:text-white transition-none, border-b-4 border-black (section dividers), divide-y divide-black (lists), font-family: Playfair Display (headers) + Source Serif 4 (body) + JetBrains Mono (labels), background-image: noise SVG opacity-[0.03]","☐ 0px border-radius on ALL elements, ☐ No shadows anywhere, ☐ Instant inversion on every tap (transition-none), ☐ 4px black line separates hero from content, ☐ Safe area respected (pt-safe pb-safe), ☐ h-14 touch targets, ☐ Sticky section headers with border-b, ☐ Typography hero: word spans full screen width, ☐ Paper noise texture on backgrounds, ☐ Menu word-label instead of icon","--color-bg: #FFFFFF, --color-fg: #000000, --color-muted: #F5F5F5, --color-muted-fg: #525252, --color-border: #000000, --color-border-light: #E5E5E5, --radius: 0px, --shadow: none, --border-hairline: 1px solid #E5E5E5, --border-thin: 1px solid #000000, --border-thick: 2px solid #000000, --border-heavy: 4px solid #000000, --font-display: Playfair Display, --font-body: Source Serif 4, --font-mono: JetBrains Mono"
|
||||
71,Modern Dark (Cinema Mobile),Mobile,"dark mode, cinematic, ambient light, glassmorphism, deep black, indigo, glow, blur, atmospheric, reanimated, haptic, premium, layered, frosted glass, linear gradient","Deep #020203, Base #050506, Elevated #0a0a0c, Accent #5E6AD2","Foreground #EDEDEF, Muted #8A8F98, Accent Glow rgba(94 106 210/0.2), Border rgba(255 255 255/0.08), Surface rgba(255 255 255/0.05)","Expo.out Bezier(0.16,1,0.3,1) easing; spring modals (damping:20 stiffness:90); haptic-linked press (Impact Light/Medium); animated ambient light blobs (Reanimated translateX/Y slow oscillation); BlurView glassmorphism headers/nav (intensity 20); scale press 0.97 → 1.0; avoid pure #000000 (OLED smear)","Developer tools, pro productivity apps, fintech/trading dashboards, media/streaming platforms, AI tool interfaces, high-end gaming companion apps","Consumer apps needing warmth, children's apps, health/medical contexts where dark feels harsh, high-accessibility contexts needing maximum contrast",✓ Light mode only as exception,✓ Dark Mode Primary,⚠ Good (blur effects require native driver),⚠ WCAG AA (requires careful accent contrast check),✓ Mobile-First,◐ Medium,"React Native 10/10, Expo 10/10, react-native-skia 9/10, SwiftUI 8/10",2020s Cinematic Mobile,High,"Design a cinematic dark mobile app. Background: LinearGradient from #0a0a0f (top) to #020203 (bottom). Add 2–3 absolute animated 'blob' views: circular, blurRadius 30–50, opacity 0.08–0.12, slow Reanimated oscillation. Cards: borderRadius 16, border rgba(255,255,255,0.08) hairline, subtle top-edge shine gradient. Primary button: #5E6AD2, scale press 0.97, haptic on press. BlurView (intensity 20, tint dark) for tab bar and headers. Typography: Inter 700 for headers, 400 for body. Never use pure #000000. Accent glow: rgba(94,106,210,0.2) behind primary actions.","borderRadius: 16 (cards/buttons), background: LinearGradient #0a0a0f→#020203, border: StyleSheet.hairlineWidth rgba(255,255,255,0.08), BlurView intensity={20} tint='dark', useAnimatedStyle + withRepeat (blob oscillation), Easing.bezier(0.16,1,0.3,1), withSpring damping:20 stiffness:90, Haptics.impactAsync(ImpactFeedbackStyle.Light), scale: 0.97 press","☐ No pure #000000 backgrounds, ☐ LinearGradient base screen, ☐ Animated ambient blobs (Reanimated, native driver), ☐ BlurView on tab bar and headers, ☐ borderRadius 16 on all cards, ☐ Haptic feedback on every Pressable, ☐ Bezier(0.16,1,0.3,1) easing used, ☐ Accent glow behind primary button, ☐ No solid grey borders (rgba only), ☐ Bottom sheets replace all modals","--bg-deep: #020203, --bg-base: #050506, --bg-elevated: #0a0a0c, --surface: rgba(255 255 255/0.05), --foreground: #EDEDEF, --foreground-muted: #8A8F98, --accent: #5E6AD2, --accent-glow: rgba(94 106 210/0.2), --border: rgba(255 255 255/0.08), --radius: 16px, --easing: cubic-bezier(0.16 1 0.3 1), --font: Inter"
|
||||
72,SaaS Mobile (High-Tech Boutique),Mobile,"saas, electric blue, gradient, fintech, spring animation, dual font, glassmorphism, boutique, premium, calistoga, inter, mono, tactile, haptic, bento","Electric Blue #0052FF, Gradient End #4D7CFF","Background #FAFAFA, Foreground #0F172A, Muted #F1F5F9, Card #FFFFFF, Border #E2E8F0","Spring animations (mass:1 damping:15 stiffness:120); gradient buttons (0052FF→4D7CFF); scale press 0.96→1.0 with haptics; floating FAB with gentle bobbing (Reanimated); glassmorphism BlurView navigation bars; staggered fade-in entrance (Y:20→0 + opacity:0→1); pulsing status dot on section badges; layout transitions (LayoutAnimation or Reanimated entering)","B2B SaaS mobile dashboards, fintech apps, developer tool mobile companions, marketing analytics apps, HR/operations apps, modern business productivity","Pure consumer entertainment, children's apps, highly decorative lifestyle apps, contexts where Electric Blue feels too corporate",✓ Full,◐ Partial,⚡ Excellent,✓ WCAG AA,✓ Mobile-First,✓ High,"React Native 10/10, Expo 10/10, NativeWind 10/10, SwiftUI 8/10, Flutter 9/10",2020s SaaS Mobile,Medium,"Design a high-tech boutique SaaS mobile app. Primary canvas: #FAFAFA (warm off-white). Cards: #FFFFFF with 1pt Slate-200 border, iOS shadow (shadowOpacity:0.1, shadowRadius:10, offset y:4), Android elevation:4, padding 24px, borderRadius 16. Buttons: LinearGradient #0052FF→#4D7CFF, height 56px, borderRadius 16, scale press 0.96 + haptic. Section badges: rounded pill with rgba(0,82,255,0.05) bg and rgba(0,82,255,0.2) border + PulseDot + JetBrains Mono text. Typography: Calistoga for heroes (36–42pt), Inter for body (16–18pt), JetBrains Mono for data labels. All screen transitions: spring (mass:1 damping:15 stiffness:120). Always include SafeAreaView.","borderRadius: 16 (buttons/cards), LinearGradient colors={['#0052FF','#4D7CFF']}, shadowOpacity: 0.1, shadowRadius: 10, elevation: 4, Haptics.impactAsync(ImpactFeedbackStyle.Light) on press, withSpring({mass:1, damping:15, stiffness:120}), withTiming Y:20→0 opacity:0→1 staggered entrance, LayoutAnimation.configureNext for list updates, BlurView on nav bars","☐ SafeAreaView wraps all screens, ☐ All touch targets ≥ 44×44px, ☐ Spring config used for all transitions, ☐ Gradient buttons (not flat), ☐ Haptic on every Pressable, ☐ Section badges with PulseDot, ☐ Staggered entrance animation on screen mount, ☐ JetBrains Mono for data labels, ☐ Calistoga for hero headlines, ☐ Elevation/shadow on cards","--bg: #FAFAFA, --fg: #0F172A, --muted: #F1F5F9, --accent: #0052FF, --accent-sec: #4D7CFF, --card: #FFFFFF, --border: #E2E8F0, --radius: 16px, --shadow: shadowOpacity 0.1 shadowRadius 10, --spring: mass 1 damping 15 stiffness 120, --font-display: Calistoga, --font-body: Inter, --font-mono: JetBrains Mono"
|
||||
73,Terminal CLI (Mobile),Mobile,"terminal, cli, matrix green, monospace, hacker, ascii, command line, developer, web3, crypto, sci-fi, OLED, retro-future, field operative","Matrix Green #33FF00, OLED Black #050505","Amber #FFB000, Muted Green #1A3D1A, Error Red #FF3333, Border Green #33FF00","Blinking cursor (500ms opacity loop), typewriter text reveal hook, scanline overlay (repeating lines 0.05 opacity), ASCII art headers, instant color inversion on press (bg-green text-black), haptic on every keystroke, boot sequence splash on launch","Developer tools, Web3/blockchain apps, geek-culture apps, ARG games, sci-fi/noir gaming companions, hacker/security tools, creative studio portfolios","Consumer products, health apps, anything requiring approachability or warmth, children's apps, standard enterprise contexts",✗ No,✓ OLED Dark Only,⚡ Excellent,✓ High contrast (green on black ≫4.5:1 ratio),✓ Mobile-First (OLED optimized),✗ Low,"React Native 10/10, Expo 10/10, NativeWind 9/10",Retro-Future 1980s–2020s,Medium,"Design a Mobile Terminal CLI app. Background: #050505 OLED black. ALL text in Matrix Green #33FF00. Font: JetBrains Mono or SpaceMono ONLY — zero border-radius everywhere. ASCII borders using +, -, |, * characters instead of standard containers. Buttons displayed as [ EXECUTE ] or > PROCEED. On press: instantly inverts to green bg + black text + haptic. Cursor: blinking View opacity 0→1 at 500ms. Show boot sequence on launch (fake log scroll). Progress bars as [#####-----] text. Status bar footer: [BATTERY:88%] [NET:CONNECTED]. Scanline overlay: absolute View with repeating 1px horizontal lines at opacity 0.05. Typewriter effect on new data.","borderRadius: 0 (ALL elements), borderWidth: 1, borderColor: '#33FF00', backgroundColor: '#050505', color: '#33FF00', fontFamily: 'SpaceMono-Regular' or JetBrains Mono, fontSize: 12 or 14 or 16 only, lineHeight: 1.2x fontSize, Haptics.impactAsync(Light) on every press, useAnimatedValue blink 500ms, hitSlop: 12px all sides for bracketed buttons","☐ 0px border-radius everywhere, ☐ ASCII-style borders on cards, ☐ Boot sequence on launch, ☐ Blinking cursor component, ☐ Typewriter hook for new content, ☐ Scanline overlay (0.05 opacity), ☐ Haptic on every button press, ☐ Footer status bar component, ☐ hitSlop on all bracketed buttons (44×44dp), ☐ Reduced motion respected","--bg: #050505, --fg-primary: #33FF00, --fg-amber: #FFB000, --fg-muted: #1A3D1A, --fg-error: #FF3333, --border: #33FF00, --radius: 0px, --font: SpaceMono-Regular or JetBrains Mono, --font-sizes: 12 14 16 only, --blink-duration: 500ms, --scanline-opacity: 0.05"
|
||||
74,Kinetic Brutalism (Mobile),Mobile,"kinetic, brutalism, motion, marquee, acid yellow, uppercase, oversized, aggressive typography, street, zine, high contrast, scroll-driven, haptic, reanimated","Acid Yellow #DFE104, Rich Black #09090B","Off-white #FAFAFA, Dark Gray #27272A, Zinc #A1A1AA, Border Zinc #3F3F46","Infinite marquee (Reanimated, Linear easing, 5s loop, hard clip), hero parallax (scale 1.0→1.3 + fade), sticky section header push, card flood inversion on press (bg→#DFE104, text→#000000), haptic Medium on every press, scroll-triggered interpolate transforms, 0px radius, 2px borders, 100ms color transitions","Immersive storytelling apps, brand flagship mobile, music/culture platforms, sports apps, underground zines, limited-edition product drops, performance dashboards","Calm informational apps, healthcare, finance contexts needing trust, children's, any context where aggressive typography feels inappropriate",✓ Dark Primary,◐ Dark only (inverted sections),⚡ Excellent (native driver required),⚠ WCAG AA (verify zinc body text on dark bg),✓ Mobile-First,✓ High energy,"React Native 10/10, Expo 10/10, Reanimated 10/10, NativeWind 9/10",2020s Mobile Brutalism,High,"Design a Kinetic Brutalism mobile app. Canvas: #09090B. Primary accent: Acid Yellow #DFE104 (text: #000000). Typography: Space Grotesk BOLD. Display text: 60–120pt, uppercase, letterSpacing -1, lineHeight 0.9–1.1x. Body: 18–20pt. Labels: 12pt uppercase letterSpacing +2. Add infinite marquee rows (Reanimated, no easing, hard edge clip). Hero text parallax on scroll (Interpolate: scale 1.0→1.3, opacity 1→0). Card press: instantly flood to #DFE104 + flip text to #000. Haptic Medium on every press. 0px radius. 2px solid borders. NO shadows. No gradients. Scale all fonts by (windowWidth / 375 * size) for responsiveness.","borderRadius: 0, borderWidth: 2, borderColor: '#3F3F46', backgroundColor: '#09090B', color: '#FAFAFA', fontWeight: '800 or 900', letterSpacing: -1 (large) or 2 (labels), lineHeight: 0.9–1.1 * fontSize, Reanimated withRepeat marquee timing 5000ms Easing.linear, Interpolate scroll→scale + opacity, Haptics.impactAsync(Medium), scale press: 0.95, 100ms color transitions","☐ Infinite marquee rows (Reanimated, no fade edges), ☐ Hero parallax scroll (scale+opacity Interpolate), ☐ All display text uppercase, ☐ 0px border-radius, ☐ 2px borders, ☐ Acid yellow card flood on press, ☐ Haptic Medium on every interaction, ☐ Font scale helper (windowWidth/375*size), ☐ Safe area for massive headers, ☐ Reduced motion stops marquees","--bg: #09090B, --fg: #FAFAFA, --muted: #27272A, --muted-fg: #A1A1AA, --accent: #DFE104, --accent-fg: #000000, --border: #3F3F46, --radius: 0px, --border-width: 2px, --shadow: none, --marquee-speed: 5000ms, --press-duration: 100ms, --font: Space Grotesk or Inter"
|
||||
75,Flat Design Mobile (Touch-First),Mobile,"flat, 2D, no shadow, color blocking, geometric, bold, poster, icon, touch-first, minimal, clean, tailored, cross-platform","Blue #3B82F6, Emerald #10B981","Background #FFFFFF, Surface #F3F4F6, Text #111827, Amber #F59E0B, Border #E5E7EB","Immediate press feedback (scale 0.97, no delay), color section blocking (full-width contrasting View), zero elevation/shadow, solid icon containers (colored squares/circles), geometric low-opacity shape overlays, bottom tabs solid fill (no floating)","Cross-platform apps (iOS+Android parity), information-dense dashboards, system UI, brand illustration, onboarding flows, marketing pages, icon design","Ultra-premium contexts needing depth/shadow, dark-mode-first products, contexts where flat design reads as unfinished or sterile",✓ Full,◐ Partial (Dark mode via color swap only),⚡ Excellent (no GPU effects),✓ WCAG AA (large bold type helps),✓ Mobile-First,✓ High,"React Native 10/10, Expo 10/10, NativeWind 10/10, Flutter 9/10, SwiftUI 9/10",2010s–2020s Flat Mobile,Low,"Design a Flat Mobile app. NO shadows (shadowOpacity: 0, elevation: 0). Color creates all hierarchy. Sections: full-width View blocks alternating contrasting bg colors (Blue Hero → White Content → Gray Block). Buttons: solid #3B82F6, borderRadius 8, height 56. Cards: backgroundColor #FFFFFF (on gray bg) or #DBEAFE (blue tint) — no shadow. Text: fontWeight 800 letterSpacing -0.5 (heads), 600 (sub), 400 (body). Inputs: #F3F4F6 bg, focused: borderWidth 2 borderColor #3B82F6. Icons: Lucide strokeWidth 2.5 inside solid colored square/circle. Press feedback: scale 0.97 Pressable. Use position absolute low-opacity geometric shapes (circles, rotated squares) as background decoration.","shadowOpacity: 0, elevation: 0, borderRadius: 6/12/999, height: 48 minimum touch targets, spacing: 4/8/16/24/32/48 system, backgroundColor (section blocking), Pressable scale: pressed ? 0.97 : 1, fontWeight: '800' heads / '600' sub / '400' body, letterSpacing: -0.5 heads / 1 labels, textTransform: 'uppercase' labels, strokeWidth={2.5} icons, borderWidth: 3/4 for featured CTAs","☐ Zero elevation AND shadowOpacity on all elements, ☐ Color-blocking sections (not borders), ☐ All touch targets ≥ 48×48, ☐ No gradients on flat elements, ☐ Icons inside solid colored containers, ☐ Pressable scale feedback, ☐ Geometric shapes as bg decoration, ☐ Bold flat bottom tabs (no floating), ☐ Primary headlines much larger than body, ☐ 4pt spacing system throughout","--bg: #FFFFFF, --surface: #F3F4F6, --fg: #111827, --primary: #3B82F6, --secondary: #10B981, --accent: #F59E0B, --border: #E5E7EB, --radius-sm: 6px, --radius-md: 12px, --radius-pill: 999px, --shadow: none, --elevation: 0, --touch-target: 48px, --spacing: 4 8 16 24 32 48"
|
||||
76,Material You (MD3 Mobile),Mobile,"material design 3, md3, tonal surfaces, pills, soft curves, android, md3 easing, state layers, haptic, fab, google","Primary Violet #6750A4, Secondary Container #E8DEF8, Tertiary #7D5260","Surface #FFFBFE, On Surface #1C1B1F, Surface Container #F3EDF7, Outline #79747E","Tonal elevation (overlay colors instead of strong shadows), pill-shaped buttons and chips (borderRadius 999), emphasized easing Easing.bezier(0.2,0,0,1), state layers (pressed overlays 10–15% opacity), Reanimated-filled label float for inputs, HapticFeedback on FAB/toggles","Android ecosystem apps, cross-platform productivity tools, MD3-based admin panels, data-heavy back-office UI with Material UI","Ultra-minimal brutalist brands, terminal/hacker aesthetics, monochrome editorial apps",✓ Full,✓ Full,⚠ Good (requires gradients and overlays),✓ WCAG AA (with MD3 token checks),✓ Mobile-First,✓ High,"React Native 9/10, Expo 10/10, React Native Paper 9/10","Material Design 3",Medium,"Design a Material You (MD3) mobile app. Use #FFFBFE background, #6750A4 primary, #E8DEF8 secondary container, #F3EDF7 surface container. All interactive elements are pill-shaped (borderRadius: 999). Buttons use Pressable with scale: 0.95 on press and state-layer overlays (black 10% or primary 12%). Inputs use filled M3 style: background #E7E0EC with floating label animation on focus. Elevation is tonal (layering containers) plus light shadow/elevation on Android. Animations use emphasized easing (0.2,0,0,1) at 100–400ms. FABs are tertiary-colored rounded squares/circles with level 3 elevation.","borderRadius: 999 (buttons/chips), containerRadius: 16–28, backgroundColor: '#FFFBFE', colorPrimary: '#6750A4', colorSecondaryContainer: '#E8DEF8', colorSurfaceContainer: '#F3EDF7', outlineColor: '#79747E', Pressable state-layer overlay (opacity 0.1–0.15), Easing.bezier(0.2,0,0,1), HapticFeedback.impactMedium on FAB, floating label using Reanimated translateY/scale","☐ MD3 color tokens applied (background/surface/container), ☐ All CTAs are pill-shaped, ☐ State-layer overlays instead of opacity 0.5 hacks, ☐ Emphasized easing used for all animations, ☐ Floating label inputs implemented, ☐ FAB uses tertiary color with correct elevation, ☐ Safe areas respected for organic shapes, ☐ No pure white background, ☐ No harsh box-shadows (ambient only)","--md3-bg: #FFFBFE, --md3-on-surface: #1C1B1F, --md3-primary: #6750A4, --md3-on-primary: #FFFFFF, --md3-secondary-container: #E8DEF8, --md3-on-secondary-container: #1D192B, --md3-tertiary: #7D5260, --md3-surface-container: #F3EDF7, --md3-outline: #79747E, --radius-pill: 999px, --easing-emphasized: cubic-bezier(0.2,0,0,1)"
|
||||
77,Neo Brutalism (Mobile),Mobile,"neo brutalism, pop art, stickers, thick borders, cream background, hot red, vivid yellow, soft violet, hard offset shadow, mechanical press, collage","Cream #FFFDF5, Hot Red #FF6B6B, Vivid Yellow #FFD93D","Soft Violet #C4B5FD, Pure Black #000000, White #FFFFFF","Thick 4px black borders on all major elements, hard offset shadows (4–8px, no blur), mechanical press: translateX/Y equal to shadow offset, slightly rotated cards/badges (-2deg/2deg), high-saturation color blocking, spring/linear animations only","Creative tools, collab platforms, Gen Z marketing & e-commerce, portfolio sites, sticker-book style content apps","Serious enterprise apps, conservative industries, sober fintech, accessibility-first contexts (must tune contrast)",✓ Light-first,✗ Dark,⚠ Moderate (shadows + transforms),⚠ Requires careful contrast tuning,✓ Mobile-First,✓ High,"React Native 10/10, Expo 10/10, NativeWind 9/10",2020s Neo-Brutalism,High,"Design a Mobile Neo-Brutalist app. Background: Cream #FFFDF5. All content blocks: white or violet with borderWidth 4 borderColor #000. Shadows are solid offset blocks (no blur) using an extra View behind offset by 4px or 8px. Typography: Space Grotesk Bold/Black only (700–900). Buttons: 56px tall, 4px border, 0 radius; press animation translates button to cover the shadow. Cards slightly rotated (-1deg, 2deg). Colors: Hot Red #FF6B6B for primary, Yellow #FFD93D for focus/badges, Soft Violet #C4B5FD as tertiary. Animation: spring/linear only, no ease-out luxury motion.","borderWidth: 4 (primary), 2 (secondary), borderRadius: 0 or 999 (badges only), backgroundColor: '#FFFDF5', shadow implemented as offset View, transform: [{translateX:4},{translateY:4}] on PressIn, fontFamily: 'SpaceGrotesk-Bold', fontWeight: '700/900', transform: [{ rotate: '-1deg' }] on cards, padding: 20,"☐ 4px borders on major elements, ☐ Hard offset shadow implemented via extra View, ☐ Mechanical press hides shadow, ☐ Cream canvas background, ☐ Pop-art color palette used, ☐ Cards/badges slightly rotated, ☐ No gradients or soft shadows, ☐ Only bold/black type weights, ☐ Badges slapped with absolute positioning, ☐ Anti-patterns (no subtle gray, no blur) avoided","--bg: #FFFDF5, --ink: #000000, --accent-primary: #FF6B6B, --accent-secondary: #FFD93D, --accent-muted: #C4B5FD, --white: #FFFFFF, --border-primary: 4px solid #000000, --shadow-offset-small: 4px, --shadow-offset-medium: 8px, --radius: 0px, --radius-pill: 999px, --font: Space Grotesk"
|
||||
78,Bold Typography (Mobile Poster),Mobile,"bold typography, editorial, poster, broadsheet, vermillion, negative space, edge-to-edge type, underline CTA, near-black, warm white","Near Black #0A0A0A, Warm White #FAFAFA","Muted #1A1A1A, Secondary Text #737373, Accent Vermillion #FF3D00, Border #262626","Hero headlines 48–72px (5:1 vs body size), tight tracking (-1.5px), edge-to-edge type, massive vertical spacing (60px+), underline CTAs (2–3px accent line), instant 200ms transitions (no bounce), strictly 0px radius containers, color shifts for active state instead of elevation","Creative brand heroes, reading-focused apps, event/exhibition pages, editorial mobile experiences, landing hero sections","Utility dashboards, kids apps, playful consumer products, contexts needing many icons or heavy imagery",✓ Dark Mode Primary,◐ Light sections optional,⚡ Excellent,✓ Contrast 18:1 achievable,✓ Mobile-First,✓ High,"React Native 10/10, Expo 10/10",Editorial 2020s,Medium,"Design a Bold Typography mobile screen. Background #0A0A0A, text #FAFAFA, accent #FF3D00. Use Inter Tight/Inter 600+ for all type; JetBrains Mono for labels. Headline: 56–72px, tracking -1.5, lineHeight 1.1, full-bleed width with slight bleed off-screen. Body: 16–18px, leading 1.6. Buttons: underline CTA (accent text + 2px underline block), or inverted box with 0 radius. No shadows, no rounded corners. Layout: single column, paddingHorizontal 24, vertical gaps 64 between sections. Animation: 200ms, Easing.bezier(0.25,0,0,1), slight slide-up 10px + fade on mount.","backgroundColor: '#0A0A0A', color: '#FAFAFA', accent: '#FF3D00', borderColor: '#262626', borderRadius: 0, paddingHorizontal: 24, headline style: fontSize:56–72, fontWeight:'700/800', letterSpacing:-1.5, lineHeight:1.1*fontSize, body: fontSize:16–18, lineHeight:1.6*fontSize, underline CTA: 2–3px height View under text, transition: 200ms cubic-bezier(0.25,0,0,1)","☐ H1 at least 4–5× body size, ☐ All containers 0 radius, ☐ Underline CTA pattern used, ☐ Large vertical gaps between sections, ☐ No shadows or soft corners, ☐ Accent used only for interaction, ☐ Text bleeds to/over screen edges, ☐ Animation timings 200ms, ☐ Accessible contrast ≥ 18:1, ☐ Body text never below 16px","--bg: #0A0A0A, --fg: #FAFAFA, --muted: #1A1A1A, --muted-fg: #737373, --accent: #FF3D00, --accent-fg: #0A0A0A, --border: #262626, --font-primary: Inter Tight, --font-display: Playfair Display Italic, --font-mono: JetBrains Mono"
|
||||
79,Academia (Scholarly Mobile),Mobile,"academia, library, mahogany, parchment, brass, crimson, serif, drop cap, arch-top, vignette, leather, scholarly, tactile","Mahogany #1C1714, Oak #251E19","Parchment #E8DFD4, Worn Leather #3D332B, Faded Ink #9C8B7A, Brass #C9A962, Library Crimson #8B2635","Deep mahogany backgrounds, oak surface cards, brass accented CTAs, arch-top hero/imagery, heavy vignette overlays, sepia-tinted images, drop caps with brass Cinzel, Roman numeral volume headings, slow timing-based animations (Easing.out poly(4)), zero neon or modern tech cues","Knowledge management apps, deep reading tools, ritual-heavy personal brands, lore-heavy RPG/roleplay apps, culture-specific community platforms","Hyper-modern tech dashboards, neon/glassmorphism, playful Gen Z branding",✓ Dark Rich,◐ Light parchment sections,⚠ Moderate (vignette + shadows),✓ Legible (serif optimized),◐ Mobile-First,◐ Medium,"React Native 9/10, Expo 10/10",Timeless Scholarly,High,"Design a Scholarly Academia mobile app. Background #1C1714 (mahogany), alt surfaces #251E19 (oak), text #E8DFD4 (parchment). Accent brass #C9A962 for CTAs + borders; crimson #8B2635 for wax seals. Typography: Cormorant Garamond (headings), Crimson Pro (body), Cinzel (labels/overlines). Use arch-top hero containers (borderTopRadius 100). Cards: oak bg, 1px wood-grain border. Inputs: worn-leather background, brass focus border. Global vignette overlay and ornate brass dividers (Unicode glyph + gradient line). Animations: no spring, only Timing with Easing.out(Easing.poly(4)).","backgroundColor: '#1C1714', altSurface: '#251E19', textColor: '#E8DFD4', mutedBg: '#3D332B', borderColor: '#4A3F35', brass: '#C9A962', crimson: '#8B2635', borderRadius: 4 (default), archTopRadius: 100 for hero, shadowOpacity:0.4 shadowRadius:6 elevation:8 for cards, textShadow on headings, vignette overlay via LinearGradient","☐ Mahogany/oak/parchment palette applied, ☐ Brass used on all tappable items, ☐ Arch-top imagery used in hero/cards, ☐ Drop caps & Roman numerals used, ☐ Vignette overlay present, ☐ No sans-serif body fonts, ☐ No neon/bright modern colors, ☐ Animations use non-spring timing, ☐ Inputs use worn-leather style, ☐ Wax seal badges implemented","--bg: #1C1714, --bg-alt: #251E19, --fg: #E8DFD4, --muted: #3D332B, --muted-fg: #9C8B7A, --border: #4A3F35, --accent-brass: #C9A962, --accent-crimson: #8B2635, --radius: 4px, --arch-radius: 100px, --shadow-card: 0 4px 6px rgba(0,0,0,0.4), --font-heading: Cormorant Garamond, --font-body: Crimson Pro, --font-label: Cinzel"
|
||||
80,Cyberpunk Mobile HUD,Mobile,"cyberpunk, neon, glitch, chamfered, orbitron, jetbrains, scanlines, crt, hud, matrix, military, decker","Void #0A0A0F, Card #12121A","Neon Green #00FF88, Neon Magenta #FF00FF, Cyber Cyan #00D4FF, Neutral Text #E0E0E0, Alert Red #FF3366, Border #2A2A3A","Deep void background with neon radiance, chamfered 45° corners via SVG/Skia, scanline overlay, CRT flicker opacity oscillation, glitch animations (translateX ±2), neon pulses around buttons, HUD corner brackets, terminal prompt text inputs, heavy use of blurView holographic panels","Gaming dashboards, crypto/cyberpunk apps, sci-fi companion tools, hacker OS skins, data-heavy monitoring HUDs","Serious enterprise, health/finance requiring calm trust, minimal editorial apps",✗ Light,✓ Dark-only,⚠ Moderate–Heavy (Skia/blur/animations),⚠ Requires careful reduced-motion handling,✓ Mobile-First HUD,✓ High,"React Native 10/10, Skia 9/10, Expo 10/10",Cyber-Noir,High,"Design a Cyberpunk mobile HUD. Background #0A0A0F, card #12121A. Accents: #00FF88 (primary), #FF00FF, #00D4FF. Typography: Orbitron for headings, JetBrains Mono for data. All shapes use chamfered corners via SVG or Skia clipPath. Buttons: neon glow shadows, scale 0.98 + haptic on press, optional glitch jitter on active. Global scanline overlay (semi-transparent horizontal lines) and CRT flicker (root opacity 0.98–1). Inputs: prompt style with '>' in accent, custom blinking block cursor. HUD cards use corner brackets and subtle gradients.","backgroundColor: '#0A0A0F', cardBg: '#12121A', accent: '#00FF88', accent2: '#FF00FF', accent3: '#00D4FF', borderColor: '#2A2A3A', destructive: '#FF3366', borderRadius: 0, chamfer via SVG path, shadowColor accent with animated radius, scanline overlay View pointerEvents='none', withRepeat glitch translateX [-2,2,0], Easing.steps(2)","☐ Chamfered corners used instead of radius, ☐ Scanline & CRT flicker implemented, ☐ Orbitron + JetBrains Mono typography, ☐ Neon glow shadows on primary buttons, ☐ Glitch animation on active states, ☐ Prompt-style inputs with custom cursor, ☐ HUD corner brackets implemented, ☐ Safe-area system status bar styled, ☐ Reduced motion disables glitch/flicker, ☐ Icons configured with Lucide accent color","--bg: #0A0A0F, --card: #12121A, --fg: #E0E0E0, --muted: #1C1C2E, --accent: #00FF88, --accent2: #FF00FF, --accent3: #00D4FF, --border: #2A2A3A, --destructive: #FF3366, --radius: 0px, --font-heading: Orbitron, --font-body: JetBrains Mono"
|
||||
81,Bitcoin DeFi (Mobile),Mobile,"web3, bitcoin, defi, digital gold, fintech, wallet, orange, glassmorphism, gradient, blur, holographic, trust, precision","Bitcoin Orange #F7931A, Burnt Orange #EA580C, Digital Gold #FFD600","Void #030304, Dark Matter #0F1115, Pure Light #FFFFFF, Stardust #94A3B8, Border Dim rgba(30,41,59,0.2)","Deep void + dark matter surfaces, Bitcoin orange/gold gradients for CTAs, pill buttons with glowing shadows, glassmorphic BlurView nav, monospace data rows, gradient text balances + masked orange-gold, pulsing status indicators and vertical ledger timelines, ultra-thin borders, high-precision typography","DeFi dashboards, wallets, NFT marketplaces, Web3 social, metaverse utilities, high-tech fintech brands","Playful casual apps, low-tech brands, ultra-minimal editorial apps",✗ Light,✓ Dark-only,⚠ Moderate (gradients+blur),✓ WCAG AA with care,✓ Mobile-First,✓ High,"React Native 10/10, Expo 10/10, Reanimated 10/10",Fintech/Web3,High,"Design a Bitcoin DeFi mobile app. Background #030304, cards #0F1115, text #FFFFFF, muted #94A3B8. Primary CTA: LinearGradient #EA580C→#F7931A with orange glow shadow. Typography: Space Grotesk Bold for headings, Inter for body, JetBrains Mono for prices/hashes. Use BlurView (intensity 20) for nav bars and floating panels. Cards as 'blocks' with hairline borders and light orange glow on active. Use grid background (low-opacity 50px grid). Gradient text for key balances via MaskedView and LinearGradient orange→gold. Status indicators pulse using Reanimated. Ledger timelines drawn as vertical gradient line with pulsing dots.","backgroundColor: '#030304', cardBg: '#0F1115', textColor: '#FFFFFF', mutedText: '#94A3B8', borderColor: 'rgba(30,41,59,0.2)', accentBitcoin: '#F7931A', accentBurnt: '#EA580C', accentGold: '#FFD600', borderRadius: 24 for cards, radiusPill: 999 for buttons, BlurView intensity 20, LinearGradient on CTAs, shadowColor '#F7931A' shadowRadius up to 10, JetBrains Mono for numeric text","☐ Void/dark-matter palette applied, ☐ Bitcoin orange/gold gradient buttons, ☐ BlurView nav implemented, ☐ Monospace for numeric data, ☐ Hairline borders on blocks, ☐ Gradient text on balances, ☐ Pulsing network status indicators, ☐ Ledger vertical timeline, ☐ Haptics on money actions, ☐ SafeArea + FlashList for heavy lists","--bg-void: #030304, --bg-surface: #0F1115, --fg: #FFFFFF, --fg-muted: #94A3B8, --border-dim: rgba(30,41,59,0.2), --accent-bitcoin: #F7931A, --accent-burnt: #EA580C, --accent-gold: #FFD600, --radius-card: 24px, --radius-pill: 999px, --blur-intensity: 20, --font-heading: Space Grotesk, --font-body: Inter, --font-mono: JetBrains Mono"
|
||||
82,Claymorphism (Mobile),Mobile,"claymorphism, clay, 3d, soft, bubbly, candy, playful, rounded, squish, tactile, inflate, silicone, haptic, spring","Vivid Violet #7C3AED, Hot Pink #DB2777","Canvas #F4F1FA, Soft Charcoal #332F3A, Emerald #10B981, Amber #F59E0B, Lavender-Gray #635F69","Multi-layer shadow stacks (nested View) to simulate clay depth, LinearGradient #A78BFA→#7C3AED buttons, borderRadius 40–50 outer / 32 cards / 20 buttons, Reanimated spring squish (scale 0.92 on press), BlurView glass-clay hybrid cards, floating blobs with slow ±20px drift, Haptics Light on every press","Children education apps, teen social products, crypto gamification, creative tools, brand mascot-led apps","Serious enterprise, high-density data, editorial reading apps, fintech trust signals",✓ Light,⚠ Dark (adjusted),⚠ Moderate–Heavy (shadows+blur),✓ WCAG AA (careful),✓ Mobile-First (thumb zone),✓ High,"React Native 10/10, Reanimated 10/10, Expo 10/10",Consumer/Education,High,"Design a high-fidelity Claymorphism mobile app. Background #F4F1FA (cool lavender-white, never pure white). Primary CTA: LinearGradient #A78BFA to #7C3AED, borderRadius 20, height 56. Cards: borderRadius 32, backgroundColor rgba(255,255,255,0.7) with BlurView. Multi-layer shadow: outer offset(12,12) rgba(160,150,180,0.2) + highlight offset(-8,-8) white. Typography: Nunito Black 900 for headings (48px hero, 32px section, 22px card), DM Sans Medium 500 for body 16px. Spring animations: scale 0.92 on press, spring back damping 10. Background blobs drift ±20px over 8–10s. Bento 2-column grid with hero card spanning full width. Haptics.impactAsync Light on every button press.","backgroundColor: '#F4F1FA', cardBg: 'rgba(255,255,255,0.7)', textPrimary: '#332F3A', textMuted: '#635F69', accentPrimary: '#7C3AED', accentSecondary: '#DB2777', success: '#10B981', warning: '#F59E0B', radiusOuter: 50, radiusCard: 32, radiusButton: 20, shadowStack: 'nested View', gradientButton: ['#A78BFA', '#7C3AED'], springDamping: 10","☐ Background uses #F4F1FA (no pure white), ☐ Multi-layer clay shadow stack applied, ☐ Cards use blurred glass-clay hybrid, ☐ Buttons squish to scale 0.92 on press, ☐ Spring physics on all interactions, ☐ Nunito Black for headings, ☐ Background blobs drifting, ☐ Haptics on every press, ☐ Nested border radius (card 32, inner 24), ☐ Bento layout with hero span","--bg: #F4F1FA, --card-bg: rgba(255,255,255,0.7), --text: #332F3A, --muted: #635F69, --accent: #7C3AED, --accent2: #DB2777, --success: #10B981, --warning: #F59E0B, --radius-outer: 50px, --radius-card: 32px, --radius-button: 20px, --font-heading: Nunito Black, --font-body: DM Sans"
|
||||
83,Enterprise SaaS (Mobile),Mobile,"enterprise, saas, b2b, professional, indigo, violet, gradient, polished, trustworthy, clean, approachable, spring, haptic","Indigo #4F46E5, Violet #7C3AED","Slate 50 #F8FAFC, White #FFFFFF, Slate 900 #0F172A, Slate 500 #64748B, Emerald #10B981, Slate 200 #E2E8F0","Indigo→Violet gradient primary CTAs + active tab highlights, colored card shadows rgba(79,70,229,0.08), pill buttons or 12pt radius, full-width CTA at screen bottom, spring press scale 0.97, floating label inputs with animated focus border, skeletal loading pulses (Indigo/Slate tint), Bottom Sheets with drag dismiss, swipe-to-action list cards, scroll-linked title collapse","B2B backend management, productivity tools, government and finance mobile apps, SaaS companion apps, enterprise dashboards","Pure consumer entertainment, Gen-Z youth apps, gaming UI, ultra-minimal editorial",✓ Light,✓ Dark-ready (token inversion),✓ Performant,✓ WCAG AA,✓ Mobile-First (Safe Area strict),✓ High,"React Native 10/10, Reanimated 10/10, NativeWind 9/10",Enterprise/SaaS,High,"Design a Modern Enterprise SaaS mobile app. Background #F8FAFC, surfaces #FFFFFF, primary #4F46E5 (Indigo), secondary #7C3AED (Violet). Typography: Plus Jakarta Sans, ExtraBold 800 for screen titles, Bold 700 for section headers, SemiBold 600 for buttons, Regular 400 for body. Line height 1.1–1.2 for titles, 1.4–1.5 for body. Primary button: full-width, LinearGradient Indigo→Violet, pill-shaped or radius 12, scale 0.95 on press with medium haptic. Cards: white bg, 16pt radius, hairline border, shadow rgba(79,70,229,0.08). Inputs: white bg, 8pt radius, floating label, Indigo border on focus. Bottom Tab Navigation (3–5 items), gradient active tab icon. Screen padding 16–20pt. Vertical rhythm 24pt between sections, 12pt between items. Shared Element Transition for hero cards opening to detail.","backgroundColor: '#F8FAFC', surfaceBg: '#FFFFFF', textPrimary: '#0F172A', textMuted: '#64748B', primary: '#4F46E5', secondary: '#7C3AED', success: '#10B981', border: '#E2E8F0', radiusCard: 16, radiusButton: 999, radiusInput: 8, shadowCard: 'rgba(79,70,229,0.08)', gradientPrimary: ['#4F46E5', '#7C3AED'], screenPadding: 20","☐ Background #F8FAFC applied, ☐ Indigo→Violet gradient on primary CTA, ☐ Colored card shadows (not gray), ☐ Plus Jakarta Sans typography, ☐ Floating label inputs with Indigo focus, ☐ Scale 0.97 press with haptic Medium, ☐ Bottom Tab Navigation implemented, ☐ Safe Area strict compliance, ☐ Skeletal loading placeholders, ☐ Reduced Motion fallback","--bg: #F8FAFC, --surface: #FFFFFF, --text: #0F172A, --muted: #64748B, --primary: #4F46E5, --secondary: #7C3AED, --success: #10B981, --border: #E2E8F0, --radius-card: 16px, --radius-pill: 999px, --radius-input: 8px, --shadow-card: rgba(79,70,229,0.08), --font: Plus Jakarta Sans"
|
||||
84,Sketch Hand-Drawn (Mobile),Mobile,"sketch, hand-drawn, handwriting, wobbly, imperfect, paper, kalam, organic, collage, post-it, tape, offset shadow, scribble","Red Marker #FF4D4D, Pencil Black #2D2D2D","Warm Paper #FDFBF7, Old Paper #E5E0D8, Blue Ballpoint #2D5DA1, Post-it Yellow #FFF9C4","Wobbly borderRadius (unique per corner: 15/25/20/10), borderWidth 2–3 solid/dashed, hard offset shadow via rear View (4px,4px) #2D2D2D, Kalam Bold headings, PatrickHand Regular body, slight rotation (-1deg/1deg) on cards, absolute SVG scribble overlays (arrows/tape/tacks), jiggle -2deg↔2deg on error, LayoutAnimation spring on layout changes, Haptics on press, paper texture repeating background","Low-fidelity prototyping, creative brands, children/picturebook apps, education tools, journaling apps, gamified puzzles","Enterprise dashboards, high-density data tables, fintech precision tools, medical or legal apps",✓ Light,⚠ Dark (requires texture inversion),✓ Lightweight,⚠ Moderate (small/muted text risk),✓ Mobile-First (wobbly touch targets 48x48),✗ Low-Conversion,"React Native 10/10, Reanimated 9/10, Expo 9/10",Creative/Education,Medium,"Design a Hand-Drawn (Sketch) mobile app. Background #FDFBF7 (warm paper texture). Typography: Kalam Bold for headings (high weight, felt-tip style), PatrickHand Regular for body (human but legible). Colors: Pencil Black #2D2D2D for all text and borders, Red Marker #FF4D4D for accents, Blue Ballpoint #2D5DA1for input focus. Cards: white background, wobbly corner radii (e.g., 15/25/20/10), borderWidth 3, rotate -1deg or +1deg. Hard offset shadow implemented as a second View behind the card offset 4px right and 4px down. Buttons: Post-it yellow #FFF9C4 for primary CTA, press state shifts the button (translateX 4, translateY 4) to cover the shadow. Inputs: PatrickHand font, wobbly border, focus changes to Blue Ballpoint. Add absolute SVG tape and tack decorations. Error: jiggle animation -2deg to +2deg. All touch targets minimum 48x48.","backgroundColor: '#FDFBF7', cardBg: '#FFFFFF', textPrimary: '#2D2D2D', accentRed: '#FF4D4D', accentBlue: '#2D5DA1', accentYellow: '#FFF9C4', border: '#2D2D2D', shadowView: 'offset 4px 4px #2D2D2D', wobblyRadius: [15,25,20,10], fontHeading: 'Kalam-Bold', fontBody: 'PatrickHand-Regular'","☐ Warm paper background texture applied, ☐ Kalam Bold headings, ☐ Wobbly corner radii on all cards, ☐ Hard offset shadow View (not blur), ☐ Cards slightly rotated, ☐ Button press shifts to cover shadow, ☐ SVG tape/tack decorations, ☐ PatrickHand for inputs, ☐ Jiggle error animation, ☐ Minimum 48x48 touch targets","--bg: #FDFBF7, --text: #2D2D2D, --accent-red: #FF4D4D, --accent-blue: #2D5DA1, --postit: #FFF9C4, --border-width: 3px, --shadow-offset: 4px 4px, --font-heading: Kalam Bold, --font-body: Patrick Hand, --rotation-card: -1deg to 1deg"
|
||||
85,Neumorphism (Mobile),Mobile,"neumorphism, soft ui, dual shadow, extruded, inset, clay surface, monochromatic, cool grey, haptic, ceramic, physical, depth","Accent Violet #6C63FF, Clay Base #E0E5EC","Text Dark #3D4852, Text Muted #6B7280, Shadow Light rgba(255,255,255,0.6), Shadow Dark rgba(163,177,198,0.7), Inset Background #D1D9E6","Full-screen #E0E5EC base, dual-layer shadow via nested View (light top-left + dark bottom-right), extruded convex resting state, inset concave pressed/input state, Reanimated scale 0.97 on press, shadow opacity interpolates 1→0.4 on press, Haptics Light on every interaction, 8pt grid, no blur shadows (no shadowRadius blend), nested depth (extruded card contains inset icon slot)","Minimal hardware controls, smart home apps, aesthetic utility tools, health monitors, brand showcase pages","High-density data, bright multi-color apps, apps needing strong visual hierarchy via color, dark-mode-only products",✓ Light-only,✗ Dark (breaks material metaphor),✓ Lightweight,⚠ Moderate (low-contrast risk),✓ Mobile-First,✗ Low-Conversion,"React Native 10/10, react-native-shadow-2 9/10, Reanimated 9/10",Tools/Lifestyle,Medium,"Design a Neumorphism (Soft UI) mobile app. Entire background is a single color #E0E5EC (Cool Clay). No other background colors. Dual shadows: outer dark shadowColor rgba(163,177,198,0.7) offset(6,6) radius 10 + outer light #FFFFFF offset(-6,-6) radius 10 using nested View or react-native-shadow-2. Extruded (convex) for resting buttons and cards. Inset (concave) for inputs and pressed states. Buttons: height 56, borderRadius 16, scale 0.97 on press with shadow opacity→0.4, Haptics.impactAsync Light. Cards: padding 24, borderRadius 32, nested inner icon container uses inset style. Inputs: height 50, borderRadius 16, backgroundColor #E0E5EC (NOT white), inset depth effect, focus borderColor #6C63FF width 1.5. Typography: Plus Jakarta Sans Bold or System. Heading 24–32pt, body 16pt, caption 12pt, letterSpacing -0.5 for headings. Animation: 250ms Bezier(0.4,0,0.2,1). No black shadows, no pure white backgrounds.","backgroundColor: '#E0E5EC', textPrimary: '#3D4852', textMuted: '#6B7280', accent: '#6C63FF', shadowLight: 'rgba(255,255,255,0.6)', shadowDark: 'rgba(163,177,198,0.7)', insetBg: '#D1D9E6', radiusCard: 32, radiusButton: 16, radiusPill: 999, shadowOffset: 6, shadowRadius: 10","☐ Single #E0E5EC base applied across all screens, ☐ Dual shadow (light+dark) implemented via nested View, ☐ Extruded resting state on cards/buttons, ☐ Inset concave state on inputs, ☐ Scale 0.97 press + shadow opacity interpolation, ☐ Haptics Light on all presses, ☐ No black shadows or white backgrounds, ☐ Nested depth pattern (extruded→inset), ☐ Accent #6C63FF on active/focus only, ☐ 8pt grid spacing","--bg: #E0E5EC, --text: #3D4852, --muted: #6B7280, --accent: #6C63FF, --shadow-light: rgba(255,255,255,0.6), --shadow-dark: rgba(163,177,198,0.7), --inset-bg: #D1D9E6, --radius-card: 32px, --radius-button: 16px, --font: Plus Jakarta Sans or System"
|
||||
|
Can't render this file because it contains an unexpected character in line 77 and column 1866.
|
|
|
@ -1,74 +0,0 @@
|
|||
No,Font Pairing Name,Category,Heading Font,Body Font,Mood/Style Keywords,Best For,Google Fonts URL,CSS Import,Tailwind Config,Notes
|
||||
1,Classic Elegant,"Serif + Sans",Playfair Display,Inter,"elegant, luxury, sophisticated, timeless, premium, editorial","Luxury brands, fashion, spa, beauty, editorial, magazines, high-end e-commerce","https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Playfair+Display:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Playfair+Display:wght@400;500;600;700&display=swap');","fontFamily: { serif: ['Playfair Display', 'serif'], sans: ['Inter', 'sans-serif'] }","High contrast between elegant heading and clean body. Perfect for luxury/premium."
|
||||
2,Modern Professional,"Sans + Sans",Poppins,Open Sans,"modern, professional, clean, corporate, friendly, approachable","SaaS, corporate sites, business apps, startups, professional services","https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&family=Poppins:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&family=Poppins:wght@400;500;600;700&display=swap');","fontFamily: { heading: ['Poppins', 'sans-serif'], body: ['Open Sans', 'sans-serif'] }","Geometric Poppins for headings, humanist Open Sans for readability."
|
||||
3,Tech Startup,"Sans + Sans",Space Grotesk,DM Sans,"tech, startup, modern, innovative, bold, futuristic","Tech companies, startups, SaaS, developer tools, AI products","https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&family=Space+Grotesk:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&family=Space+Grotesk:wght@400;500;600;700&display=swap');","fontFamily: { heading: ['Space Grotesk', 'sans-serif'], body: ['DM Sans', 'sans-serif'] }","Space Grotesk has unique character, DM Sans is highly readable."
|
||||
4,Editorial Classic,"Serif + Serif",Cormorant Garamond,Libre Baskerville,"editorial, classic, literary, traditional, refined, bookish","Publishing, blogs, news sites, literary magazines, book covers","https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Libre+Baskerville:wght@400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@400;500;600;700&family=Libre+Baskerville:wght@400;700&display=swap');","fontFamily: { heading: ['Cormorant Garamond', 'serif'], body: ['Libre Baskerville', 'serif'] }","All-serif pairing for traditional editorial feel."
|
||||
5,Minimal Swiss,"Sans + Sans",Inter,Inter,"minimal, clean, swiss, functional, neutral, professional","Dashboards, admin panels, documentation, enterprise apps, design systems","https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');","fontFamily: { sans: ['Inter', 'sans-serif'] }","Single font family with weight variations. Ultimate simplicity."
|
||||
6,Playful Creative,"Display + Sans",Fredoka,Nunito,"playful, friendly, fun, creative, warm, approachable","Children's apps, educational, gaming, creative tools, entertainment","https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&family=Nunito:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&family=Nunito:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Fredoka', 'sans-serif'], body: ['Nunito', 'sans-serif'] }","Rounded, friendly fonts perfect for playful UIs."
|
||||
7,Bold Statement,"Display + Sans",Bebas Neue,Source Sans 3,"bold, impactful, strong, dramatic, modern, headlines","Marketing sites, portfolios, agencies, event pages, sports","https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Source+Sans+3:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Source+Sans+3:wght@300;400;500;600;700&display=swap');","fontFamily: { display: ['Bebas Neue', 'sans-serif'], body: ['Source Sans 3', 'sans-serif'] }","Bebas Neue for large headlines only. All-caps display font."
|
||||
8,Wellness Calm,"Serif + Sans",Lora,Raleway,"calm, wellness, health, relaxing, natural, organic","Health apps, wellness, spa, meditation, yoga, organic brands","https://fonts.googleapis.com/css2?family=Lora:wght@400;500;600;700&family=Raleway:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Lora:wght@400;500;600;700&family=Raleway:wght@300;400;500;600;700&display=swap');","fontFamily: { serif: ['Lora', 'serif'], sans: ['Raleway', 'sans-serif'] }","Lora's organic curves with Raleway's elegant simplicity."
|
||||
9,Developer Mono,"Mono + Sans",JetBrains Mono,IBM Plex Sans,"code, developer, technical, precise, functional, hacker","Developer tools, documentation, code editors, tech blogs, CLI apps","https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap');","fontFamily: { mono: ['JetBrains Mono', 'monospace'], sans: ['IBM Plex Sans', 'sans-serif'] }","JetBrains for code, IBM Plex for UI. Developer-focused."
|
||||
10,Retro Vintage,"Display + Serif",Abril Fatface,Merriweather,"retro, vintage, nostalgic, dramatic, decorative, bold","Vintage brands, breweries, restaurants, creative portfolios, posters","https://fonts.googleapis.com/css2?family=Abril+Fatface&family=Merriweather:wght@300;400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Abril+Fatface&family=Merriweather:wght@300;400;700&display=swap');","fontFamily: { display: ['Abril Fatface', 'serif'], body: ['Merriweather', 'serif'] }","Abril Fatface for hero headlines only. High-impact vintage feel."
|
||||
11,Geometric Modern,"Sans + Sans",Outfit,Work Sans,"geometric, modern, clean, balanced, contemporary, versatile","General purpose, portfolios, agencies, modern brands, landing pages","https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Work+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Work+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Outfit', 'sans-serif'], body: ['Work Sans', 'sans-serif'] }","Both geometric but Outfit more distinctive for headings."
|
||||
12,Luxury Serif,"Serif + Sans",Cormorant,Montserrat,"luxury, high-end, fashion, elegant, refined, premium","Fashion brands, luxury e-commerce, jewelry, high-end services","https://fonts.googleapis.com/css2?family=Cormorant:wght@400;500;600;700&family=Montserrat:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Cormorant:wght@400;500;600;700&family=Montserrat:wght@300;400;500;600;700&display=swap');","fontFamily: { serif: ['Cormorant', 'serif'], sans: ['Montserrat', 'sans-serif'] }","Cormorant's elegance with Montserrat's geometric precision."
|
||||
13,Friendly SaaS,"Sans + Sans",Plus Jakarta Sans,Plus Jakarta Sans,"friendly, modern, saas, clean, approachable, professional","SaaS products, web apps, dashboards, B2B, productivity tools","https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { sans: ['Plus Jakarta Sans', 'sans-serif'] }","Single versatile font. Modern alternative to Inter."
|
||||
14,News Editorial,"Serif + Sans",Newsreader,Roboto,"news, editorial, journalism, trustworthy, readable, informative","News sites, blogs, magazines, journalism, content-heavy sites","https://fonts.googleapis.com/css2?family=Newsreader:wght@400;500;600;700&family=Roboto:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Newsreader:wght@400;500;600;700&family=Roboto:wght@300;400;500;700&display=swap');","fontFamily: { serif: ['Newsreader', 'serif'], sans: ['Roboto', 'sans-serif'] }","Newsreader designed for long-form reading. Roboto for UI."
|
||||
15,Handwritten Charm,"Script + Sans",Caveat,Quicksand,"handwritten, personal, friendly, casual, warm, charming","Personal blogs, invitations, creative portfolios, lifestyle brands","https://fonts.googleapis.com/css2?family=Caveat:wght@400;500;600;700&family=Quicksand:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Caveat:wght@400;500;600;700&family=Quicksand:wght@300;400;500;600;700&display=swap');","fontFamily: { script: ['Caveat', 'cursive'], sans: ['Quicksand', 'sans-serif'] }","Use Caveat sparingly for accents. Quicksand for body."
|
||||
16,Corporate Trust,"Sans + Sans",Lexend,Source Sans 3,"corporate, trustworthy, accessible, readable, professional, clean","Enterprise, government, healthcare, finance, accessibility-focused","https://fonts.googleapis.com/css2?family=Lexend:wght@300;400;500;600;700&family=Source+Sans+3:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Lexend:wght@300;400;500;600;700&family=Source+Sans+3:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Lexend', 'sans-serif'], body: ['Source Sans 3', 'sans-serif'] }","Lexend designed for readability. Excellent accessibility."
|
||||
17,Brutalist Raw,"Mono + Mono",Space Mono,Space Mono,"brutalist, raw, technical, monospace, minimal, stark","Brutalist designs, developer portfolios, experimental, tech art","https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&display=swap');","fontFamily: { mono: ['Space Mono', 'monospace'] }","All-mono for raw brutalist aesthetic. Limited weights."
|
||||
18,Fashion Forward,"Sans + Sans",Syne,Manrope,"fashion, avant-garde, creative, bold, artistic, edgy","Fashion brands, creative agencies, art galleries, design studios","https://fonts.googleapis.com/css2?family=Manrope:wght@300;400;500;600;700&family=Syne:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Manrope:wght@300;400;500;600;700&family=Syne:wght@400;500;600;700&display=swap');","fontFamily: { heading: ['Syne', 'sans-serif'], body: ['Manrope', 'sans-serif'] }","Syne's unique character for headlines. Manrope for readability."
|
||||
19,Soft Rounded,"Sans + Sans",Varela Round,Nunito Sans,"soft, rounded, friendly, approachable, warm, gentle","Children's products, pet apps, friendly brands, wellness, soft UI","https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Varela+Round&display=swap","@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Varela+Round&display=swap');","fontFamily: { heading: ['Varela Round', 'sans-serif'], body: ['Nunito Sans', 'sans-serif'] }","Both rounded and friendly. Perfect for soft UI designs."
|
||||
20,Premium Sans,"Sans + Sans",Satoshi,General Sans,"premium, modern, clean, sophisticated, versatile, balanced","Premium brands, modern agencies, SaaS, portfolios, startups","https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;700&display=swap');","fontFamily: { sans: ['DM Sans', 'sans-serif'] }","Note: Satoshi/General Sans on Fontshare. DM Sans as Google alternative."
|
||||
21,Vietnamese Friendly,"Sans + Sans",Be Vietnam Pro,Noto Sans,"vietnamese, international, readable, clean, multilingual, accessible","Vietnamese sites, multilingual apps, international products","https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@300;400;500;600;700&family=Noto+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@300;400;500;600;700&family=Noto+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { sans: ['Be Vietnam Pro', 'Noto Sans', 'sans-serif'] }","Be Vietnam Pro excellent Vietnamese support. Noto as fallback."
|
||||
22,Japanese Elegant,"Serif + Sans",Noto Serif JP,Noto Sans JP,"japanese, elegant, traditional, modern, multilingual, readable","Japanese sites, Japanese restaurants, cultural sites, anime/manga","https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@300;400;500;700&family=Noto+Serif+JP:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@300;400;500;700&family=Noto+Serif+JP:wght@400;500;600;700&display=swap');","fontFamily: { serif: ['Noto Serif JP', 'serif'], sans: ['Noto Sans JP', 'sans-serif'] }","Noto fonts excellent Japanese support. Traditional + modern feel."
|
||||
23,Korean Modern,"Sans + Sans",Noto Sans KR,Noto Sans KR,"korean, modern, clean, professional, multilingual, readable","Korean sites, K-beauty, K-pop, Korean businesses, multilingual","https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700&display=swap');","fontFamily: { sans: ['Noto Sans KR', 'sans-serif'] }","Clean Korean typography. Single font with weight variations."
|
||||
24,Chinese Traditional,"Serif + Sans",Noto Serif TC,Noto Sans TC,"chinese, traditional, elegant, cultural, multilingual, readable","Traditional Chinese sites, cultural content, Taiwan/Hong Kong markets","https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@300;400;500;700&family=Noto+Serif+TC:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+TC:wght@300;400;500;700&family=Noto+Serif+TC:wght@400;500;600;700&display=swap');","fontFamily: { serif: ['Noto Serif TC', 'serif'], sans: ['Noto Sans TC', 'sans-serif'] }","Traditional Chinese character support. Elegant pairing."
|
||||
25,Chinese Simplified,"Sans + Sans",Noto Sans SC,Noto Sans SC,"chinese, simplified, modern, professional, multilingual, readable","Simplified Chinese sites, mainland China market, business apps","https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@300;400;500;700&display=swap');","fontFamily: { sans: ['Noto Sans SC', 'sans-serif'] }","Simplified Chinese support. Clean modern look."
|
||||
26,Arabic Elegant,"Serif + Sans",Noto Naskh Arabic,Noto Sans Arabic,"arabic, elegant, traditional, cultural, RTL, readable","Arabic sites, Middle East market, Islamic content, bilingual sites","https://fonts.googleapis.com/css2?family=Noto+Naskh+Arabic:wght@400;500;600;700&family=Noto+Sans+Arabic:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Naskh+Arabic:wght@400;500;600;700&family=Noto+Sans+Arabic:wght@300;400;500;700&display=swap');","fontFamily: { serif: ['Noto Naskh Arabic', 'serif'], sans: ['Noto Sans Arabic', 'sans-serif'] }","RTL support. Naskh for traditional, Sans for modern Arabic."
|
||||
27,Thai Modern,"Sans + Sans",Noto Sans Thai,Noto Sans Thai,"thai, modern, readable, clean, multilingual, accessible","Thai sites, Southeast Asia, tourism, Thai restaurants","https://fonts.googleapis.com/css2?family=Noto+Sans+Thai:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+Thai:wght@300;400;500;700&display=swap');","fontFamily: { sans: ['Noto Sans Thai', 'sans-serif'] }","Clean Thai typography. Excellent readability."
|
||||
28,Hebrew Modern,"Sans + Sans",Noto Sans Hebrew,Noto Sans Hebrew,"hebrew, modern, RTL, clean, professional, readable","Hebrew sites, Israeli market, Jewish content, bilingual sites","https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+Hebrew:wght@300;400;500;700&display=swap');","fontFamily: { sans: ['Noto Sans Hebrew', 'sans-serif'] }","RTL support. Clean modern Hebrew typography."
|
||||
29,Legal Professional,"Serif + Sans",EB Garamond,Lato,"legal, professional, traditional, trustworthy, formal, authoritative","Law firms, legal services, contracts, formal documents, government","https://fonts.googleapis.com/css2?family=EB+Garamond:wght@400;500;600;700&family=Lato:wght@300;400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=EB+Garamond:wght@400;500;600;700&family=Lato:wght@300;400;700&display=swap');","fontFamily: { serif: ['EB Garamond', 'serif'], sans: ['Lato', 'sans-serif'] }","EB Garamond for authority. Lato for clean body text."
|
||||
30,Medical Clean,"Sans + Sans",Figtree,Noto Sans,"medical, clean, accessible, professional, healthcare, trustworthy","Healthcare, medical clinics, pharma, health apps, accessibility","https://fonts.googleapis.com/css2?family=Figtree:wght@300;400;500;600;700&family=Noto+Sans:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Figtree:wght@300;400;500;600;700&family=Noto+Sans:wght@300;400;500;700&display=swap');","fontFamily: { heading: ['Figtree', 'sans-serif'], body: ['Noto Sans', 'sans-serif'] }","Clean, accessible fonts for medical contexts."
|
||||
31,Financial Trust,"Sans + Sans",IBM Plex Sans,IBM Plex Sans,"financial, trustworthy, professional, corporate, banking, serious","Banks, finance, insurance, investment, fintech, enterprise","https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { sans: ['IBM Plex Sans', 'sans-serif'] }","IBM Plex conveys trust and professionalism. Excellent for data."
|
||||
32,Real Estate Luxury,"Serif + Sans",Cinzel,Josefin Sans,"real estate, luxury, elegant, sophisticated, property, premium","Real estate, luxury properties, architecture, interior design","https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=Josefin+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=Josefin+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { serif: ['Cinzel', 'serif'], sans: ['Josefin Sans', 'sans-serif'] }","Cinzel's elegance for headlines. Josefin for modern body."
|
||||
33,Restaurant Menu,"Serif + Sans",Playfair Display SC,Karla,"restaurant, menu, culinary, elegant, foodie, hospitality","Restaurants, cafes, food blogs, culinary, hospitality","https://fonts.googleapis.com/css2?family=Karla:wght@300;400;500;600;700&family=Playfair+Display+SC:wght@400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Karla:wght@300;400;500;600;700&family=Playfair+Display+SC:wght@400;700&display=swap');","fontFamily: { display: ['Playfair Display SC', 'serif'], sans: ['Karla', 'sans-serif'] }","Small caps Playfair for menu headers. Karla for descriptions."
|
||||
34,Art Deco,"Display + Sans",Poiret One,Didact Gothic,"art deco, vintage, 1920s, elegant, decorative, gatsby","Vintage events, art deco themes, luxury hotels, classic cocktails","https://fonts.googleapis.com/css2?family=Didact+Gothic&family=Poiret+One&display=swap","@import url('https://fonts.googleapis.com/css2?family=Didact+Gothic&family=Poiret+One&display=swap');","fontFamily: { display: ['Poiret One', 'sans-serif'], sans: ['Didact Gothic', 'sans-serif'] }","Poiret One for art deco headlines only. Didact for body."
|
||||
35,Magazine Style,"Serif + Sans",Libre Bodoni,Public Sans,"magazine, editorial, publishing, refined, journalism, print","Magazines, online publications, editorial content, journalism","https://fonts.googleapis.com/css2?family=Libre+Bodoni:wght@400;500;600;700&family=Public+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Libre+Bodoni:wght@400;500;600;700&family=Public+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { serif: ['Libre Bodoni', 'serif'], sans: ['Public Sans', 'sans-serif'] }","Bodoni's editorial elegance. Public Sans for clean UI."
|
||||
36,Crypto/Web3,"Sans + Sans",Orbitron,Exo 2,"crypto, web3, futuristic, tech, blockchain, digital","Crypto platforms, NFT, blockchain, web3, futuristic tech","https://fonts.googleapis.com/css2?family=Exo+2:wght@300;400;500;600;700&family=Orbitron:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Exo+2:wght@300;400;500;600;700&family=Orbitron:wght@400;500;600;700&display=swap');","fontFamily: { display: ['Orbitron', 'sans-serif'], body: ['Exo 2', 'sans-serif'] }","Orbitron for futuristic headers. Exo 2 for readable body."
|
||||
37,Gaming Bold,"Display + Sans",Russo One,Chakra Petch,"gaming, bold, action, esports, competitive, energetic","Gaming, esports, action games, competitive sports, entertainment","https://fonts.googleapis.com/css2?family=Chakra+Petch:wght@300;400;500;600;700&family=Russo+One&display=swap","@import url('https://fonts.googleapis.com/css2?family=Chakra+Petch:wght@300;400;500;600;700&family=Russo+One&display=swap');","fontFamily: { display: ['Russo One', 'sans-serif'], body: ['Chakra Petch', 'sans-serif'] }","Russo One for impact. Chakra Petch for techy body text."
|
||||
38,Indie/Craft,"Display + Sans",Amatic SC,Cabin,"indie, craft, handmade, artisan, organic, creative","Craft brands, indie products, artisan, handmade, organic products","https://fonts.googleapis.com/css2?family=Amatic+SC:wght@400;700&family=Cabin:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Amatic+SC:wght@400;700&family=Cabin:wght@400;500;600;700&display=swap');","fontFamily: { display: ['Amatic SC', 'sans-serif'], sans: ['Cabin', 'sans-serif'] }","Amatic for handwritten feel. Cabin for readable body."
|
||||
39,Startup Bold,"Sans + Sans",Clash Display,Satoshi,"startup, bold, modern, innovative, confident, dynamic","Startups, pitch decks, product launches, bold brands","https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Outfit', 'sans-serif'], body: ['Rubik', 'sans-serif'] }","Note: Clash Display on Fontshare. Outfit as Google alternative."
|
||||
40,E-commerce Clean,"Sans + Sans",Rubik,Nunito Sans,"ecommerce, clean, shopping, product, retail, conversion","E-commerce, online stores, product pages, retail, shopping","https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Rubik:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Rubik', 'sans-serif'], body: ['Nunito Sans', 'sans-serif'] }","Clean readable fonts perfect for product descriptions."
|
||||
41,Academic/Research,"Serif + Sans",Crimson Pro,Atkinson Hyperlegible,"academic, research, scholarly, accessible, readable, educational","Universities, research papers, academic journals, educational","https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Crimson+Pro:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&family=Crimson+Pro:wght@400;500;600;700&display=swap');","fontFamily: { serif: ['Crimson Pro', 'serif'], sans: ['Atkinson Hyperlegible', 'sans-serif'] }","Crimson for scholarly headlines. Atkinson for accessibility."
|
||||
42,Dashboard Data,"Mono + Sans",Fira Code,Fira Sans,"dashboard, data, analytics, code, technical, precise","Dashboards, analytics, data visualization, admin panels","https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&family=Fira+Sans:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&family=Fira+Sans:wght@300;400;500;600;700&display=swap');","fontFamily: { mono: ['Fira Code', 'monospace'], sans: ['Fira Sans', 'sans-serif'] }","Fira family cohesion. Code for data, Sans for labels."
|
||||
43,Music/Entertainment,"Display + Sans",Righteous,Poppins,"music, entertainment, fun, energetic, bold, performance","Music platforms, entertainment, events, festivals, performers","https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&family=Righteous&display=swap","@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&family=Righteous&display=swap');","fontFamily: { display: ['Righteous', 'sans-serif'], sans: ['Poppins', 'sans-serif'] }","Righteous for bold entertainment headers. Poppins for body."
|
||||
44,Minimalist Portfolio,"Sans + Sans",Archivo,Space Grotesk,"minimal, portfolio, designer, creative, clean, artistic","Design portfolios, creative professionals, minimalist brands","https://fonts.googleapis.com/css2?family=Archivo:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Archivo:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&display=swap');","fontFamily: { heading: ['Space Grotesk', 'sans-serif'], body: ['Archivo', 'sans-serif'] }","Space Grotesk for distinctive headers. Archivo for clean body."
|
||||
45,Kids/Education,"Display + Sans",Baloo 2,Comic Neue,"kids, education, playful, friendly, colorful, learning","Children's apps, educational games, kid-friendly content","https://fonts.googleapis.com/css2?family=Baloo+2:wght@400;500;600;700&family=Comic+Neue:wght@300;400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Baloo+2:wght@400;500;600;700&family=Comic+Neue:wght@300;400;700&display=swap');","fontFamily: { display: ['Baloo 2', 'sans-serif'], sans: ['Comic Neue', 'sans-serif'] }","Fun, playful fonts for children. Comic Neue is readable comic style."
|
||||
46,Wedding/Romance,"Script + Serif",Great Vibes,Cormorant Infant,"wedding, romance, elegant, script, invitation, feminine","Wedding sites, invitations, romantic brands, bridal","https://fonts.googleapis.com/css2?family=Cormorant+Infant:wght@300;400;500;600;700&family=Great+Vibes&display=swap","@import url('https://fonts.googleapis.com/css2?family=Cormorant+Infant:wght@300;400;500;600;700&family=Great+Vibes&display=swap');","fontFamily: { script: ['Great Vibes', 'cursive'], serif: ['Cormorant Infant', 'serif'] }","Great Vibes for elegant accents. Cormorant for readable text."
|
||||
47,Science/Tech,"Sans + Sans",Exo,Roboto Mono,"science, technology, research, data, futuristic, precise","Science, research, tech documentation, data-heavy sites","https://fonts.googleapis.com/css2?family=Exo:wght@300;400;500;600;700&family=Roboto+Mono:wght@300;400;500;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Exo:wght@300;400;500;600;700&family=Roboto+Mono:wght@300;400;500;700&display=swap');","fontFamily: { sans: ['Exo', 'sans-serif'], mono: ['Roboto Mono', 'monospace'] }","Exo for modern tech feel. Roboto Mono for code/data."
|
||||
48,Accessibility First,"Sans + Sans",Atkinson Hyperlegible,Atkinson Hyperlegible,"accessible, readable, inclusive, WCAG, dyslexia-friendly, clear","Accessibility-critical sites, government, healthcare, inclusive design","https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:wght@400;700&display=swap');","fontFamily: { sans: ['Atkinson Hyperlegible', 'sans-serif'] }","Designed for maximum legibility. Excellent for accessibility."
|
||||
49,Sports/Fitness,"Sans + Sans",Barlow Condensed,Barlow,"sports, fitness, athletic, energetic, condensed, action","Sports, fitness, gyms, athletic brands, competition","https://fonts.googleapis.com/css2?family=Barlow+Condensed:wght@400;500;600;700&family=Barlow:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Barlow+Condensed:wght@400;500;600;700&family=Barlow:wght@300;400;500;600;700&display=swap');","fontFamily: { display: ['Barlow Condensed', 'sans-serif'], body: ['Barlow', 'sans-serif'] }","Condensed for impact headlines. Regular Barlow for body."
|
||||
50,Luxury Minimalist,"Serif + Sans",Bodoni Moda,Jost,"luxury, minimalist, high-end, sophisticated, refined, premium","Luxury minimalist brands, high-end fashion, premium products","https://fonts.googleapis.com/css2?family=Bodoni+Moda:wght@400;500;600;700&family=Jost:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Bodoni+Moda:wght@400;500;600;700&family=Jost:wght@300;400;500;600;700&display=swap');","fontFamily: { serif: ['Bodoni Moda', 'serif'], sans: ['Jost', 'sans-serif'] }","Bodoni's high contrast elegance. Jost for geometric body."
|
||||
51,Tech/HUD Mono,"Mono + Mono",Share Tech Mono,Fira Code,"tech, futuristic, hud, sci-fi, data, monospaced, precise","Sci-fi interfaces, developer tools, cybersecurity, dashboards","https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500;600;700&family=Share+Tech+Mono&display=swap","@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@300;400;500;600;700&family=Share+Tech+Mono&display=swap');","fontFamily: { hud: ['Share Tech Mono', 'monospace'], code: ['Fira Code', 'monospace'] }","Share Tech Mono has that classic sci-fi look."
|
||||
52,Pixel Retro,"Display + Sans",Press Start 2P,VT323,"pixel, retro, gaming, 8-bit, nostalgic, arcade","Pixel art games, retro websites, creative portfolios","https://fonts.googleapis.com/css2?family=Press+Start+2P&family=VT323&display=swap","@import url('https://fonts.googleapis.com/css2?family=Press+Start+2P&family=VT323&display=swap');","fontFamily: { pixel: ['Press Start 2P', 'cursive'], terminal: ['VT323', 'monospace'] }","Press Start 2P is very wide/large. VT323 is better for body text."
|
||||
53,Neubrutalist Bold,"Display + Sans",Lexend Mega,Public Sans,"bold, neubrutalist, loud, strong, geometric, quirky","Neubrutalist designs, Gen Z brands, bold marketing","https://fonts.googleapis.com/css2?family=Lexend+Mega:wght@100..900&family=Public+Sans:wght@100..900&display=swap","@import url('https://fonts.googleapis.com/css2?family=Lexend+Mega:wght@100..900&family=Public+Sans:wght@100..900&display=swap');","fontFamily: { mega: ['Lexend Mega', 'sans-serif'], body: ['Public Sans', 'sans-serif'] }","Lexend Mega has distinct character and variable weight."
|
||||
54,Academic/Archival,"Serif + Serif",EB Garamond,Crimson Text,"academic, old-school, university, research, serious, traditional","University sites, archives, research papers, history","https://fonts.googleapis.com/css2?family=Crimson+Text:wght@400;600;700&family=EB+Garamond:wght@400;500;600;700;800&display=swap","@import url('https://fonts.googleapis.com/css2?family=Crimson+Text:wght@400;600;700&family=EB+Garamond:wght@400;500;600;700;800&display=swap');","fontFamily: { classic: ['EB Garamond', 'serif'], text: ['Crimson Text', 'serif'] }","Classic academic aesthetic. Very legible."
|
||||
55,Spatial Clear,"Sans + Sans",Inter,Inter,"spatial, legible, glass, system, clean, neutral","Spatial computing, AR/VR, glassmorphism interfaces","https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600&display=swap');","fontFamily: { sans: ['Inter', 'sans-serif'] }","Optimized for readability on dynamic backgrounds."
|
||||
56,Kinetic Motion,"Display + Mono",Syncopate,Space Mono,"kinetic, motion, futuristic, speed, wide, tech","Music festivals, automotive, high-energy brands","https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Syncopate:wght@400;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Syncopate:wght@400;700&display=swap');","fontFamily: { display: ['Syncopate', 'sans-serif'], mono: ['Space Mono', 'monospace'] }","Syncopate's wide stance works well with motion effects."
|
||||
57,Gen Z Brutal,"Display + Sans",Anton,Epilogue,"brutal, loud, shouty, meme, internet, bold","Gen Z marketing, streetwear, viral campaigns","https://fonts.googleapis.com/css2?family=Anton&family=Epilogue:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Anton&family=Epilogue:wght@400;500;600;700&display=swap');","fontFamily: { display: ['Anton', 'sans-serif'], body: ['Epilogue', 'sans-serif'] }","Anton is impactful and condensed. Good for stickers/badges."57,Bauhaus Geometric,"Geometric Sans + Single Weight","Outfit","Outfit","bauhaus, geometric, constructivist, bold, uppercase, architectural, mechanical, poster, tactile","Bauhaus mobile apps, bold editorial mobile, design-forward branding apps, art/culture platforms","https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;700;900&display=swap","@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;700;900&display=swap');","fontFamily: { display: ['Outfit', 'sans-serif'], body: ['Outfit', 'sans-serif'] }","Single-family system: Outfit 900 uppercase tracking-tighter for heroes; Outfit 700 uppercase for buttons/nav; Outfit 500 for body. Scale aggressively: text-4xl–text-5xl headlines on mobile."
|
||||
58,Minimalist Monochrome Editorial,"Serif + Serif + Mono (Triple Stack)",Playfair Display,Source Serif 4,"monochrome, editorial, austere, typographic, pocket manifesto, luxury, high contrast, brutalist mobile","Luxury fashion mobile apps, editorial publications, digital exhibitions, portfolio apps, high-contrast e-reader aesthetics","https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Playfair+Display:ital,wght@0,400;0,700;0,900;1,400|Source+Serif+4:ital,wght@0,300;0,400;0,600;1,300","@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Playfair+Display:ital,wght@0,400;0,700;0,900;1,400&family=Source+Serif+4:ital,wght@0,300;0,400;0,600;1,300&display=swap');","fontFamily: { display: ['Playfair Display', 'serif'], body: ['Source Serif 4', 'serif'], mono: ['JetBrains Mono', 'monospace'] }","Triple stack: Playfair Display 900 tracking-tighter leading-[0.9] for heroes (text-5xl–text-6xl breaks words graphically). Source Serif 4 300–600 for body legibility. JetBrains Mono 400–500 uppercase tracking-widest for tags/dates/labels. NO UI sans-serif — 100% serif/mono."
|
||||
59,Modern Dark Cinema (Inter System),"Sans + Mono",Inter,Inter,"dark, cinematic, technical, precision, clean, premium, developer, professional, high-end utility","Developer tools, fintech/trading, AI dashboards, streaming platforms, high-end productivity apps","https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');","fontFamily: { sans: ['Inter', 'sans-serif'] }","Single-family precision system: Inter 700 (-1.5 tracking) for Display 48pt; Inter 600 (-0.5 tracking) for H1 32pt / H2 24pt; Inter 400 for body 16pt; Inter 500 uppercase +1.2 tracking for labels/mono. Gradient text via mask-view + react-native-linear-gradient (#FFFFFF → rgba(255,255,255,0.7)) on major headers."
|
||||
60,SaaS Mobile Boutique (Calistoga + Inter),"Display Serif + Sans + Mono",Calistoga,Inter,"saas, boutique, electric, warm, editorial, bold, premium, fintech, business, dual font, human warmth","B2B SaaS mobile, fintech apps, analytics dashboards, marketing tools, operations platforms","https://fonts.googleapis.com/css2?family=Calistoga:ital@0;1&family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap","@import url('https://fonts.googleapis.com/css2?family=Calistoga:ital@0;1&family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');","fontFamily: { display: ['Calistoga', 'serif'], body: ['Inter', 'sans-serif'], mono: ['JetBrains Mono', 'monospace'] }","Tri-stack: Calistoga (adds human warmth) for heroes 36–42pt leading-1.1; Inter 400–600 for body/UI 16–18pt; JetBrains Mono 12pt uppercase tracking-[1.5] for data labels and section badges. Scale: Hero 36–42pt, Section H2 28–32pt, Body 16–18pt, Label 12pt. Avoid italic Calistoga except editorial callouts."
|
||||
61,Terminal CLI Monospace,"Mono + Mono (Single Family)",JetBrains Mono,JetBrains Mono,"terminal, cli, hacker, monospace, matrix, developer, retro-future, command line, precision, OLED","Developer tools, Web3/blockchain apps, hacker aesthetic, sci-fi games, ARG, security tools, geek-culture portfolios","https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,400;0,500;1,400","@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,400;0,500;1,400&display=swap');","fontFamily: { mono: ['JetBrains Mono', 'monospace'] }","Single monospace system: use ONLY JetBrains Mono (or SpaceMono-Regular as system fallback). Strict sizes: 12pt / 14pt / 16pt only — no in-between. Weight: 400 normal (bold ruins mono character). Line height: 1.2x font size for information density. Letter spacing: normal (monospaced auto-spacing). All UI labels uppercase. ASCII borders and text-based progress bars."
|
||||
62,Kinetic Brutalism (Space Grotesk),"Geometric Sans (Single Dominant)",Space Grotesk,Space Grotesk,"kinetic, brutalist, aggressive, uppercase, oversized, display, motion, street, bold, high-energy, zine","Music/culture apps, sports platforms, brand flagship mobile, performance dashboards, underground product drops","https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&display=swap');","fontFamily: { display: ['Space Grotesk', 'sans-serif'], body: ['Space Grotesk', 'sans-serif'] }","Dominant single-family system: Space Grotesk 700–900 for ALL display. Scale: Hero 60–120pt (windowWidth/375*size), Section 40–50pt, Card titles 28–32pt, Body 18–20pt, Labels 12pt. ALL display/buttons/nav: UPPERCASE, letterSpacing -1 (large) / +2 (labels), lineHeight 0.9–1.1x. Use Inter as fallback. Font scale must use PixelRatio helper for responsive sizing."
|
||||
63,Flat Design Mobile (System Bold),"Sans + Sans",Inter,Inter,"flat, clean, system, bold, geometric, cross-platform, icon, poster, minimal, functional, responsive","Cross-platform apps, dashboards, system UI, onboarding, marketing pages, informational apps, icon-heavy interfaces","https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap');","fontFamily: { sans: ['Inter', 'sans-serif'] }","System-first strategy: Inter as primary, falls back to system SF/Roboto on iOS/Android. Scale: Headlines fontWeight 800 letterSpacing -0.5; Subheadings fontWeight 600 fontSize 18; Body fontWeight 400 lineHeight 24; Labels fontWeight 700 uppercase letterSpacing 1. Thick weights carry all hierarchy since there are no shadows. Use aggressive size contrast (poster rule: body 16pt vs headline 40pt+). Avoid italic."
|
||||
64,Material You MD3 (Roboto System),"Sans (System Default)",Roboto,Roboto,"material design 3, md3, android, google, tonal, friendly, rounded, accessible, adaptive","Android apps, cross-platform tools, productivity software, data-heavy B2B dashboards, enterprise mobile","https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,300;0,400;0,500;0,700;1,400","@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,300;0,400;0,500;0,700;1,400&display=swap');","fontFamily: { sans: ['Roboto', 'sans-serif'] }","MD3 type scale: Display Large 56px/400/64px. Headline Large 32px/500/40px. Title Large 22px/500/28px. Body Large 16px/400/24px. Label Medium 12px/500/16px. Buttons and Labels: letterSpacing 0.1px. Use system Roboto on Android; load from Google Fonts for iOS parity. Never use custom weights beyond 300–700."
|
||||
65,Neo Brutalism Mobile (Space Grotesk Heavy),"Geometric Sans (Bold-Only)",Space Grotesk,Space Grotesk,"neo brutalism, pop art, loud, bold, heavy, stickers, mechanical, high contrast, cream, gen-z","Creative tools, Gen-Z marketing, e-commerce for youth culture, content portfolios, collage-style apps","https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@700&display=swap');","fontFamily: { display: ['Space Grotesk', 'sans-serif'], body: ['Space Grotesk', 'sans-serif'] }","Strictly 700 (Bold) and 900 (Black/Heavy) ONLY — never Regular or Light. Display: 48–64px. Heading: 24–32px. Body: 18–20px (stays heavy for brutalist density). Labels: 14px ALL CAPS letterSpacing 2. All buttons and navigation: uppercase. System bold as fallback. No italic, no thin weights."
|
||||
66,Bold Typography Mobile (Inter-Tight Poster),"Sans + Serif (Display) + Mono","Inter","Playfair Display","bold typography, editorial, poster, near-black, vermillion, luxury, type-as-hero, manifesto, high-contrast","Creative brand flagships, reading platforms, event apps, flash pages, luxury mobile experiences","https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;0,800;1,400|JetBrains+Mono:wght@400|Playfair+Display:ital@1","@import url('https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;0,800;1,400&family=JetBrains+Mono:wght@400&family=Playfair+Display:ital@1&display=swap');","fontFamily: { display: ['Inter', 'sans-serif'], quote: ['Playfair Display', 'serif'], mono: ['JetBrains Mono', 'monospace'] }","Tri-stack: Inter 600–800 for all UI (letterSpacing -1.5px heroes, -0.5px subheads). Playfair Display Italic ONLY for pull quotes. JetBrains Mono for labels and stats. Scale: 12px labels, 16px body, 22px sub, 32px section, 40px H2, 56px H1, 72px Hero Statement. 5:1 ratio H1:Body is mandatory. lineHeight 1.1 headlines, 1.6 body. Underlines (2–3pt accent) replace buttons for interactions."
|
||||
67,Academia Mobile (Cormorant + Crimson + Cinzel),"Serif + Book Serif + Engraved (Triple Stack)","Cormorant Garamond","Crimson Pro","academia, library, mahogany, parchment, brass, scholarly, prestige, antique, victorian, leather","Knowledge management apps, scholarly reading tools, personal brand portfolios, RPG games, cultural community platforms","https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600&family=Cormorant+Garamond:ital,wght@0,300;0,500;0,700;1,300;1,500|Crimson+Pro:ital,wght@0,300;0,400;0,600;1,300;1,400","@import url('https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600&family=Cormorant+Garamond:ital,wght@0,300;0,500;0,700;1,300;1,500&family=Crimson+Pro:ital,wght@0,300;0,400;0,600;1,300;1,400&display=swap');","fontFamily: { heading: ['Cormorant Garamond', 'serif'], body: ['Crimson Pro', 'serif'], display: ['Cinzel', 'serif'] }","Triple-stack: Cormorant Garamond Medium for all headings (32–40px tight leading). Crimson Pro Regular for body reading text (16–18px, lineHeight 24–26px). Cinzel SemiBold for ALL-CAPS labels, overlines, section prefixes (10–12px, letterSpacing 2–3px). Drop caps: first letter 60px Cinzel in Brass #C9A962. Section prefix: VOLUME I/II/III in Cinzel 10px. NO sans-serif anywhere."
|
||||
68,Cyberpunk Mobile (Orbitron + JetBrains Mono),"Tech Display + Mono","Orbitron","JetBrains Mono","cyberpunk, neon, glitch, hud, sci-fi, dark, matrix green, magenta, chamfered, tactical","Gaming companion apps, fintech/crypto, data visualization, dark brand apps, cyberpunk narrative games","https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Orbitron:wght@700;900&display=swap","@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500&family=Orbitron:wght@700;900&display=swap');","fontFamily: { heading: ['Orbitron', 'sans-serif'], body: ['JetBrains Mono', 'monospace'] }","Dual-stack: Orbitron 700–900 for H1 (42px uppercase letterSpacing 4, fontWeight 900). JetBrains Mono 400–500 for all body/data text (14px letterSpacing 1). Labels: 10px uppercase opacity 0.7. Heading scale aggressive: H1 42px, H2 28px, Section 20px. Body 14px monospace only. NO mixed sans-serif. Fallback: monospace system font. Orbitron requires loading — use NativeWind or useFonts hook."
|
||||
69,Web3 Bitcoin DeFi (Space Grotesk + Inter + Mono),"Geometric Sans + Sans + Mono (Triple)","Space Grotesk","Inter","web3, bitcoin, defi, digital gold, fintech, crypto, trustless, luminescent, precision, dark","DeFi protocols and wallets, NFT platforms, metaverse social apps, high-tech brand landing pages","https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Space+Grotesk:wght@500;600;700&display=swap","@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Space+Grotesk:wght@500;600;700&display=swap');","fontFamily: { heading: ['Space Grotesk', 'sans-serif'], body: ['Inter', 'sans-serif'], mono: ['JetBrains Mono', 'monospace'] }","Tri-stack: Space Grotesk 600–700 for headings (geometric, technical character). Inter 400–600 for all body and UI text (high legibility). JetBrains Mono Medium for all data/stats/prices/hashes (technical accuracy). Buttons: Inter Bold uppercase letterSpacing 1.5. Balance figures use MaskedView gradient text (orange→gold). Heading scale: H1 36–42px, H2 24–28px, body 16–18px, mono labels 12–14px."
|
||||
70,Claymorphism Mobile (Nunito + DM Sans),"Display Rounded + Geometric Sans","Nunito","DM Sans","claymorphism, clay, rounded, playful, candy, bubbly, soft, 3d, children, education, tactile, spring, nunito, dm sans","Children education apps, teen social, brand mascot apps, creative tools, fintech gamification","https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,400;0,500;0,700;1,400|Nunito:ital,wght@0,700;0,800;0,900;1,700","@import url('https://fonts.googleapis.com/css2?family=DM+Sans:ital,wght@0,400;0,500;0,700;1,400&family=Nunito:ital,wght@0,700;0,800;0,900;1,700&display=swap');","fontFamily: { display: ['Nunito', 'sans-serif'], body: ['DM Sans', 'sans-serif'] }","Dual-stack: Nunito Black (900) or ExtraBold (800) for ALL headings — rounded terminals are mandatory. DM Sans Medium (500) for body text — clean and geometric. Scale: Hero 48px lineHeight 52 letterSpacing -1. Section Title 32px lineHeight 38. Card Title 22px lineHeight 28. Body 16px lineHeight 24. Never use Nunito for body text (too decorative at small sizes). Never use weights below 700 for any heading. includeFontPadding: false on all Nunito Text components for vertical centering in rounded buttons."
|
||||
71,Enterprise SaaS Mobile (Plus Jakarta Sans),"Geometric Sans (Single Family)","Plus Jakarta Sans","Plus Jakarta Sans","enterprise, saas, b2b, professional, indigo, modern, approachable, legible, ios dynamic type, android scaling","B2B SaaS apps, productivity tools, government and finance mobile apps, admin dashboards, enterprise onboarding","https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,600;0,700;0,800;1,400","@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,600;0,700;0,800;1,400&display=swap');","fontFamily: { sans: ['Plus Jakarta Sans', 'sans-serif'] }","Single-family system: Plus Jakarta Sans balances professional authority with mobile approachability. Weight scale: ExtraBold 800 for screen titles/hero (line height 1.1–1.2). Bold 700 for section headers. SemiBold 600 for card titles and buttons. Regular 400 for body text (line height 1.4–1.5). Must support iOS Dynamic Type and Android font scaling — never hardcode pixel sizes without respecting system font scale. Button text: uppercase, letterSpacing 0.5. Caption: 12px Regular. Muted: Slate 500 #64748B."
|
||||
72,Sketch Hand-Drawn Mobile (Kalam + Patrick Hand),"Handwritten + Handwritten (Dual)","Kalam","Patrick Hand","sketch, hand-drawn, handwriting, human, imperfect, organic, paper, kalam, patrick hand, education, journal, creative","Journaling apps, prototype tools, children's picturebook apps, creative platforms, gamified puzzle apps","https://fonts.googleapis.com/css2?family=Kalam:wght@400;700&family=Patrick+Hand&display=swap","@import url('https://fonts.googleapis.com/css2?family=Kalam:wght@400;700&family=Patrick+Hand&display=swap');","fontFamily: { heading: ['Kalam', 'cursive'], body: ['Patrick Hand', 'cursive'] }","Dual handwritten stack: Kalam Bold (700) for all headings — high visual weight, felt-tip marker aesthetic, conveys intentional messiness. Patrick Hand Regular for all body text — highly legible at mobile sizes while remaining distinctly human. Scale: Heading 28–36px with lineHeight adjusted for descenders. Body 16–18px lineHeight 1.5. Labels 14px. Vary font sizes slightly between adjacent elements for spontaneous feel. Avoid alignment: 'center' for long body text — left-aligned reads more naturally. Both fonts require useFonts loading in Expo. Never use these fonts for financial figures or legal text."
|
||||
73,Neumorphism Mobile (Plus Jakarta Sans + System),"Geometric Sans (System Fallback)","Plus Jakarta Sans","Plus Jakarta Sans","neumorphism, soft ui, monochromatic, cool grey, minimal, physical, depth, ceramic, system font, utility","Smart home controls, minimal tools, aesthetic dashboards, health monitors, brand showcase pages","https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,500;0,700;1,400","@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,500;0,700;1,400&display=swap');","fontFamily: { sans: ['Plus Jakarta Sans', 'sans-serif'] }","Single-family or System fallback: Plus Jakarta Sans Bold/Medium pairs beautifully with the monochromatic #E0E5EC surface — subtle geometry without competing with the depth effect. Heading: 24–32px Bold (700), letterSpacing -0.5 for modern premium feel. Body: 16px Medium (500), lineHeight 1.4. Caption: 12px Regular (400). Use Text Primary #3D4852 (7.5:1 contrast against #E0E5EC) for all primary text. Use Text Muted #6B7280 (4.6:1 contrast) for secondary text. Accent color #6C63FF only on active labels or focus indicators. Never use italic or thin weights — they lose legibility against the embossed background. System (SF Pro / Roboto) is an acceptable fallback for performance-sensitive implementations."
|
||||
|
Can't render this file because it contains an unexpected character in line 58 and column 500.
|
|
|
@ -1,162 +0,0 @@
|
|||
No,UI_Category,Recommended_Pattern,Style_Priority,Color_Mood,Typography_Mood,Key_Effects,Decision_Rules,Anti_Patterns,Severity
|
||||
1,SaaS (General),Hero + Features + CTA,Glassmorphism + Flat Design,Trust blue + Accent contrast,Professional + Hierarchy,Subtle hover (200-250ms) + Smooth transitions,"{""if_ux_focused"": ""prioritize-minimalism"", ""if_data_heavy"": ""add-glassmorphism""}",Excessive animation + Dark mode by default,HIGH
|
||||
2,Micro SaaS,Hero-Centric + Trust,Motion-Driven + Vibrant & Block,Bold primaries + Accent contrast,Modern + Energetic typography,Scroll-triggered animations + Parallax,"{""if_pre_launch"": ""use-waitlist-pattern"", ""if_video_ready"": ""add-hero-video""}",Static design + No video + Poor mobile,HIGH
|
||||
3,E-commerce,Feature-Rich Showcase,Vibrant & Block-based,Brand primary + Success green,Engaging + Clear hierarchy,Card hover lift (200ms) + Scale effect,"{""if_luxury"": ""switch-to-liquid-glass"", ""if_conversion_focused"": ""add-urgency-colors""}",Flat design without depth + Text-heavy pages,HIGH
|
||||
4,E-commerce Luxury,Feature-Rich Showcase,Liquid Glass + Glassmorphism,Premium colors + Minimal accent,Elegant + Refined typography,Chromatic aberration + Fluid animations (400-600ms),"{""if_checkout"": ""emphasize-trust"", ""if_hero_needed"": ""use-3d-hyperrealism""}",Vibrant & Block-based + Playful colors,HIGH
|
||||
5,B2B Service,Feature-Rich Showcase + Trust,Trust & Authority + Minimalism,Professional blue + Neutral grey,Formal + Clear typography,Section transitions + Feature reveals,"{""must_have"": ""case-studies"", ""must_have"": ""roi-messaging""}",Playful design + Hidden credentials + AI purple/pink gradients,HIGH
|
||||
6,Financial Dashboard,Data-Dense Dashboard,Dark Mode (OLED) + Data-Dense,Dark bg + Red/Green alerts + Trust blue,Clear + Readable typography,Real-time number animations + Alert pulse,"{""must_have"": ""real-time-updates"", ""must_have"": ""high-contrast""}",Light mode default + Slow rendering,HIGH
|
||||
7,Analytics Dashboard,Data-Dense + Drill-Down,Data-Dense + Heat Map,Cool→Hot gradients + Neutral grey,Clear + Functional typography,Hover tooltips + Chart zoom + Filter animations,"{""must_have"": ""data-export"", ""if_large_dataset"": ""virtualize-lists""}",Ornate design + No filtering,HIGH
|
||||
8,Healthcare App,Social Proof-Focused,Neumorphism + Accessible & Ethical,Calm blue + Health green,Readable + Large type (16px+),Soft box-shadow + Smooth press (150ms),"{""must_have"": ""wcag-aaa-compliance"", ""if_medication"": ""red-alert-colors""}",Bright neon colors + Motion-heavy animations + AI purple/pink gradients,HIGH
|
||||
9,Educational App,Feature-Rich Showcase,Claymorphism + Micro-interactions,Playful colors + Clear hierarchy,Friendly + Engaging typography,Soft press (200ms) + Fluffy elements,"{""if_gamification"": ""add-progress-animation"", ""if_children"": ""increase-playfulness""}",Dark modes + Complex jargon,MEDIUM
|
||||
10,Creative Agency,Storytelling-Driven,Brutalism + Motion-Driven,Bold primaries + Artistic freedom,Bold + Expressive typography,CRT scanlines + Neon glow + Glitch effects,"{""must_have"": ""case-studies"", ""if_boutique"": ""increase-artistic-freedom""}",Corporate minimalism + Hidden portfolio,HIGH
|
||||
11,Portfolio/Personal,Storytelling-Driven,Motion-Driven + Minimalism,Brand primary + Artistic,Expressive + Variable typography,Parallax (3-5 layers) + Scroll-triggered reveals,"{""if_creative_field"": ""add-brutalism"", ""if_minimal_portfolio"": ""reduce-motion""}",Corporate templates + Generic layouts,MEDIUM
|
||||
12,Gaming,Feature-Rich Showcase,3D & Hyperrealism + Retro-Futurism,Vibrant + Neon + Immersive,Bold + Impactful typography,WebGL 3D rendering + Glitch effects,"{""if_competitive"": ""add-real-time-stats"", ""if_casual"": ""increase-playfulness""}",Minimalist design + Static assets,HIGH
|
||||
13,Government/Public Service,Minimal & Direct,Accessible & Ethical + Minimalism,Professional blue + High contrast,Clear + Large typography,Clear focus rings (3-4px) + Skip links,"{""must_have"": ""wcag-aaa"", ""must_have"": ""keyboard-navigation""}",Ornate design + Low contrast + Motion effects + AI purple/pink gradients,HIGH
|
||||
14,Fintech/Crypto,Trust & Authority,Minimalism + Accessible & Ethical,Navy + Trust Blue + Gold,Professional + Trustworthy,Smooth state transitions + Number animations,"{""must_have"": ""security-first"", ""if_dashboard"": ""use-dark-mode""}",Playful design + Unclear fees + AI purple/pink gradients,HIGH
|
||||
15,Social Media App,Feature-Rich Showcase,Vibrant & Block-based + Motion-Driven,Vibrant + Engagement colors,Modern + Bold typography,Large scroll animations + Icon animations,"{""if_engagement_metric"": ""add-motion"", ""if_content_focused"": ""minimize-chrome""}",Heavy skeuomorphism + Accessibility ignored,MEDIUM
|
||||
16,Productivity Tool,Interactive Demo + Feature-Rich,Flat Design + Micro-interactions,Clear hierarchy + Functional colors,Clean + Efficient typography,Quick actions (150ms) + Task animations,"{""must_have"": ""keyboard-shortcuts"", ""if_collaboration"": ""add-real-time-cursors""}",Complex onboarding + Slow performance,HIGH
|
||||
17,Design System/Component Library,Feature-Rich + Documentation,Minimalism + Accessible & Ethical,Clear hierarchy + Code-like structure,Monospace + Clear typography,Code copy animations + Component previews,"{""must_have"": ""search"", ""must_have"": ""code-examples""}",Poor documentation + No live preview,HIGH
|
||||
18,AI/Chatbot Platform,Interactive Demo + Minimal,AI-Native UI + Minimalism,Neutral + AI Purple (#6366F1),Modern + Clear typography,Streaming text + Typing indicators + Fade-in,"{""must_have"": ""conversational-ui"", ""must_have"": ""context-awareness""}",Heavy chrome + Slow response feedback,HIGH
|
||||
19,NFT/Web3 Platform,Feature-Rich Showcase,Cyberpunk UI + Glassmorphism,Dark + Neon + Gold (#FFD700),Bold + Modern typography,Wallet connect animations + Transaction feedback,"{""must_have"": ""wallet-integration"", ""must_have"": ""gas-fees-display""}",Light mode default + No transaction status,HIGH
|
||||
20,Creator Economy Platform,Social Proof + Feature-Rich,Vibrant & Block-based + Bento Box Grid,Vibrant + Brand colors,Modern + Bold typography,Engagement counter animations + Profile reveals,"{""must_have"": ""creator-profiles"", ""must_have"": ""monetization-display""}",Generic layout + Hidden earnings,MEDIUM
|
||||
21,Remote Work/Collaboration Tool,Feature-Rich + Real-Time,Soft UI Evolution + Minimalism,Calm Blue + Neutral grey,Clean + Readable typography,Real-time presence indicators + Notification badges,"{""must_have"": ""status-indicators"", ""must_have"": ""video-integration""}",Cluttered interface + No presence,HIGH
|
||||
22,Mental Health App,Social Proof-Focused,Neumorphism + Accessible & Ethical,Calm Pastels + Trust colors,Calming + Readable typography,Soft press + Breathing animations,"{""must_have"": ""privacy-first"", ""if_meditation"": ""add-breathing-animation""}",Bright neon + Motion overload,HIGH
|
||||
23,Pet Tech App,Storytelling + Feature-Rich,Claymorphism + Vibrant & Block-based,Playful + Warm colors,Friendly + Playful typography,Pet profile animations + Health tracking charts,"{""must_have"": ""pet-profiles"", ""if_health"": ""add-vet-integration""}",Generic design + No personality,MEDIUM
|
||||
24,Smart Home/IoT Dashboard,Real-Time Monitoring,Glassmorphism + Dark Mode (OLED),Dark + Status indicator colors,Clear + Functional typography,Device status pulse + Quick action animations,"{""must_have"": ""real-time-controls"", ""must_have"": ""energy-monitoring""}",Slow updates + No automation,HIGH
|
||||
25,EV/Charging Ecosystem,Hero-Centric + Feature-Rich,Minimalism + Aurora UI,Electric Blue (#009CD1) + Green,Modern + Clear typography,Range estimation animations + Map interactions,"{""must_have"": ""charging-map"", ""must_have"": ""range-calculator""}",Poor map UX + Hidden costs,HIGH
|
||||
26,Subscription Box Service,Feature-Rich + Conversion,Vibrant & Block-based + Motion-Driven,Brand + Excitement colors,Engaging + Clear typography,Unboxing reveal animations + Product carousel,"{""must_have"": ""personalization-quiz"", ""must_have"": ""subscription-management""}",Confusing pricing + No unboxing preview,HIGH
|
||||
27,Podcast Platform,Storytelling + Feature-Rich,Dark Mode (OLED) + Minimalism,Dark + Audio waveform accents,Modern + Clear typography,Waveform visualizations + Episode transitions,"{""must_have"": ""audio-player-ux"", ""must_have"": ""episode-discovery""}",Poor audio player + Cluttered layout,HIGH
|
||||
28,Dating App,Social Proof + Feature-Rich,Vibrant & Block-based + Motion-Driven,Warm + Romantic (Pink/Red gradients),Modern + Friendly typography,Profile card swipe + Match animations,"{""must_have"": ""profile-cards"", ""must_have"": ""safety-features""}",Generic profiles + No safety,HIGH
|
||||
29,Micro-Credentials/Badges Platform,Trust & Authority + Feature,Minimalism + Flat Design,Trust Blue + Gold (#FFD700),Professional + Clear typography,Badge reveal animations + Progress tracking,"{""must_have"": ""credential-verification"", ""must_have"": ""progress-display""}",No verification + Hidden progress,MEDIUM
|
||||
30,Knowledge Base/Documentation,FAQ + Minimal,Minimalism + Accessible & Ethical,Clean hierarchy + Minimal color,Clear + Readable typography,Search highlight + Smooth scrolling,"{""must_have"": ""search-first"", ""must_have"": ""version-switching""}",Poor navigation + No search,HIGH
|
||||
31,Hyperlocal Services,Conversion + Feature-Rich,Minimalism + Vibrant & Block-based,Location markers + Trust colors,Clear + Functional typography,Map hover + Provider card reveals,"{""must_have"": ""map-integration"", ""must_have"": ""booking-system""}",No map + Hidden reviews,HIGH
|
||||
32,Beauty/Spa/Wellness Service,Hero-Centric + Social Proof,Soft UI Evolution + Neumorphism,Soft pastels (Pink Sage Cream) + Gold accents,Elegant + Calming typography,Soft shadows + Smooth transitions (200-300ms) + Gentle hover,"{""must_have"": ""booking-system"", ""must_have"": ""before-after-gallery"", ""if_luxury"": ""add-gold-accents""}",Bright neon colors + Harsh animations + Dark mode,HIGH
|
||||
33,Luxury/Premium Brand,Storytelling + Feature-Rich,Liquid Glass + Glassmorphism,Black + Gold (#FFD700) + White,Elegant + Refined typography,Slow parallax + Premium reveals (400-600ms),"{""must_have"": ""high-quality-imagery"", ""must_have"": ""storytelling""}",Cheap visuals + Fast animations,HIGH
|
||||
34,Restaurant/Food Service,Hero-Centric + Conversion,Vibrant & Block-based + Motion-Driven,Warm colors (Orange Red Brown),Appetizing + Clear typography,Food image reveal + Menu hover effects,"{""must_have"": ""high_quality_images"", ""if_delivery"": ""emphasize-speed""}",Low-quality imagery + Outdated hours,HIGH
|
||||
35,Fitness/Gym App,Feature-Rich + Data,Vibrant & Block-based + Dark Mode (OLED),Energetic (Orange #FF6B35) + Dark bg,Bold + Motivational typography,Progress ring animations + Achievement unlocks,"{""must_have"": ""progress-tracking"", ""must_have"": ""workout-plans""}",Static design + No gamification,HIGH
|
||||
36,Real Estate/Property,Hero-Centric + Feature-Rich,Glassmorphism + Minimalism,Trust Blue + Gold + White,Professional + Confident,3D property tour zoom + Map hover,"{""if_luxury"": ""add-3d-models"", ""must_have"": ""map-integration""}",Poor photos + No virtual tours,HIGH
|
||||
37,Travel/Tourism Agency,Storytelling-Driven + Hero,Aurora UI + Motion-Driven,Vibrant destination + Sky Blue,Inspirational + Engaging,Destination parallax + Itinerary animations,"{""if_experience_focused"": ""use-storytelling"", ""must_have"": ""mobile-booking""}",Generic photos + Complex booking,HIGH
|
||||
38,Hotel/Hospitality,Hero-Centric + Social Proof,Liquid Glass + Minimalism,Warm neutrals + Gold (#D4AF37),Elegant + Welcoming typography,Room gallery + Amenity reveals,"{""must_have"": ""room-booking"", ""must_have"": ""virtual-tour""}",Poor photos + Complex booking,HIGH
|
||||
39,Wedding/Event Planning,Storytelling + Social Proof,Soft UI Evolution + Aurora UI,Soft Pink (#FFD6E0) + Gold + Cream,Elegant + Romantic typography,Gallery reveals + Timeline animations,"{""must_have"": ""portfolio-gallery"", ""must_have"": ""planning-tools""}",Generic templates + No portfolio,HIGH
|
||||
40,Legal Services,Trust & Authority + Minimal,Trust & Authority + Minimalism,Navy Blue (#1E3A5F) + Gold + White,Professional + Authoritative typography,Practice area reveal + Attorney profile animations,"{""must_have"": ""case-results"", ""must_have"": ""credential-display""}",Outdated design + Hidden credentials + AI purple/pink gradients,HIGH
|
||||
41,Insurance Platform,Conversion + Trust,Trust & Authority + Flat Design,Trust Blue (#0066CC) + Green + Neutral,Clear + Professional typography,Quote calculator animations + Policy comparison,"{""must_have"": ""quote-calculator"", ""must_have"": ""policy-comparison""}",Confusing pricing + No trust signals + AI purple/pink gradients,HIGH
|
||||
42,Banking/Traditional Finance,Trust & Authority + Feature,Minimalism + Accessible & Ethical,Navy (#0A1628) + Trust Blue + Gold,Professional + Trustworthy typography,Smooth number animations + Security indicators,"{""must_have"": ""security-first"", ""must_have"": ""accessibility""}",Playful design + Poor security UX + AI purple/pink gradients,HIGH
|
||||
43,Online Course/E-learning,Feature-Rich + Social Proof,Claymorphism + Vibrant & Block-based,Vibrant learning colors + Progress green,Friendly + Engaging typography,Progress bar animations + Certificate reveals,"{""must_have"": ""progress-tracking"", ""must_have"": ""video-player""}",Boring design + No gamification,HIGH
|
||||
44,Non-profit/Charity,Storytelling + Trust,Accessible & Ethical + Organic Biophilic,Cause-related colors + Trust + Warm,Heartfelt + Readable typography,Impact counter animations + Story reveals,"{""must_have"": ""impact-stories"", ""must_have"": ""donation-transparency""}",No impact data + Hidden financials,HIGH
|
||||
45,Music Streaming,Feature-Rich Showcase,Dark Mode (OLED) + Vibrant & Block-based,Dark (#121212) + Vibrant accents + Album art colors,Modern + Bold typography,Waveform visualization + Playlist animations,"{""must_have"": ""audio-player-ux"", ""if_discovery_focused"": ""add-playlist-recommendations""}",Cluttered layout + Poor audio player UX,HIGH
|
||||
46,Video Streaming/OTT,Hero-Centric + Feature-Rich,Dark Mode (OLED) + Motion-Driven,Dark bg + Poster colors + Brand accent,Bold + Engaging typography,Video player animations + Content carousel (parallax),"{""must_have"": ""continue-watching"", ""if_personalized"": ""add-recommendations""}",Static layout + Slow video player,HIGH
|
||||
47,Job Board/Recruitment,Conversion-Optimized + Feature-Rich,Flat Design + Minimalism,Professional Blue + Success Green + Neutral,Clear + Professional typography,Search/filter animations + Application flow,"{""must_have"": ""advanced-search"", ""if_salary_focused"": ""highlight-compensation""}",Outdated forms + Hidden filters,HIGH
|
||||
48,Marketplace (P2P),Feature-Rich Showcase + Social Proof,Vibrant & Block-based + Flat Design,Trust colors + Category colors + Success green,Modern + Engaging typography,Review star animations + Listing hover effects,"{""must_have"": ""seller-profiles"", ""must_have"": ""secure-payment""}",Low trust signals + Confusing layout,HIGH
|
||||
49,Logistics/Delivery,Feature-Rich Showcase + Real-Time,Minimalism + Flat Design,Blue (#2563EB) + Orange (tracking) + Green,Clear + Functional typography,Real-time tracking animation + Status pulse,"{""must_have"": ""tracking-map"", ""must_have"": ""delivery-updates""}",Static tracking + No map integration + AI purple/pink gradients,HIGH
|
||||
50,Agriculture/Farm Tech,Feature-Rich Showcase,Organic Biophilic + Flat Design,Earth Green (#4A7C23) + Brown + Sky Blue,Clear + Informative typography,Data visualization + Weather animations,"{""must_have"": ""sensor-dashboard"", ""if_crop_focused"": ""add-health-indicators""}",Generic design + Ignored accessibility + AI purple/pink gradients,MEDIUM
|
||||
51,Construction/Architecture,Hero-Centric + Feature-Rich,Minimalism + 3D & Hyperrealism,Grey (#4A4A4A) + Orange (safety) + Blueprint Blue,Professional + Bold typography,3D model viewer + Timeline animations,"{""must_have"": ""project-portfolio"", ""if_team_collaboration"": ""add-real-time-updates""}",2D-only layouts + Poor image quality + AI purple/pink gradients,HIGH
|
||||
52,Automotive/Car Dealership,Hero-Centric + Feature-Rich,Motion-Driven + 3D & Hyperrealism,Brand colors + Metallic + Dark/Light,Bold + Confident typography,360 product view + Configurator animations,"{""must_have"": ""vehicle-comparison"", ""must_have"": ""financing-calculator""}",Static product pages + Poor UX,HIGH
|
||||
53,Photography Studio,Storytelling-Driven + Hero-Centric,Motion-Driven + Minimalism,Black + White + Minimal accent,Elegant + Minimal typography,Full-bleed gallery + Before/after reveal,"{""must_have"": ""portfolio-showcase"", ""if_booking"": ""add-calendar-system""}",Heavy text + Poor image showcase,HIGH
|
||||
54,Coworking Space,Hero-Centric + Feature-Rich,Vibrant & Block-based + Glassmorphism,Energetic colors + Wood tones + Brand,Modern + Engaging typography,Space tour video + Amenity reveal animations,"{""must_have"": ""virtual-tour"", ""must_have"": ""booking-system""}",Outdated photos + Confusing layout,MEDIUM
|
||||
55,Home Services (Plumber/Electrician),Conversion-Optimized + Trust,Flat Design + Trust & Authority,Trust Blue + Safety Orange + Grey,Professional + Clear typography,Emergency contact highlight + Service menu animations,"{""must_have"": ""emergency-contact"", ""must_have"": ""certifications-display""}",Hidden contact info + No certifications,HIGH
|
||||
56,Childcare/Daycare,Social Proof-Focused + Trust,Claymorphism + Vibrant & Block-based,Playful pastels + Safe colors + Warm,Friendly + Playful typography,Parent portal animations + Activity gallery reveal,"{""must_have"": ""parent-communication"", ""must_have"": ""safety-certifications""}",Generic design + Hidden safety info,HIGH
|
||||
57,Senior Care/Elderly,Trust & Authority + Accessible,Accessible & Ethical + Soft UI Evolution,Calm Blue + Warm neutrals + Large text,Large + Clear typography (18px+),Large touch targets + Clear navigation,"{""must_have"": ""wcag-aaa"", ""must_have"": ""family-portal""}",Small text + Complex navigation + AI purple/pink gradients,HIGH
|
||||
58,Medical Clinic,Trust & Authority + Conversion,Accessible & Ethical + Minimalism,Medical Blue (#0077B6) + Trust White,Professional + Readable typography,Online booking flow + Doctor profile reveals,"{""must_have"": ""appointment-booking"", ""must_have"": ""insurance-info""}",Outdated interface + Confusing booking + AI purple/pink gradients,HIGH
|
||||
59,Pharmacy/Drug Store,Conversion-Optimized + Trust,Flat Design + Accessible & Ethical,Pharmacy Green + Trust Blue + Clean White,Clear + Functional typography,Prescription upload flow + Refill reminders,"{""must_have"": ""prescription-management"", ""must_have"": ""drug-interaction-warnings""}",Confusing layout + Privacy concerns + AI purple/pink gradients,HIGH
|
||||
60,Dental Practice,Social Proof-Focused + Conversion,Soft UI Evolution + Minimalism,Fresh Blue + White + Smile Yellow,Friendly + Professional typography,Before/after gallery + Patient testimonial carousel,"{""must_have"": ""before-after-gallery"", ""must_have"": ""appointment-system""}",Poor imagery + No testimonials,HIGH
|
||||
61,Veterinary Clinic,Social Proof-Focused + Trust,Claymorphism + Accessible & Ethical,Caring Blue + Pet colors + Warm,Friendly + Welcoming typography,Pet profile management + Service animations,"{""must_have"": ""pet-portal"", ""must_have"": ""emergency-contact""}",Generic design + Hidden services,MEDIUM
|
||||
62,Florist/Plant Shop,Hero-Centric + Conversion,Organic Biophilic + Vibrant & Block-based,Natural Green + Floral pinks/purples,Elegant + Natural typography,Product reveal + Seasonal transitions,"{""must_have"": ""delivery-scheduling"", ""must_have"": ""care-guides""}",Poor imagery + No seasonal content,MEDIUM
|
||||
63,Bakery/Cafe,Hero-Centric + Conversion,Vibrant & Block-based + Soft UI Evolution,Warm Brown + Cream + Appetizing accents,Warm + Inviting typography,Menu hover + Order animations,"{""must_have"": ""menu-display"", ""must_have"": ""online-ordering""}",Poor food photos + Hidden hours,HIGH
|
||||
64,Brewery/Winery,Storytelling + Hero-Centric,Motion-Driven + Storytelling-Driven,Deep amber/burgundy + Gold + Craft,Artisanal + Heritage typography,Tasting note reveals + Heritage timeline,"{""must_have"": ""product-showcase"", ""must_have"": ""story-heritage""}",Generic product pages + No story,HIGH
|
||||
65,Airline,Conversion + Feature-Rich,Minimalism + Glassmorphism,Sky Blue + Brand colors + Trust,Clear + Professional typography,Flight search animations + Boarding pass reveals,"{""must_have"": ""flight-search"", ""must_have"": ""mobile-first""}",Complex booking + Poor mobile,HIGH
|
||||
66,News/Media Platform,Hero-Centric + Feature-Rich,Minimalism + Flat Design,Brand colors + High contrast,Clear + Readable typography,Breaking news badge + Article reveal animations,"{""must_have"": ""mobile-first-reading"", ""must_have"": ""category-navigation""}",Cluttered layout + Slow loading,HIGH
|
||||
67,Magazine/Blog,Storytelling + Hero-Centric,Swiss Modernism 2.0 + Motion-Driven,Editorial colors + Brand + Clean white,Editorial + Elegant typography,Article transitions + Category reveals,"{""must_have"": ""article-showcase"", ""must_have"": ""newsletter-signup""}",Poor typography + Slow loading,HIGH
|
||||
68,Freelancer Platform,Feature-Rich + Conversion,Flat Design + Minimalism,Professional Blue + Success Green,Clear + Professional typography,Skill match animations + Review reveals,"{""must_have"": ""portfolio-display"", ""must_have"": ""skill-matching""}",Poor profiles + No reviews,HIGH
|
||||
69,Marketing Agency,Storytelling + Feature-Rich,Brutalism + Motion-Driven,Bold brand colors + Creative freedom,Bold + Expressive typography,Portfolio reveals + Results animations,"{""must_have"": ""portfolio"", ""must_have"": ""results-metrics""}",Boring design + Hidden work,HIGH
|
||||
70,Event Management,Hero-Centric + Feature-Rich,Vibrant & Block-based + Motion-Driven,Event theme colors + Excitement accents,Bold + Engaging typography,Countdown timer + Registration flow,"{""must_have"": ""registration"", ""must_have"": ""agenda-display""}",Confusing registration + No countdown,HIGH
|
||||
71,Membership/Community,Social Proof + Conversion,Vibrant & Block-based + Soft UI Evolution,Community brand colors + Engagement,Friendly + Engaging typography,Member counter + Benefit reveals,"{""must_have"": ""member-benefits"", ""must_have"": ""pricing-tiers""}",Hidden benefits + No community proof,HIGH
|
||||
72,Newsletter Platform,Minimal + Conversion,Minimalism + Flat Design,Brand primary + Clean white + CTA,Clean + Readable typography,Subscribe form + Archive reveals,"{""must_have"": ""subscribe-form"", ""must_have"": ""sample-content""}",Complex signup + No preview,MEDIUM
|
||||
73,Digital Products/Downloads,Feature-Rich + Conversion,Vibrant & Block-based + Motion-Driven,Product colors + Brand + Success green,Modern + Clear typography,Product preview + Instant delivery animations,"{""must_have"": ""product-preview"", ""must_have"": ""instant-delivery""}",No preview + Slow delivery,HIGH
|
||||
74,Church/Religious Organization,Hero-Centric + Social Proof,Accessible & Ethical + Soft UI Evolution,Warm Gold + Deep Purple/Blue + White,Welcoming + Clear typography,Service time highlights + Event calendar,"{""must_have"": ""service-times"", ""must_have"": ""community-events""}",Outdated design + Hidden info,MEDIUM
|
||||
75,Sports Team/Club,Hero-Centric + Feature-Rich,Vibrant & Block-based + Motion-Driven,Team colors + Energetic accents,Bold + Impactful typography,Score animations + Schedule reveals,"{""must_have"": ""schedule"", ""must_have"": ""roster""}",Static content + Poor fan engagement,HIGH
|
||||
76,Museum/Gallery,Storytelling + Feature-Rich,Minimalism + Motion-Driven,Art-appropriate neutrals + Exhibition accents,Elegant + Minimal typography,Virtual tour + Collection reveals,"{""must_have"": ""virtual-tour"", ""must_have"": ""exhibition-info""}",Cluttered layout + No online access,HIGH
|
||||
77,Theater/Cinema,Hero-Centric + Conversion,Dark Mode (OLED) + Motion-Driven,Dark + Spotlight accents + Gold,Dramatic + Bold typography,Seat selection + Trailer reveals,"{""must_have"": ""showtimes"", ""must_have"": ""seat-selection""}",Poor booking UX + No trailers,HIGH
|
||||
78,Language Learning App,Feature-Rich + Social Proof,Claymorphism + Vibrant & Block-based,Playful colors + Progress indicators,Friendly + Clear typography,Progress animations + Achievement unlocks,"{""must_have"": ""progress-tracking"", ""must_have"": ""gamification""}",Boring design + No motivation,HIGH
|
||||
79,Coding Bootcamp,Feature-Rich + Social Proof,Dark Mode (OLED) + Minimalism,Code editor colors + Brand + Success,Technical + Clear typography,Terminal animations + Career outcome reveals,"{""must_have"": ""curriculum"", ""must_have"": ""career-outcomes""}",Light mode only + Hidden results,HIGH
|
||||
80,Cybersecurity Platform,Trust & Authority + Real-Time,Cyberpunk UI + Dark Mode (OLED),Matrix Green (#00FF00) + Deep Black,Technical + Clear typography,Threat visualization + Alert animations,"{""must_have"": ""real-time-monitoring"", ""must_have"": ""threat-display""}",Light mode + Poor data viz,HIGH
|
||||
81,Developer Tool / IDE,Minimal + Documentation,Dark Mode (OLED) + Minimalism,Dark syntax theme + Blue focus,Monospace + Functional typography,Syntax highlighting + Command palette,"{""must_have"": ""keyboard-shortcuts"", ""must_have"": ""documentation""}",Light mode default + Slow performance,HIGH
|
||||
82,Biotech / Life Sciences,Storytelling + Data,Glassmorphism + Clean Science,Sterile White + DNA Blue + Life Green,Scientific + Clear typography,Data visualization + Research reveals,"{""must_have"": ""data-accuracy"", ""must_have"": ""clean-aesthetic""}",Cluttered data + Poor credibility,HIGH
|
||||
83,Space Tech / Aerospace,Immersive + Feature-Rich,Holographic/HUD + Dark Mode,Deep Space Black + Star White + Metallic,Futuristic + Precise typography,Telemetry animations + 3D renders,"{""must_have"": ""high-tech-feel"", ""must_have"": ""precision-data""}",Generic design + No immersion,HIGH
|
||||
84,Architecture / Interior,Portfolio + Hero-Centric,Exaggerated Minimalism + High Imagery,Monochrome + Gold Accent + High Imagery,Architectural + Elegant typography,Project gallery + Blueprint reveals,"{""must_have"": ""high-res-images"", ""must_have"": ""project-portfolio""}",Poor imagery + Cluttered layout,HIGH
|
||||
85,Quantum Computing Interface,Immersive + Interactive,Holographic/HUD + Dark Mode,Quantum Blue (#00FFFF) + Deep Black,Futuristic + Scientific typography,Probability visualizations + Qubit state animations,"{""must_have"": ""complexity-visualization"", ""must_have"": ""scientific-credibility""}",Generic tech design + No viz,HIGH
|
||||
86,Biohacking / Longevity App,Data-Dense + Storytelling,Biomimetic/Organic 2.0 + Minimalism,Cellular Pink/Red + DNA Blue + White,Scientific + Clear typography,Biological data viz + Progress animations,"{""must_have"": ""data-privacy"", ""must_have"": ""scientific-credibility""}",Generic health app + No privacy,HIGH
|
||||
87,Autonomous Drone Fleet Manager,Real-Time + Feature-Rich,HUD/Sci-Fi FUI + Real-Time,Tactical Green + Alert Red + Map Dark,Technical + Functional typography,Telemetry animations + 3D spatial awareness,"{""must_have"": ""real-time-telemetry"", ""must_have"": ""safety-alerts""}",Slow updates + Poor spatial viz,HIGH
|
||||
88,Generative Art Platform,Showcase + Feature-Rich,Minimalism + Gen Z Chaos,Neutral (#F5F5F5) + User Content,Minimal + Content-focused typography,Gallery masonry + Minting animations,"{""must_have"": ""fast-loading"", ""must_have"": ""creator-attribution""}",Heavy chrome + Slow loading,HIGH
|
||||
89,Spatial Computing OS / App,Immersive + Interactive,Spatial UI (VisionOS) + Glassmorphism,Frosted Glass + System Colors + Depth,Spatial + Readable typography,Depth hierarchy + Gaze interactions,"{""must_have"": ""depth-hierarchy"", ""must_have"": ""environment-awareness""}",2D design + No spatial depth,HIGH
|
||||
90,Sustainable Energy / Climate Tech,Data + Trust,Organic Biophilic + E-Ink/Paper,Earth Green + Sky Blue + Solar Yellow,Clear + Informative typography,Impact viz + Progress animations,"{""must_have"": ""data-transparency"", ""must_have"": ""impact-visualization""}",Greenwashing + No real data,HIGH
|
||||
91,Personal Finance Tracker,Interactive Product Demo,Glassmorphism + Dark Mode (OLED),Calm blue + success green + alert red + chart accents,Modern + Clear hierarchy,Backdrop blur (10-20px) + Translucent overlays,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_low_performance"": ""fallback-to-flat""}",Pure white backgrounds,HIGH
|
||||
92,Chat & Messaging App,Feature-Rich Showcase + Demo,Minimalism + Micro-interactions,Brand primary + bubble contrast (sender/receiver) + typing grey,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
93,Notes & Writing App,Minimal & Direct,Minimalism + Flat Design,Clean white/cream + minimal accent + editor syntax colors,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
94,Habit Tracker,Social Proof-Focused + Demo,Claymorphism + Vibrant & Block-based,Streak warm (amber/orange) + progress green + motivational accents,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
95,Food Delivery / On-Demand,Hero-Centric Design + Feature-Rich,Vibrant & Block-based + Motion-Driven,Appetizing warm (orange/red) + trust blue + map accent,Energetic + Bold + Large,Scroll animations + Parallax + Page transitions,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Muted colors + Low energy,HIGH
|
||||
96,Ride Hailing / Transportation,Conversion-Optimized + Demo,Minimalism + Glassmorphism,Brand primary + map neutral + status indicator colors,Professional + Clean hierarchy,Backdrop blur (10-20px) + Translucent overlays,"{""if_low_performance"": ""fallback-to-flat"", ""if_conversion_focused"": ""add-urgency-colors""}",Excessive decoration,HIGH
|
||||
97,Recipe & Cooking App,Hero-Centric Design + Feature-Rich,Claymorphism + Vibrant & Block-based,Warm food tones (terracotta/sage/cream) + appetizing imagery,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Muted colors + Low energy,HIGH
|
||||
98,Meditation & Mindfulness,Storytelling-Driven + Social Proof,Neumorphism + Soft UI Evolution,Ultra-calm pastels (lavender/sage/sky) + breathing animation gradient,Subtle + Soft + Monochromatic,Dual shadows (light+dark) + Soft press 150ms,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
99,Weather App,Hero-Centric Design,Glassmorphism + Aurora UI,Atmospheric gradients (sky blue → sunset → storm grey) + temp scale,Modern + Clear hierarchy,Backdrop blur (10-20px) + Translucent overlays,"{""if_low_performance"": ""fallback-to-flat""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
100,Diary & Journal App,Storytelling-Driven,Soft UI Evolution + Minimalism,Warm paper tones (cream/linen) + muted ink + mood-coded accents,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
101,CRM & Client Management,Feature-Rich Showcase + Demo,Flat Design + Minimalism,Professional blue + pipeline stage colors + closed-won green,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
102,Inventory & Stock Management,Feature-Rich Showcase,Flat Design + Minimalism,Functional neutral + status traffic-light (green/amber/red) + scanner accent,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
103,Flashcard & Study Tool,Feature-Rich Showcase + Demo,Claymorphism + Micro-interactions,Playful primary + correct green + incorrect red + progress blue,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
104,Booking & Appointment App,Conversion-Optimized,Soft UI Evolution + Flat Design,Trust blue + available green + booked grey + confirm accent,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_conversion_focused"": ""add-urgency-colors""}",Complex shadows + 3D effects,HIGH
|
||||
105,Invoice & Billing Tool,Conversion-Optimized + Trust,Minimalism + Flat Design,Professional navy + paid green + overdue red + neutral grey,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_conversion_focused"": ""add-urgency-colors""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
106,Grocery & Shopping List,Minimal & Direct + Demo,Flat Design + Vibrant & Block-based,Fresh green + food-category colors + checkmark accent,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects + Muted colors + Low energy,HIGH
|
||||
107,Timer & Pomodoro,Minimal & Direct,Minimalism + Neumorphism,High-contrast on dark + focus red/amber + break green,Professional + Clean hierarchy,Dual shadows (light+dark) + Soft press 150ms,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
108,Parenting & Baby Tracker,Social Proof-Focused + Trust,Claymorphism + Soft UI Evolution,Soft pastels (baby pink/sky blue/mint/peach) + warm accents,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
109,Scanner & Document Manager,Feature-Rich Showcase + Demo,Minimalism + Flat Design,Clean white + camera viewfinder accent + file-type color coding,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
110,Calendar & Scheduling App,Feature-Rich Showcase + Demo,Flat Design + Micro-interactions,Clean blue + event category accent colors + success green,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects,HIGH
|
||||
111,Password Manager,Trust & Authority + Feature-Rich,Minimalism + Accessible & Ethical,Trust blue + security green + dark neutral,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Color-only indicators,HIGH
|
||||
112,Expense Splitter / Bill Split,Minimal & Direct + Demo,Flat Design + Vibrant & Block-based,Success green + alert red + neutral grey + avatar accent colors,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects + Muted colors + Low energy,HIGH
|
||||
113,Voice Recorder & Memo,Interactive Product Demo + Minimal,Minimalism + AI-Native UI,Clean white + recording red + waveform accent,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
114,Bookmark & Read-Later,Minimal & Direct + Demo,Minimalism + Flat Design,Paper warm white + ink neutral + minimal accent + tag colors,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
115,Translator App,Feature-Rich Showcase + Interactive Demo,Flat Design + AI-Native UI,Global blue + neutral grey + language flag accent,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects,HIGH
|
||||
116,Calculator & Unit Converter,Minimal & Direct,Neumorphism + Minimalism,Dark functional + orange operation keys + clear button hierarchy,Professional + Clean hierarchy,Dual shadows (light+dark) + Soft press 150ms,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
117,Alarm & World Clock,Minimal & Direct,Dark Mode (OLED) + Minimalism,Deep dark + ambient glow accent + timezone gradient,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
118,File Manager & Transfer,Feature-Rich Showcase + Demo,Flat Design + Minimalism,"Functional neutral + file type color coding (PDF orange, doc blue, image purple)",Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
119,Email Client,Feature-Rich Showcase + Demo,Flat Design + Minimalism,Clean white + brand primary + priority red + snooze amber,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
120,Casual Puzzle Game,Feature-Rich Showcase + Social Proof,Claymorphism + Vibrant & Block-based,Cheerful pastels + progression gradient + reward gold + bright accent,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
121,Trivia & Quiz Game,Feature-Rich Showcase + Social Proof,Vibrant & Block-based + Micro-interactions,Energetic blue + correct green + incorrect red + leaderboard gold,Energetic + Bold + Large,Haptic feedback + Small 50-100ms animations,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
122,Card & Board Game,Feature-Rich Showcase,3D & Hyperrealism + Flat Design,Game-theme felt green + dark wood + card back patterns,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects,HIGH
|
||||
123,Idle & Clicker Game,Feature-Rich Showcase,Vibrant & Block-based + Motion-Driven,Coin gold + upgrade blue + prestige purple + progress green,Energetic + Bold + Large,Scroll animations + Parallax + Page transitions,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Muted colors + Low energy,HIGH
|
||||
124,Word & Crossword Game,Minimal & Direct + Demo,Minimalism + Flat Design,Clean white + warm letter tiles + success green + shake red,Professional + Clean hierarchy,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration + Complex shadows + 3D effects,HIGH
|
||||
125,Arcade & Retro Game,Feature-Rich Showcase + Hero-Centric,Pixel Art + Retro-Futurism,Neon on black + pixel palette + score gold + danger red,Nostalgic + Monospace + Neon,Subtle hover (200ms) + Smooth transitions,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
126,Photo Editor & Filters,Feature-Rich Showcase + Interactive Demo,Minimalism + Dark Mode (OLED),Dark editor background + vibrant filter preview strip + tool icon accent,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
127,Short Video Editor,Feature-Rich Showcase + Hero-Centric,Dark Mode (OLED) + Motion-Driven,Dark background + timeline track accent colors + effect preview vivid,High contrast + Light on dark,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle""}",Pure white backgrounds,HIGH
|
||||
128,Drawing & Sketching Canvas,Interactive Product Demo + Storytelling,Minimalism + Dark Mode (OLED),Neutral canvas + full-spectrum color picker + tool panel dark,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
129,Music Creation & Beat Maker,Interactive Product Demo + Storytelling,Dark Mode (OLED) + Motion-Driven,Dark studio background + track colors rainbow + waveform accent + BPM pulse,High contrast + Light on dark,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle""}",Pure white backgrounds,HIGH
|
||||
130,Meme & Sticker Maker,Feature-Rich Showcase + Social Proof,Vibrant & Block-based + Flat Design,Bold primary + comedic yellow + viral red + high saturation accent,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_trust_needed"": ""add-testimonials""}",Complex shadows + 3D effects + Muted colors + Low energy,HIGH
|
||||
131,AI Photo & Avatar Generator,Feature-Rich Showcase + Social Proof,AI-Native UI + Aurora UI,AI purple + aurora gradients + before/after neutral,Elegant + Gradient-friendly,Flowing gradients 8-12s + Color morphing,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
132,Link-in-Bio Page Builder,Conversion-Optimized + Social Proof,Vibrant & Block-based + Bento Box Grid,Brand-customizable + accent link color + clean white canvas,Energetic + Bold + Large,Large section gaps 48px+ + Color shift hover + Scroll-snap,"{""if_conversion_focused"": ""add-urgency-colors"", ""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
133,Wardrobe & Outfit Planner,Storytelling-Driven + Feature-Rich,Minimalism + Motion-Driven,Clean fashion neutral + full clothes color palette + accent,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
134,Plant Care Tracker,Storytelling-Driven + Social Proof,Organic Biophilic + Soft UI Evolution,Nature greens + earth brown + sunny yellow reminder + water blue,Warm + Humanist + Natural,Rounded 16-24px + Natural shadows + Flowing SVG,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
135,Book & Reading Tracker,Social Proof-Focused + Feature-Rich,Swiss Modernism 2.0 + Minimalism,Warm paper white + ink brown + reading progress green + book cover colors,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_trust_needed"": ""add-testimonials""}",Excessive decoration,HIGH
|
||||
136,Couple & Relationship App,Storytelling-Driven + Social Proof,Aurora UI + Soft UI Evolution,Warm romantic pink/rose + soft gradient + memory photo tones,Elegant + Gradient-friendly,Flowing gradients 8-12s + Color morphing,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
137,Family Calendar & Chores,Feature-Rich Showcase + Social Proof,Flat Design + Claymorphism,Warm playful + member color coding + chore completion green,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_trust_needed"": ""add-testimonials""}",Complex shadows + 3D effects,HIGH
|
||||
138,Mood Tracker,Storytelling-Driven + Social Proof,Soft UI Evolution + Minimalism,Emotion gradient (blue sad to yellow happy) + pastel per mood + insight accent,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_trust_needed"": ""add-testimonials""}",Excessive decoration,HIGH
|
||||
139,Gift & Wishlist,Minimal & Direct + Conversion,Vibrant & Block-based + Soft UI Evolution,Celebration warm pink/gold/red + category colors + surprise accent,Energetic + Bold + Large,Large section gaps 48px+ + Color shift hover + Scroll-snap,"{""if_conversion_focused"": ""add-urgency-colors""}",Muted colors + Low energy,HIGH
|
||||
140,Running & Cycling GPS,Feature-Rich Showcase + Social Proof,Dark Mode (OLED) + Vibrant & Block-based,Energetic orange + map accent + pace zones (green/yellow/red),High contrast + Light on dark,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Pure white backgrounds + Muted colors + Low energy,HIGH
|
||||
141,Yoga & Stretching Guide,Storytelling-Driven + Social Proof,Organic Biophilic + Soft UI Evolution,Earth calming sage/terracotta/cream + breathing gradient + warm accent,Warm + Humanist + Natural,Rounded 16-24px + Natural shadows + Flowing SVG,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
142,Sleep Tracker,Feature-Rich Showcase + Social Proof,Dark Mode (OLED) + Neumorphism,Deep midnight blue + stars/moon accent + sleep quality gradient (poor red to great green),High contrast + Light on dark,Dual shadows (light+dark) + Soft press 150ms,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Pure white backgrounds,HIGH
|
||||
143,Calorie & Nutrition Counter,Feature-Rich Showcase + Social Proof,Flat Design + Vibrant & Block-based,"Healthy green + macro colors (protein blue, carb orange, fat yellow) + progress circle",Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_trust_needed"": ""add-testimonials""}",Complex shadows + 3D effects + Muted colors + Low energy,HIGH
|
||||
144,Period & Cycle Tracker,Social Proof-Focused + Trust,Soft UI Evolution + Aurora UI,Rose/blush + lavender + fertility green + soft calendar tones,Elegant + Gradient-friendly,Flowing gradients 8-12s + Color morphing,"{""if_trust_needed"": ""add-testimonials""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
145,Medication & Pill Reminder,Trust & Authority + Feature-Rich,Accessible & Ethical + Flat Design,Medical trust blue + missed alert red + taken green + clean white,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects + Color-only indicators,HIGH
|
||||
146,Water & Hydration Reminder,Minimal & Direct + Demo,Claymorphism + Vibrant & Block-based,Refreshing blue + water wave animation + goal progress accent,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Muted colors + Low energy,HIGH
|
||||
147,Fasting & Intermittent Timer,Feature-Rich Showcase + Social Proof,Minimalism + Dark Mode (OLED),Fasting deep blue/purple + eating window green + timeline neutral,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
148,Anonymous Community / Confession,Social Proof-Focused + Feature-Rich,Dark Mode (OLED) + Minimalism,Dark protective + subtle gradient + upvote green + empathy warm accent,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
149,Local Events & Discovery,Hero-Centric Design + Feature-Rich,Vibrant & Block-based + Motion-Driven,City vibrant + event category colors + map accent + date highlight,Energetic + Bold + Large,Scroll animations + Parallax + Page transitions,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Muted colors + Low energy,HIGH
|
||||
150,Study Together / Virtual Coworking,Social Proof-Focused + Feature-Rich,Minimalism + Soft UI Evolution,Calm focus blue + session progress indicator + ambient warm neutrals,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_trust_needed"": ""add-testimonials""}",Excessive decoration,HIGH
|
||||
151,Coding Challenge & Practice,Feature-Rich Showcase + Social Proof,Dark Mode (OLED) + Cyberpunk UI,Code editor dark + success green + difficulty gradient (easy green / medium amber / hard red),High contrast + Light on dark,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Pure white backgrounds,HIGH
|
||||
152,Kids Learning (ABC & Math),Social Proof-Focused + Trust,Claymorphism + Vibrant & Block-based,Bright primary + child-safe pastels + reward gold + interactive accent,Playful + Rounded + Friendly,Multi-layer shadows + Spring bounce + Soft press 200ms,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
153,Music Instrument Learning,Interactive Product Demo + Social Proof,Vibrant & Block-based + Motion-Driven,Musical warm deep red/brown + note color system + skill progress bar,Energetic + Bold + Large,Scroll animations + Parallax + Page transitions,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
154,Parking Finder,Conversion-Optimized + Feature-Rich,Minimalism + Glassmorphism,Trust blue + available green + occupied red + map neutral,Professional + Clean hierarchy,Backdrop blur (10-20px) + Translucent overlays,"{""if_low_performance"": ""fallback-to-flat"", ""if_conversion_focused"": ""add-urgency-colors""}",Excessive decoration,HIGH
|
||||
155,Public Transit Guide,Feature-Rich Showcase + Interactive Demo,Flat Design + Accessible & Ethical,Transit brand line colors + real-time indicator green/red + map neutral,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Complex shadows + 3D effects + Color-only indicators,HIGH
|
||||
156,Road Trip Planner,Storytelling-Driven + Hero-Centric,Aurora UI + Organic Biophilic,Adventure warm sunset orange + map teal + stop markers + road neutral,Elegant + Gradient-friendly,Flowing gradients 8-12s + Color morphing,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Inconsistent styling + Poor contrast ratios,HIGH
|
||||
157,VPN & Privacy Tool,Trust & Authority + Conversion-Optimized,Minimalism + Dark Mode (OLED),Dark shield blue + connected green + disconnected red + trust accent,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_conversion_focused"": ""add-urgency-colors""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
158,Emergency SOS & Safety,Trust & Authority + Social Proof,Accessible & Ethical + Flat Design,Alert red + safety blue + location green + high contrast critical,Bold + Clean + Sans-serif,Color shift hover + Fast 150ms transitions + No shadows,"{""if_trust_needed"": ""add-testimonials""}",Complex shadows + 3D effects + Color-only indicators,HIGH
|
||||
159,Wallpaper & Theme App,Feature-Rich Showcase + Social Proof,Vibrant & Block-based + Aurora UI,Content-driven + trending aesthetic palettes + download accent,Energetic + Bold + Large,Large section gaps 48px+ + Color shift hover + Scroll-snap,"{""if_trust_needed"": ""add-testimonials""}",Muted colors + Low energy,HIGH
|
||||
160,White Noise & Ambient Sound,Minimal & Direct + Social Proof,Minimalism + Dark Mode (OLED),Calming dark + ambient texture visual + subtle sound wave + sleep blue,Professional + Clean hierarchy,Subtle glow + Neon accents + High contrast,"{""if_light_mode_needed"": ""provide-theme-toggle"", ""if_trust_needed"": ""add-testimonials""}",Excessive decoration + Pure white backgrounds,HIGH
|
||||
161,Home Decoration & Interior Design,Storytelling-Driven + Feature-Rich,Minimalism + 3D Product Preview,Neutral interior palette + material texture accent + AR blue,Professional + Clean hierarchy,Subtle hover 200ms + Smooth transitions + Clean,"{""if_ux_focused"": ""prioritize-clarity"", ""if_mobile"": ""optimize-touch-targets""}",Excessive decoration,HIGH
|
||||
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue