cyc-stack 0.0.0-stage → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +108 -0
  8. package/LICENSE +21 -0
  9. package/README.md +359 -2
  10. package/bin/cyc.mjs +285 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +99 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +196 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +247 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +102 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +84 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +93 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/check-response.mjs +13 -0
  80. package/scripts/claude-project-hook.mjs +12 -0
  81. package/scripts/context-review.mjs +600 -0
  82. package/scripts/host-activation.mjs +66 -0
  83. package/scripts/install.mjs +387 -0
  84. package/scripts/onboarding.mjs +110 -0
  85. package/scripts/packet.mjs +107 -0
  86. package/scripts/project-tools.mjs +196 -0
  87. package/scripts/recovery.mjs +66 -0
  88. package/scripts/response-gate.mjs +105 -0
  89. package/scripts/response-hook.mjs +237 -0
  90. package/scripts/response-mode.mjs +12 -0
  91. package/scripts/run-gate.mjs +264 -0
  92. package/scripts/runtime.mjs +1723 -0
  93. package/scripts/source-hash-worker.mjs +5 -0
  94. package/scripts/source-snapshot.mjs +405 -0
  95. package/scripts/test-output.mjs +258 -0
  96. package/scripts/work-review.mjs +257 -0
  97. package/skills/cyc/SKILL.md +130 -0
  98. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  99. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  100. package/skills/cyc/references/playbooks/experience.md +7 -0
  101. package/skills/cyc/references/playbooks/explore.md +9 -0
  102. package/skills/cyc/references/playbooks/feature.md +14 -0
  103. package/skills/cyc/references/playbooks/handoff.md +11 -0
  104. package/skills/cyc/references/playbooks/investigation.md +7 -0
  105. package/skills/cyc/references/playbooks/performance.md +7 -0
  106. package/skills/cyc/references/playbooks/plan.md +11 -0
  107. package/skills/cyc/references/playbooks/refactor.md +12 -0
  108. package/skills/cyc/references/playbooks/reflect.md +11 -0
  109. package/skills/cyc/references/playbooks/resume.md +11 -0
  110. package/skills/cyc/references/playbooks/review.md +9 -0
  111. package/skills/cyc/references/playbooks/teach.md +11 -0
  112. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: cyc-correct
3
+ description: "Turn user feedback or a repeated miss into a named missing criterion and a targeted fix, instead of another variant. Use when the user says \"that's not it\", \"still wrong\", or \"this feels off\", when a revision misses the same way twice, or when feedback reveals an unstated requirement."
4
+ ---
5
+
6
+ # Turn feedback into a correction
7
+
8
+ A correction is information: it tells you which criterion was missing or which mental model was wrong. Producing another variant without finding that is guessing. Follow the [handoff contract](../../docs/skill-contract.md).
9
+
10
+ ## The core loop
11
+
12
+ 1. **Quote the feedback exactly.** Keep the user's words separate from your interpretation.
13
+ 2. **Locate the mismatch in the artifact.** Point at the part that fails. For vague feedback ("feels disconnected", "too busy"), check the structural causes first: grouping, order, transitions, and the user's path through it. Spacing and color are usually symptoms.
14
+ 3. **Name the missing criterion.** Write it as an observable check: "Each section leads into the next with a visible connection." Add it to the task's criteria. Existing criteria stay unless the user removes them.
15
+ 4. **Classify it.** Is it a fact about this task, the user's preference, a project convention, or a reusable rule? Only the task fact goes into the current frame by default. The others are candidates for [Reflect](../cyc-reflect/SKILL.md) and need the user's say-so before they become rules.
16
+ 5. **Pick the responsible stage.** Wrong code: fix it in [Build](../cyc-build/SKILL.md). Wrong goal, missed dependency, or wrong shape: rethink the plan (`run retry --stage scout` in fast playbooks; [Frame](../cyc-frame/SKILL.md), [Impact](../cyc-impact/SKILL.md), or [Design](../cyc-design/SKILL.md) in the detailed chain).
17
+ 6. **Fix the cause, then check both.** Check the new criterion and the old ones together. A fix that satisfies the feedback but breaks an earlier requirement is not a fix.
18
+ 7. **If unsure what they mean, restate before revising.** Re-pitch the problem in plain language ("So the issue is that the steps don't feel like one journey, not that it looks cluttered?") rather than guessing with another draft.
19
+
20
+ ## Codify manual checks
21
+
22
+ If the feedback came from the user checking something by hand ("the page jumps when it loads", "the console shows an error", "it takes three seconds"), that is a missing verification step. Add it to the project's verify recipe as a measurable check (see [Verify](../cyc-verify/references/recipe.md)) so the next run catches it without the user. During an active run, record it in `.cyc/runs/<runId>/proposed-checks.json` and apply it after the run completes.
23
+
24
+ ## Done when
25
+
26
+ The feedback maps to a named criterion, the criterion is recorded with the task, the fix addresses its cause, and both new and existing criteria were checked.
27
+
28
+ ## Stop rule
29
+
30
+ Two corrections on the same point that both missed: stop revising. Write down the assumption both attempts share and ask the user one sharp question that tests it.
31
+
32
+ ## Anti-patterns
33
+
34
+ | Name | The tell | Fix |
35
+ | --- | --- | --- |
36
+ | Variant spray | Producing three new versions after "not quite" | Name the missing criterion first |
37
+ | Surface fix | "Feels off" answered by changing padding | Check structure and journey first |
38
+ | Silent drop | The fix quietly removes an earlier requirement | Recheck all criteria together |
39
+ | Global from local | One correction becomes a permanent rule | Classify it; ask before promoting |
40
+
41
+ ## Handoff
42
+
43
+ Return the quoted feedback, the named criterion, its classification, the stage that fixed it, and the check results.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: cyc-deliver
3
+ description: "Write the final handoff: result first, evidence labeled in the same sentence, one useful visual, and honest limits. Use at the end of any CYC task, when handing off to another person or session, or when a blocker stops the work."
4
+ ---
5
+
6
+ # Deliver the result
7
+
8
+ The reader should know in ten seconds what happened and whether to trust it. Follow the [response standard](../../docs/response-standard.md) and [handoff contract](../../docs/skill-contract.md).
9
+
10
+ Leave the engineer able to follow and maintain the change: summarize the before/after mechanism, the consequential choice, and where to find the relevant check and retained context. Reuse the shared review and existing evidence rather than adding a teaching report. Self-review the [engineering understanding criteria](../../docs/response-standard.md#engineering-understanding-throughout-the-work); do not claim comprehension merely because explanations were supplied.
11
+
12
+ ## The core loop
13
+
14
+ 1. **Lead with the result or the blocker.** First sentence: what now works, or what stopped you. "Homework can now be marked finished and it survives reload."
15
+ 2. **Label each claim in the same sentence.** *Ran*: "the persistence test fails on the old code and passes now." *Read*: "the reminder job skips unknown fields (read, not run)." *Didn't check*: "cross-device sync is untested." For code changes, name the decisive regression test or its precise review location alongside the command/result so a maintainer can find the assertion; this does not apply to conversation-only work. Never hand the reader a check you could have run yourself.
16
+ 3. **Frame impact for the user, then the maintainer.** What they will see, then what changed in the code.
17
+ 4. **Include and display one visual that carries information, even under the 1,000-character limit.** Choose it with the answer: a diagram or labeled flow for processes and relationships, a data chart for quantities, a before/after for changes, or a table for comparisons and status. Use available rendering tools when helpful; otherwise use a readable text flow. A bare link, decoration, or a table that restates the paragraph above it doesn't count. Check that the visual makes the main idea easier to grasp, not merely that its markup passes the gate. Every number or output in it must be one you observed this run: take "before" values from running the original code, never from reading it. If you did not run the old code, describe the change without a before-value.
18
+ 5. **Use the shared review artifact.** Link `.cyc/runs/ID/review.md`, generated from handoffs and receipts, alongside relevant files/diffs. Refresh it with `run review` after external changes and reuse it for an authorized PR. Update underlying records rather than maintaining competing reports.
19
+ 6. **Retain what the next task needs.** Follow the [Deliver assessment](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order): record verified reusable facts, actual adopted decisions, and error history with evidence and limits; keep unverified hypotheses or undecided proposals explicit in run-local notes. Name the canonical component/index path so a teammate can find the learning; identify local-only evidence. Bug fixes and recorded failures require the selected `ledgerPath`; when run-local, explain in `errorHistory.reason` that shared-log promotion remains pending authorized scope. Do not claim the shared log was updated. Finalize durable updates before final verification; source changes afterwards require fresh Verify. No reusable finding is a valid `learning: none` with a reason. The Deliver handoff records `contextDocs`, the component docs under `docs/context/` among the artifacts and `learning.artifacts`; a mapped component whose doc the run did not touch is what `cyc context review --run ID` proposes an entry for, from the run's record, and `--write` appends it and refreshes the index (see [Context](../cyc-context/SKILL.md)).
20
+ 7. **Check session readiness and say what is left.** The latest run's completion is not the whole session's readiness. Codex/Claude `packet` preflight includes current-request run status; `cyc readiness --session ID` provides a read-only diagnosis. Without mapped hook state, supply the actual request start with `--since ISO_TIMESTAMP`; that explicit window does not replace the Stop hook. Cursor packet preflight leaves controller readiness unverified, so inspect its actual request window separately. Preserve stopped originals and failed attempts; do not start replacements or change a cutoff to evade a block. Disclose accepted pre-existing failures (each with its reason), unverified rows, known limits, and a decision only if one remains. No forced "next task."
21
+
22
+ ## Shape for code work
23
+
24
+ ```text
25
+ Result: one or two sentences.
26
+
27
+ [One displayed visual: changed flow, before/after, or criteria table,
28
+ chosen for what the reader needs to understand.]
29
+
30
+ Changed: files and why (short).
31
+ Not covered: what wasn't checked and why.
32
+ Your call: a decision, only if one exists.
33
+ ```
34
+
35
+ ## Done when
36
+
37
+ The first sentence states the result or the blocker. Every claim has a label. The visual is included in the response, its form fits the subject, and it adds understanding. Limits are stated. The length honors the conversation's `limit on` or `limit off` setting; shortening prose must not silently remove the visual.
38
+
39
+ If the host gate provides a review token and packet path: in Claude Code and Codex, a completed `run finish` writes the packet from the run's record, and the Stop gate checks the reply itself. Otherwise (no completed run, files changed after finish, or Cursor) write it with `cyc packet`; Cursor's packet carries the exact final response. Before sending, draft the reply in `.cyc/runtime/reply.md` and run `cyc check-reply .cyc/runtime/reply.md --session <ID>`: it reports the character count, how much to cut, and whether the visual is recognized, writes nothing, and is the same check the gate applies. If hooks aren't active, say that automatic enforcement is unverified.
40
+
41
+ ## Anti-patterns
42
+
43
+ | Name | The tell | Fix |
44
+ | --- | --- | --- |
45
+ | Buried lead | Three sentences of process before the result | Result first |
46
+ | Unlabeled claim | "Everything works" | Say what was run, read, or unchecked |
47
+ | Log replay | Narrating each step taken | Report outcomes, link logs |
48
+ | Decoration | An emoji or a table that repeats the prose | Use a visual that adds facts |
49
+ | Reconstructed before-value | A before/after row whose "before" was worked out by reading old code | Run the old code, or drop the before-value |
50
+ | Hedge fog | "Should probably mostly work" | State what's proven and what isn't, plainly |
51
+
52
+ A blocked handoff starts with "Blocked:", names the missing prerequisite, and names the smallest action the user can take. It is never presented as done. If verification failed, send the work back to its stage instead of polishing the summary.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: cyc-design
3
+ description: "Choose the shape of a change (data, interfaces, and the steps to build it) before writing logic. Use before any change that adds state, changes a data shape or interface, spans several files, or after a build shows the current design is wrong."
4
+ ---
5
+
6
+ # Design the change
7
+
8
+ Get the shape right before the logic. Most rework comes from a wrong data shape or interface, not a wrong line of code. Follow the [handoff contract](../../docs/skill-contract.md).
9
+
10
+ For web interface creation or visual redesign, use the [frontend design method](frontend-design/SKILL.md) alongside this one. Its decision sheet (archetype, type, palette, signature element, rejection condition) is the visual counterpart of the caller sketch and data shape below; the architectural questions here still apply when state or interfaces change. A narrow UI repair should preserve the existing identity and use only relevant checks.
11
+
12
+ ## The core loop
13
+
14
+ 1. **Write the caller's code first.** Sketch how the change will be used from the outside: the call site, the component props, the API request. Then derive the types and signatures from that usage. If the sketch is awkward to call, the interface is wrong.
15
+ 2. **Name the data shape.** Write the actual type or record, including what old data looks like and how it maps into the new shape. "Add `finished: boolean`, defaulting to `false` when missing on load."
16
+ 3. **Resolve consequential alternatives.** When ownership or the public contract remains uncertain, compare genuinely different shapes against the requirements and choose with a reason. A cosmetic variation is not an alternative. Reuse a sound established project pattern without manufacturing another design; name the pattern and why it fits. For large or risky unresolved choices, independent alternatives can help answer a specific question.
17
+ 4. **Screen ownership and boundaries.** Use the [architecture questions and counter-cases](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract). Locate authoritative state and repeated policy; check that the interface hides meaningful decisions and legitimate callers cannot bypass its invariant. Preserve meaningful adapters, domain helpers, and compatibility behavior. Do not split or remove code solely because of its length, caller count, or execution order.
18
+ 5. **Check the whole experience, not only the part.** Walk the user's complete path through the change. A section that is better on its own can make the whole page or flow feel disconnected. If the design improves one step but breaks the flow between steps, it is not done.
19
+ 6. **Reuse before you add.** Prefer the project's existing store, helper, or pattern when it meets the requirement. A new dependency or layer needs a reason tied to a criterion.
20
+ 7. **Slice it vertically.** Order the build as thin end-to-end slices (a tracer bullet first: one path working through every layer), each with the check from Verify's matrix that proves it.
21
+ 8. **Write the scrap conditions.** What observation during build would mean this design is wrong? Examples: the same workaround needed twice, an escape-hatch type (`any`, casts), a sudden need for locks.
22
+
23
+ ## Done when
24
+
25
+ - The caller sketch and data shape are written down.
26
+ - Consequential design uncertainty was resolved through a concrete comparison, or the fitting project pattern is identified.
27
+ - Every acceptance criterion maps to a slice and a check.
28
+ - For user-facing changes, the full journey was walked and still holds together.
29
+ - Scrap conditions are listed.
30
+ - Build could proceed without inventing a product decision.
31
+
32
+ For a one-file change, this can be five lines. Do not inflate it.
33
+
34
+ ## Output
35
+
36
+ Chosen approach and why; alternatives considered and why not; data shape and legacy mapping; caller sketch; ordered slices with checks; scrap conditions; open decisions for the user.
37
+
38
+ ## Anti-patterns
39
+
40
+ | Name | The tell | Fix |
41
+ | --- | --- | --- |
42
+ | Logic first | Writing functions before the type exists | Stop and write the shape |
43
+ | Unexamined choice | An uncertain ownership or contract decision is asserted without evidence | Compare a real alternative against the requirement |
44
+ | Horizontal plan | "Step 1: all the types. Step 2: all the UI" | Reorder as vertical slices |
45
+ | Polished fragment | One component improved; the page now feels stitched together | Walk the whole journey |
46
+ | Infrastructure for its own sake | New service or library with no criterion needing it | Reuse the existing mechanism |
47
+
48
+ ## Handoff
49
+
50
+ Pass the design to [Build](../cyc-build/SKILL.md). If the design changes a shared dependency, update the [impact map](../cyc-impact/SKILL.md) first. If build hits a scrap condition, come back here with the observation; keep what still holds.
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: frontend-design
3
+ description: "Build web interfaces a reviewer cannot mistake for a default AI page. Three gates: a written design decision sheet before any markup, the signature section rendered and scored against the generic-tells list before the page is extended, and a set-divergence table when several sites are requested. Use for new websites, pages, dashboards and visual redesigns. For a narrow UI bug, keep the existing identity and use only the relevant checks."
4
+ ---
5
+
6
+ # Frontend design
7
+
8
+ The page a model writes without instructions is recognizable at a glance: a centered hero, one sans-serif font, three equal cards with icons, a blue or violet accent, rounded corners and soft shadows on everything, the same container and padding in every section. Every site built that way looks like every other site built that way. This method makes that output impossible to ship by requiring three things you can show.
9
+
10
+ ## Gate 1: the decision sheet exists before any markup
11
+
12
+ Write `design/decisions.md` in the project (or in the run directory when the project forbids new files) using the [decision sheet](references/decision-sheet.md). Every field holds a concrete value: a named typeface pair, eight hex values with roles and their contrast ratios, a layout archetype by name, a signature element, the visual material by kind and source (a photograph stored in `/assets` with its license, a rendered object, an illustration with depth), three candidate headlines in the product's own voice. "Warm and modern" is not a value, and "none, strong type instead" is not a material plan for a site; a tool-dense dashboard may have no photograph, a café, a portfolio or a service may not. Read these first; they are short and they are where the values come from:
13
+
14
+ - [Generic tells](references/generic-tells.md): the default page, numbered, and what replaces each tell.
15
+ - [Typography](references/typography.md): pairings with character notes, sizes, tracking and loading.
16
+ - [Color](references/color.md): deriving a palette from the subject, token roles, example palettes.
17
+ - [Layout archetypes](references/layout-archetypes.md): nine compositions with CSS skeletons. Archetype 0 is the banned default.
18
+ - [Visual material](references/visual-material.md): what counts as imagery, how much a page needs, and how to source photographs when everything must stay local.
19
+ - [Reference standards](references/reference-standards.md): what the sites held up as the bar actually do, with observed values.
20
+
21
+ When several sites or identities are requested, the sheet includes the set-divergence table: no two sites share a layout archetype, a display face, a palette temperature or a hero mechanism. Fill the table before building the first site. A model building five sites in a row reuses its own scaffolding unless divergence is decided up front.
22
+
23
+ Keep the user's criterion count. Visual quality is a subcondition with a rejection condition ("fail if the opening could belong to any café in any city"), not an extra criterion.
24
+
25
+ ## Gate 2: the signature section is rendered and scored before the page is extended
26
+
27
+ Build the one section that carries the identity (usually the opening; for a tool or portfolio, the tool or the work) in the real page: final copy, the chosen material actually in place (the downloaded photograph, the rendered board, not a placeholder rectangle), the main action and its next state, and the transition into the next section. Render it at desktop and phone width. Score it with the [generic-tells score sheet](references/generic-tells.md#score-sheet). Three or more tells is a fail, and the fix is a different decision (archetype, type, imagery, copy), not a color swap. Then apply the [craft rules](references/craft-rules.md) and extend the treatment to the rest of the page.
28
+
29
+ Writing the whole site and taking screenshots at the end skips this gate. Do not skip it.
30
+
31
+ ## Gate 3: the finished page passes the tells check and the experience review
32
+
33
+ Score the full page at desktop and phone width, including the [density rule](references/visual-material.md#the-density-rule) for material, then run the [experience review](references/experience-review.md) (visual pass, primary-task pass, access pass) with the applicable [UX foundations](references/ux-foundations.md). The access pass includes an executed check, not a reading: axe-core or an equivalent in the rendered page at desktop and phone width, with the contrast ratios and target sizes it reports recorded in the evidence. A contrast rule "computed, not eyeballed" that nobody ran is how a page with a perfect tells score still ships 4.0:1 numerals. Test the decision sheet's rejection condition directly. A page that works, passes every automated check and still reads as a default page has an unmet visual criterion. Say so; do not shrink the criterion to fit the page.
34
+
35
+ For a set, lay the openings side by side at the same width and the full scrolls side by side. Cover the names and the colors. What remains different must be composition, type, imagery and voice.
36
+
37
+ ## What this method does not require
38
+
39
+ No mascot, animation, asymmetry or paid assets. A conventional grid in a well-chosen face, with a palette derived from the subject and copy full of that business's nouns, beats a novelty layout. When the project already has a brand system, the decision sheet records it and the gates check adherence to it instead. A narrow repair keeps the existing identity and runs only the relevant checks. Nothing here is machine-enforced; the controller cannot judge taste, so the rendered evidence and the scored sheet are the proof.
40
+
41
+ ## Handoff
42
+
43
+ Pass the decision sheet, the rendered evidence at both widths, the tells scores and the review findings through [Build](../../cyc-build/SKILL.md) and [Verify](../../cyc-verify/SKILL.md). Keep `design/decisions.md` in the repository so the next change can read why the page looks the way it does.
@@ -0,0 +1,77 @@
1
+ # Color
2
+
3
+ A palette is derived from the subject, then expressed as eight tokens with roles, then checked with a contrast script before any markup. A palette chosen from a swatch of pleasant blues is tell 11 on the [generic list](generic-tells.md). An accent that reads well as a 100 px word and fails as a 16 px label is the most common way a good palette ships inaccessible text, so the accent has two values.
4
+
5
+ ## Derive it from the subject
6
+
7
+ Name two materials and one place or time that belong to this business, then take the colors from them.
8
+
9
+ | Subject | Materials and place | What falls out |
10
+ | --- | --- | --- |
11
+ | Café | Espresso, crema, cream paper, a wooden counter in morning light | Deep brown brand, warm cream canvas, a caramel accent |
12
+ | Photographer | Darkroom, silver print, matte black paper, one warm safelight | Near-black canvas or warm white, silver-gray muted ink, one brass accent |
13
+ | Catalog | Paper stock, ink, one signal color for "in stock" or "selected" | Paper-white canvas, true ink, one vermilion or cobalt signal, nothing else |
14
+ | Event | The venue at night, stage light, the wristband | Deep night canvas, one hot accent, warm white ink |
15
+ | Home repair | Workwear navy, safety orange, plaster white, galvanized steel | Navy brand, warm off-white canvas, orange accent, steel line color |
16
+ | Careers or finance | Forest green, aged paper, gold leaf | Deep green brand, cream canvas, gold accent (observed at Undersold.ai) |
17
+ | Daily health tool | Sage, linen, morning light | Sage-tinted canvas, forest brand, muted green ink (observed in Rep & Plate) |
18
+
19
+ A user-supplied brand always wins. Record it in the decision sheet and derive the missing roles from it.
20
+
21
+ ## Eight roles
22
+
23
+ ```css
24
+ :root {
25
+ --canvas: ...; /* page background, tinted, never #ffffff */
26
+ --surface: ...; /* cards, inputs, panels; one step off the canvas */
27
+ --ink: ...; /* body text, tinted toward the brand hue, never #000000 */
28
+ --ink-muted: ...; /* secondary text; still 4.5:1 on canvas and surface */
29
+ --brand: ...; /* the deep color: primary buttons, the dark section, the mark */
30
+ --accent: ...; /* marks, underlines, rules, display words of 24 px or more, text on the dark band */
31
+ --accent-ink: ...; /* the accent darkened (or lightened on a dark canvas) until it reaches 4.5:1; every accent-colored text under 24 px, and the background of an accent button */
32
+ --line: ...; /* hairline rules and borders, derived from canvas, not gray */
33
+ }
34
+ ```
35
+
36
+ Rules:
37
+
38
+ - The canvas is tinted. Cream `#f8f5ee`, bone `#f5f2ec`, sage `#f3f8f5`, cool paper `#f4f5f7`, charcoal `#141414`. Pure white is for a surface sitting on a tinted canvas, if at all.
39
+ - Ink carries the brand hue: `#171b18` on a green site, `#2a1f16` on a brown site, `#101828` on a blue site. Gray-on-white text is the default page.
40
+ - One accent, under 10 percent of the view. The brand color does the heavy lifting (buttons, the dark section). The accent marks the two words that matter, a rule under them, one number, one state.
41
+ - `--accent` touches text only at display size (24 px and up, or 19 px bold), where 3:1 is the requirement, and only when the script's "accent display" line passes; on a light canvas most accents do not, and the display word then uses `--accent-ink` too. Index numerals, dates, prices, eyebrow labels, links and button labels in the accent hue use `--accent-ink`. Undersold.ai does exactly this: bright gold `#e5a128` for the underline and for text on the green band, dark gold `#805000` for the handwritten phrase on cream.
42
+ - Exactly one dark section per page, in the brand color, unless the whole site is dark. Its text is the canvas color, not white; the accent is usually fine there, check it.
43
+ - Surfaces come from mixing, not from a gray scale: `color-mix(in oklab, var(--brand) 6%, var(--canvas))` gives a surface that belongs to the palette.
44
+ - Status (error, success, warning) gets its own hue and an icon or text; never color alone.
45
+
46
+ ## Check it before writing markup
47
+
48
+ Contrast is computed, not eyeballed. Run this on the eight values (Node, no dependencies) and paste the output into the decision sheet; the finished page is then checked again in the browser with axe-core or an equivalent (see [experience review](experience-review.md)).
49
+
50
+ ```js
51
+ // node contrast.mjs "#canvas" "#surface" "#ink" "#ink-muted" "#brand" "#accent" "#accent-ink" "#line"
52
+ const [canvas, surface, ink, muted, brand, accent, accentInk] = process.argv.slice(2);
53
+ const lum = h => { const c = h.slice(1).match(/../g).map(x => parseInt(x, 16) / 255).map(v => v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4); return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]; };
54
+ const cr = (a, b) => ((Math.max(lum(a), lum(b)) + 0.05) / (Math.min(lum(a), lum(b)) + 0.05)).toFixed(2);
55
+ const pairs = [['ink on canvas', ink, canvas, 4.5], ['ink on surface', ink, surface, 4.5], ['muted on canvas', muted, canvas, 4.5], ['muted on surface', muted, surface, 4.5], ['canvas text on brand', canvas, brand, 4.5], ['accent-ink on canvas', accentInk, canvas, 4.5], ['accent-ink on surface', accentInk, surface, 4.5], ['canvas text on accent-ink', canvas, accentInk, 4.5], ['accent display on canvas', accent, canvas, 3], ['accent on brand', accent, brand, 3]];
56
+ for (const [name, a, b, min] of pairs) console.log(`${cr(a, b) >= min ? 'pass' : 'FAIL'} ${name}: ${cr(a, b)} (min ${min})`);
57
+ ```
58
+
59
+ Any FAIL means a different value, not a smaller font. Derive `--accent-ink` by mixing the accent toward the ink until the pair passes; keep the hue.
60
+
61
+ ## Example palettes
62
+
63
+ Starting points to adapt. Eight values in the order canvas, surface, ink, ink-muted, brand, accent, accent-ink, line. Every accent-ink below was computed to 4.6:1 or better on its canvas and surface on 2026-11-02; the plain accent on a light canvas is 1.8 to 3.7:1, so there it is for underlines, rules, marks and text on the dark band; only the catalog and home-repair accents clear 3:1 for display words.
64
+
65
+ | Subject | Values |
66
+ | --- | --- |
67
+ | Café, espresso | `#f6efe4` `#fff9ef` `#2a1f16` `#6d5d50` `#3b2419` `#c9772b` `#995d25` `#e4d6c3` |
68
+ | Photographer, dark | `#111111` `#1a1a1a` `#f2efe9` `#9a9690` `#f2efe9` `#d9c58b` `#d9c58b` `#2a2a2a` |
69
+ | Photographer, light | `#f7f5f0` `#ffffff` `#161616` `#6a6660` `#161616` `#b8952e` `#846c26` `#e2ddd3` |
70
+ | Catalog, paper and signal | `#f4f4f1` `#ffffff` `#121417` `#5b6066` `#121417` `#e8412c` `#c83a29` `#d9d9d4` |
71
+ | Event, night | `#0f0e17` `#1b1930` `#fffffe` `#a7a9be` `#ff8906` `#e53170` `#e84880` `#2e2b4a` |
72
+ | Home repair, workwear | `#f3f4f1` `#ffffff` `#15202b` `#55606b` `#1f3a5f` `#e4572e` `#b94b2d` `#d6dad3` |
73
+ | Careers, green and gold | `#f8f5ee` `#fffaf0` `#171b18` `#5c625d` `#104034` `#e5a128` `#8e6921` `#e3ddd0` |
74
+ | Daily tool, sage | `#f8faf7` `#ffffff` `#102333` `#5f6b66` `#17674e` `#c9a24a` `#817041` `#d5e1dd` |
75
+ | Software, restrained | `#fbfbf9` `#ffffff` `#101828` `#5d6675` `#0c4a3a` `#ffb000` `#936c12` `#e3e5e0` |
76
+
77
+ For a set of sites, no two palettes share a temperature and a brand hue family. Two warm-cream sites with brown and green brands are still two cream sites; make one of them dark or cool.
@@ -0,0 +1,61 @@
1
+ # Craft rules
2
+
3
+ Execution rules with numbers, applied after the signature section passes the [tells score](generic-tells.md#score-sheet) and before the treatment is extended. They make the page consistent; they do not choose its identity.
4
+
5
+ ## Spacing and containers
6
+
7
+ - One spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 px. Section padding 96 to 128 px on desktop, 56 to 72 px on a phone, and not the same in every section.
8
+ - Three widths, not one: full bleed for images and bands, about 1280 px for grids, about 720 px (or 65 ch) for reading. A page where everything sits in the same centered 1200 px box is tell 3.
9
+ - Phone gutters 16 to 20 px. Primary tap targets at least 44 px tall; checkboxes and radios 24 px or larger, or their label row at least 44 px tall and clickable.
10
+
11
+ ## Surfaces
12
+
13
+ - One radius for the whole site, chosen from 0, 4, 8 or 999 (pill). Cards at 16, buttons at 8 and badges at 999 on the same page is the default look.
14
+ - One surface system: hairline borders (`--line`) on a tinted canvas, or flat color blocks, or sharp-edged panels. Shadows only on things that actually float (a menu, a dialog, a dragged item).
15
+ - Exactly one dark section on a light site. Its text is the canvas color, not white.
16
+
17
+ ## Imagery
18
+
19
+ - Every image has a reason recorded in the decision sheet: which subject, why this crop, what it proves.
20
+ - `aspect-ratio` set and `object-fit: cover`; crop for the layout, not the other way round. Decide `object-position` for the phone crop separately.
21
+ - One treatment across the site: all warm, or all duotone, or all with a 1 px line, or all untouched. Mixed treatments read as stock.
22
+ - No photograph yet: get one (see [visual material](visual-material.md), which covers local-only builds), or render the product as an object and draw an illustration with depth. Never a gray box with an icon, and never a page of type and rules; that is tell 21.
23
+ - Local-only sites store assets in the repository with their source and license noted.
24
+
25
+ ## Icons and marks
26
+
27
+ - One icon set (Lucide, Phosphor, Heroicons, Tabler), one stroke width, 20 or 24 px, inline SVG. No emoji.
28
+ - A wordmark set in the display face is a logo. Add a mark only if it means something.
29
+
30
+ ## Details that signal craft
31
+
32
+ - Eyebrow labels (uppercase, tracked, 11 to 13 px) above display text and section headings, saying something specific.
33
+ - Index numerals (01, 02) on lists and steps, set in the display face.
34
+ - Hairline rules between rows instead of boxes around them.
35
+ - Captions under images; meta lines under titles (date, place, duration, price).
36
+ - A footer line with a real-sounding address, hours and one contact, proportional to the site.
37
+ - Hover and focus change one property (color, underline offset, background), 150 to 250 ms, and respect `prefers-reduced-motion`.
38
+ - `text-wrap: balance` on display and section headings, `text-wrap: pretty` on paragraphs; `touch-action: manipulation` on buttons and links; a `theme-color` meta matching the canvas; the display face preloaded when it is self-hosted.
39
+
40
+ ## Copy
41
+
42
+ - Nouns from this business: the roast origin, the street, the neighborhood, the service radius, the dish, the lens, the venue, the plan limit. A headline that fits any business is tell 17.
43
+ - One primary action per view, labeled verb plus object: "Reserve a table", "Request a quote", "Search the catalog". Not "Get started".
44
+ - Reassurance next to the action only when it answers a hesitation: no account needed, free estimate, cancel any time, and only if true.
45
+ - Plausible, specific invented details on a demo (a named roaster, a named street) are fine; label demo behavior where a visitor could mistake it for a real save or a real payment, as Rep & Plate does with "Local demo" and "Estimated · editable".
46
+
47
+ ## States
48
+
49
+ - Empty, loading, error and success states are designed in the same grammar as the rest of the page, not browser defaults. The empty state says what to do next.
50
+ - Form errors appear next to the field, name the fix, and keep the entered values.
51
+ - Inputs, selects, textareas and buttons get `font: inherit`; a browser default (Arial on Windows) inside a page set in the chosen faces is the first thing a reviewer notices.
52
+ - Disabled is visibly disabled and explains why when it matters.
53
+
54
+ ## Navigation
55
+
56
+ - Header: wordmark, three to five links, one action. On a phone the action stays visible and the menu button opens a real menu that the keyboard can use.
57
+ - Skip link, visible focus ring in the accent or brand color, logical tab order, `Escape` closes what opened.
58
+
59
+ ## Phone recomposition
60
+
61
+ Each archetype in the [catalog](layout-archetypes.md) says how it recomposes. Beyond that: display text at 36 to 44 px, the action within the first screen, the hero image cropped for its new aspect, three-across grids becoming an index list or a two-across grid, and nothing that needs a hover.
@@ -0,0 +1,110 @@
1
+ # Decision sheet
2
+
3
+ Write this before any markup, as `design/decisions.md` in the project. Every field holds a value a reviewer could check against the rendered page, and the palette line carries the contrast ratios the script in [color](color.md) printed. Adjectives are not values. Two filled examples follow the template, then the set-divergence table for several sites.
4
+
5
+ ## Template
6
+
7
+ ```markdown
8
+ # Design decisions: <site>
9
+
10
+ Subject and audience: <who arrives, what they came to do, what they already know>
11
+ Premise (one sentence a visitor could verify in the first screen): <...>
12
+ Rejection condition: fail if <the opening could belong to any ... / the work is buried under a slogan / ...>
13
+
14
+ Opening archetype: <1 to 4 from layout-archetypes.md> because <...>
15
+ Content archetypes: <5 to 9> for <which sections>
16
+ Section plan: <section: its job, its surface (canvas / brand-dark / image), its density>
17
+
18
+ Display face: <name, weight> · Text face: <name> · Accent voice: <italic phrase / handwritten word / none>
19
+ Display size: <desktop px / phone px>, tracking <−0.0x em>, line height <x>
20
+
21
+ Palette (canvas, surface, ink, ink-muted, brand, accent, accent-ink, line): <8 hex values>
22
+ Contrast (from the script in color.md): <ink/canvas, muted/canvas, canvas/brand, accent-ink/canvas, accent display/canvas>
23
+ Derived from: <two materials and a place>
24
+ Radius: <0 / 4 / 8 / 999> · Surface system: <hairline / flat blocks / sharp panels> · Dark section: <which one>
25
+
26
+ Signature element: <the one thing a visitor would describe afterwards>
27
+ Imagery (see visual-material.md): <kinds: photograph / rendered object / illustration / surface / texture / map>, <subject, crop, treatment>, <source and license, stored in /assets>. "None" only for a tool-dense screen, with the reason.
28
+ Icons: <set, stroke, size>
29
+
30
+ Voice: <how it talks> · Headline candidates: 1. <...> 2. <...> 3. <...>
31
+ Primary action: <verb + object> → <what happens next, and what is demo>
32
+
33
+ Tells to watch: <numbers from generic-tells.md this subject tends to attract>
34
+ ```
35
+
36
+ ## Example: café
37
+
38
+ ```markdown
39
+ # Design decisions: Halvard Coffee, Ballard
40
+
41
+ Subject and audience: a neighborhood café that roasts on Thursdays; regulars checking hours and the week's filter, newcomers deciding whether to walk over.
42
+ Premise: the first screen shows the counter in morning light, this week's coffees and the hours, so you can decide to come in without reading a paragraph.
43
+ Rejection condition: fail if the opening could belong to any café in any city, or if the menu is three cards with cup icons.
44
+
45
+ Opening archetype: 1, split with bleed, because the one good photograph is the counter and it should run off the right edge.
46
+ Content archetypes: 9, index list, for the menu and the weekly filters; 7, stacked bands, for the roasting-day story on a dark band.
47
+ Section plan: opening (canvas, airy) → this week's filters as an index list (canvas, dense) → roasting Thursdays (brand-dark band, one statement and three facts) → menu by category (canvas, index list) → find us (image band with a map crop and the hours line).
48
+
49
+ Display face: Fraunces 500, optical size 96 · Text face: Work Sans · Accent voice: Fraunces italic on "roasted here"
50
+ Display size: 84 px / 40 px, tracking −0.03 em, line height 1.0
51
+
52
+ Palette: #f6efe4 #fff9ef #2a1f16 #6d5d50 #3b2419 #c9772b #995d25 #e4d6c3
53
+ Contrast: ink 14.1, muted 5.5, canvas on brand 12.7, accent-ink 4.7, accent display 2.99 (fails 3:1, so the accent word in the headline uses accent-ink)
54
+ Derived from: espresso and crema, the cream paper of the menu board, the counter at 7 a.m.
55
+ Radius: 4 · Surface system: hairline on tinted canvas · Dark section: roasting Thursdays
56
+
57
+ Signature element: the weekly filter list with origin, process and tasting notes, set like a wine list with index numerals.
58
+ Imagery: counter photograph (Openverse, CC BY, author noted in /assets/SOURCES.md) cropped to keep the grinder and the window light, warm treatment, bleeding off the right edge; the day's board rendered as a dark chalkboard panel; bean close-up behind the dark band at 8 percent texture; a drawn street map in the footer. Material kinds: photograph, rendered object, surface, map.
59
+ Icons: Lucide, 1.5 px stroke, 20 px, only for hours, map and phone.
60
+
61
+ Voice: short, specific, no exclamation marks · Headline candidates: 1. Roasted here on Thursdays. 2. Two shots, textured milk, no hurry. 3. The 6:30 pour for the 7:15 ferry.
62
+ Primary action: "See this week's coffees" → scrolls to the index list; "Order ahead" is labeled demo and shows the pickup form with a saved-locally notice.
63
+
64
+ Tells to watch: 2, 16 (cup icons), 17 ("crafted with care").
65
+ ```
66
+
67
+ ## Example: home-repair service
68
+
69
+ ```markdown
70
+ # Design decisions: Keel & Timber Home Repair
71
+
72
+ Subject and audience: homeowners with something broken today; they want to know if the job is covered, what it costs and how fast someone comes.
73
+ Premise: the first screen asks for the problem and the zip code and promises a window, with the plan limits visible directly beneath.
74
+ Rejection condition: fail if the opening is a slogan over a stock handshake, or if the services are three equal cards with a wrench, a pipe and a plug.
75
+
76
+ Opening archetype: 4, tool first, because the visitor came to request a repair, not to be welcomed.
77
+ Content archetypes: 9, index list, for services with their response windows and from-prices; a real table for plan comparison; 7, stacked bands, for one dark band with the service radius and the crew.
78
+ Section plan: brand band with the request card (dense) → services index (canvas) → plan table with actual limits (surface) → crew and radius (brand-dark band with a photograph of a technician at a real door) → request again, short.
79
+
80
+ Display face: Bricolage Grotesque 800 · Text face: Figtree · Accent voice: none; the numbers are the voice
81
+ Display size: 64 px / 38 px, tracking −0.02 em, line height 1.05
82
+
83
+ Palette: #f3f4f1 #ffffff #15202b #55606b #1f3a5f #e4572e #b94b2d #d6dad3
84
+ Contrast: ink 14.9, muted 5.8, canvas on brand 10.4, accent-ink 4.6, accent display 3.3
85
+ Derived from: workwear navy, safety orange, plaster dust, galvanized conduit.
86
+ Radius: 8 · Surface system: flat blocks and hairlines · Dark section: crew and radius
87
+
88
+ Signature element: the request card with the problem picker and the promised window ("today before 6 pm" / "tomorrow 8 to 12").
89
+ Imagery: one photograph of a technician at a door in a branded jacket, cropped to the handshake and the jacket mark; conduit and copper close-ups for the dark band.
90
+ Icons: Phosphor regular, 24 px, in the problem picker only.
91
+
92
+ Voice: plain, direct, numbers first · Headline candidates: 1. Broken today. Fixed today. 2. Tell us what failed; we tell you when. 3. Twelve miles, four crews, one window.
93
+ Primary action: "Request a window" → confirmation with the chosen window; labeled demo, nothing sent.
94
+
95
+ Tells to watch: 2 (service cards), 5 (invented 10k+ repairs), 11 (blue accent is close to navy; keep orange as the only accent).
96
+ ```
97
+
98
+ ## Set divergence (several sites)
99
+
100
+ Fill this before building the first site. No two rows share a column value.
101
+
102
+ | Site | Opening archetype | Display face | Palette temperature | Hero mechanism | Signature element |
103
+ | --- | --- | --- | --- | --- | --- |
104
+ | Café | 1 split with bleed | Fraunces | warm cream | counter photograph bleeding right | weekly filter index list |
105
+ | Photography portfolio | 5 editorial grid as the opening | Playfair Display | dark | one lead image at 8 columns, no headline above it | project sequence with captions |
106
+ | Searchable catalog | 4 tool first | Space Grotesk | cool paper | search input on a signal-color band | results as an index list with tabular numbers |
107
+ | Event registration | 3 typographic poster | Syne | night with one hot accent | 120 px date and venue, no image | the schedule as a sticky-panel scroll |
108
+ | Home-repair service | 4 tool first (different band color and card content from the catalog) | Bricolage Grotesque | neutral with orange | problem picker and zip code | plan table with actual limits |
109
+
110
+ Two sites sharing archetype 4 is allowed only when band color, card content and the next section differ; mark it in the table, as above. If the table cannot be filled without repetition, the set does not yet have five identities.
@@ -0,0 +1,58 @@
1
+ # Review appearance and usefulness separately
2
+
3
+ Use the project's existing browser or preview tooling. Adapt checks to the changed surface; a copy correction does not require an application-wide audit. Record the route, viewport, exercised state, observation and resulting repair in the existing task evidence. This is a self-review unless someone else actually reviewed it.
4
+
5
+ ## Visual pass
6
+
7
+ Score the view first with the [generic-tells score sheet](generic-tells.md#score-sheet) at desktop and phone width and record the numbers. Three or more tells is a fail whatever the rest of this pass finds, and the repair is a changed decision in `design/decisions.md`, not a color swap. Then read the sheet's rejection condition and judge the render against it.
8
+
9
+ Read the visual criterion before judging the screenshot. If it only names colors, an illustration and readable layout, it cannot establish the intended design quality. Refer back to the decision sheet's premise and rejection condition to make its intended effect and rejection condition explicit. Preserve the user's ambition and criterion count; do not rewrite a failed criterion to match the result.
10
+
11
+ Inspect a representative desktop and phone view. Also inspect the narrowest supported width for a new layout or a suspected breakpoint defect; include a middle width when the transition itself is in question. Choose dimensions from the project; 1440, 390 and 320 CSS pixels are possible samples, not a universal support contract.
12
+
13
+ Start at the full composition, then inspect normal reading size. Check the first viewport, middle, close and next destination. Ask whether the headline, actual proof and main action form a clear priority. Check density, section continuity, image crop, text wrapping, crowded labels, broken assets and loading shifts. A full-page screenshot is useful for rhythm, but does not prove legibility or interaction.
14
+
15
+ For each important finding, write an observation that points to a repair: "At phone width the primary action follows three repeated summaries; group those below the action" is usable. "Needs more polish" is not. Repair the highest-impact issue before decorative details, then re-inspect the changed view. Do not call visual taste an objective score.
16
+
17
+ Trace the visual brief into implemented decisions: the actual asset and crop, dominant composition, type roles, useful interaction and the transition into the next content. Explain why a consequential choice helps this product. Sketch counts, repeated generic study panels and statements such as "clear hierarchy" are not evidence of resolved design. Inspect the ordinary reading-size view as well as the full page: a good overview can hide weak typography, placeholder imagery or unfinished controls. No finding quota is required; report a real miss when present, and do not invent a repair to certify the review.
18
+
19
+ Evaluate the product-specific visual acceptance criterion and its rejection condition explicitly. "Screenshots opened; no clipping" establishes an inspection and a layout observation, not an art-direction pass. A theme description is also insufficient: identify what the visitor can see, why it achieves or misses the intended effect, and any repair. Ask whether a generic starter could pass on the same evidence. A photographer's work buried beneath a slogan or a search tool buried beneath a marketing hero can fail the intended emphasis while remaining readable and functional. Judge against the actual brief, not a universal rule that every site needs an image or search above the fold. A material miss remains unmet even when behavior checks pass.
20
+
21
+ For several unrelated identities, add a comparison across the set: view openings at the same viewport and compare the full scroll. Judge the complete expression, then set names, colors and illustration subjects aside to expose shallow reuse. Inspect hierarchy, imagery and its integration, density, navigation, voice and where the useful interaction begins. A shared split or centered layout is not itself a defect; identify whether execution makes the products meaningfully distinct. A screenshot row is evidence to judge, not a passing result. Repair convergence when variety was requested; preserve shared-brand consistency. Never derive an originality score from pixel or DOM differences.
22
+
23
+ Apply the relevant [UX foundations](ux-foundations.md) to the chosen visual mechanisms. Keep visual observations separate from tested behavior; a screenshot of a control does not show whether it works or is accessible.
24
+
25
+ ## Primary-task pass
26
+
27
+ Follow the promised action to its outcome. A modal opening is not a completed booking, a submit click is not a saved record, and a toast alone is not persistence evidence. Where the feature promises saving, check the displayed result and reload or revisit it. Check cancellation and an applicable failure/recovery path using permitted test fixtures, not consequential live submissions.
28
+
29
+ Use honest first-use state, representative populated state, and an edge state that could break this layout. Depending on the feature, that might mean a long name, missing photo, large value, many rows, narrow locale, delayed response or validation error. Exercise only states relevant to the feature. Avoid filling production screens with invented success, progress, testimonials or personal records to make them look complete.
30
+
31
+ In a prototype, local state and example data can be the intended outcome. Label that boundary where users might mistake it for a real save or external action. Prefer a working local demonstration or honest unavailable control to a fake success alert. Report the precise missing integration.
32
+
33
+ ## Access and comfort pass
34
+
35
+ Run an automated check in the rendered page first (axe-core through Playwright or the browser extension, or Lighthouse) at desktop and phone width, and record every reported contrast ratio and target size in the evidence. The decision sheet's script checks the palette; this step checks what the page actually rendered, including text on photographs, the dark band and button labels. Then:
36
+
37
+ - Follow the primary path with a keyboard. Check focus visibility, logical order, activation, modal containment where needed, Escape/close and focus return.
38
+ - Inspect labels and semantic roles for controls, alternatives for meaningful images and text equivalents for visual data. Icon-only actions need accessible names. Check reading order when layouts reorder content.
39
+ - Check contrast and legibility on actual surfaces, zoom/reflow, and targets that are practical to tap. Use project or applicable accessibility requirements; visual taste does not excuse inaccessible controls.
40
+ - Check fixed navigation, banners and overlays for obscured actions or content. Phone keyboards and safe areas matter when they affect the requested input flow.
41
+ - Check reduced motion and any automatic tour's pause/manual controls. Read status and errors without relying on animation or color alone.
42
+
43
+ Run established build, lint, type and behavior checks appropriate to the change. Add focused behavioral coverage for new risky interactions where it adds value; do not make screenshot or CSS-string assertions merely to certify taste. Automated access checks can supplement this pass, not establish that the whole experience is accessible.
44
+
45
+ ## Completion evidence
46
+
47
+ Report these as separate claims:
48
+
49
+ | Claim | Supporting evidence | What it does not establish |
50
+ | --- | --- | --- |
51
+ | Runs | Actual build/start result and route | Visual quality or a completed user journey |
52
+ | Looks coherent | Current rendered views, specific inspection and repaired findings | Universal taste or conversion improvement |
53
+ | Meets the requested visual direction | Explicit judgment of the visual criterion, with composition evidence; for distinct identities, comparison across the set | That functional checks prove design quality or that novelty alone makes a design good |
54
+ | Main task works | Observed action → outcome and relevant recovery/persistence check | Every integration or device works |
55
+ | Access checks performed | Named keyboard, contrast, reflow and semantic observations | A formal accessibility certification |
56
+ | Direction accepted | The user's actual feedback on that direction | Acceptance of later unrelated revisions |
57
+
58
+ The handoff should let another person open and use the work: give the entry route or file, run instructions when needed, working scope, current visual evidence and material limits. When rendering is unavailable, continue useful implementation or review within scope, but label visual verification unperformed. Do not replace missing evidence with "responsive by design" or "production-ready."
@@ -0,0 +1,76 @@
1
+ # Generic tells
2
+
3
+ This is the page a model writes when nobody tells it otherwise. Learn it so you can recognize it in your own output. Score a rendered page by counting the tells present. Three or more: the page is generic, and the repair is a different decision, not a different color. One or two: fix them before extending the treatment.
4
+
5
+ ## The default page
6
+
7
+ Layout
8
+
9
+ 1. Centered hero: headline, one-sentence subhead, two buttons (filled and outline), everything centered, nothing else in the first viewport.
10
+ 2. Three equal cards in a row, each with an icon in a tinted circle, a bold title and two lines of text. Repeated as "features", "services" and "why us".
11
+ 3. Every section built the same way: the same max-width container, the same vertical padding, a centered heading and centered subhead, then a grid.
12
+ 4. White and light gray (`#f9fafb`, `#f3f4f6`) alternating as the only rhythm.
13
+ 5. A testimonials row of three quote cards with avatar circles, and a stats row of four numbers nobody measured (10k+, 99%, 24/7, 4.9 stars).
14
+ 6. A footer with four link columns and a copyright line, however small the site.
15
+
16
+ Type
17
+
18
+ 7. Inter, Roboto, Poppins, Montserrat, Open Sans or `system-ui` for everything, including the display size.
19
+ 8. Display text at 36 to 48 px with default letter-spacing and line-height 1.2, so the headline reads as large body text.
20
+ 9. Every heading at the same weight (700) and the same color. No eyebrow label, no italic or secondary voice anywhere.
21
+ 10. Centered text everywhere, including paragraphs.
22
+
23
+ Color and surface
24
+
25
+ 11. A blue, indigo, teal or violet accent (`#2563eb`, `#6366f1`, `#14b8a6`, `#8b5cf6`), or a two-stop gradient of two of them, on buttons, icons and a highlighted headline word.
26
+ 12. Pure white canvas (`#ffffff`), gray text (`#6b7280`) and gray borders (`#e5e7eb`).
27
+ 13. Border-radius 12 to 16 px and a soft drop shadow on every box; cards inside cards.
28
+ 14. A gradient blob, glass panel or mesh background behind the hero.
29
+
30
+ Imagery and copy
31
+
32
+ 15. Emoji as icons, or several icon sets at different stroke widths.
33
+ 16. A category illustration (a cup, a camera, a house outline) stretched to hero size, or a stock-style photo unrelated to the copy.
34
+ 17. Headlines that could head any business: "Welcome to [Name]", "Quality you can trust", "Your journey starts here", "Crafted with care", "Elevate your experience".
35
+ 18. Placeholder specifics: "123 Main Street", "John Doe", "$99/month", "Since 1995", "Lorem ipsum".
36
+ 19. A pill badge above the headline reading "✨ Now live" or "New".
37
+ 20. The phone layout is the desktop layout stacked: hero text still centered, the three cards now three tall cards.
38
+
39
+ The opposite failure, which the first twenty tells do not catch
40
+
41
+ 21. Wall of text: no photograph, rendered object, illustration or color surface at least a quarter of the viewport wide in the first two viewports; sections are type and hairlines on one flat canvas. Good typography does not rescue this; the page reads as a document.
42
+ 22. Flat page: every section sits on the same canvas with the same content column; no full-bleed band, no panel, no change of surface for item-like content.
43
+
44
+ ## Escaping each tell
45
+
46
+ Each row is a different decision, not a style.
47
+
48
+ | Tell | Replace with |
49
+ | --- | --- |
50
+ | 1 Centered hero | An archetype from the [catalog](layout-archetypes.md): a split whose image bleeds to the viewport edge, a full-bleed scene with type set into its quiet area, a typographic poster, a tool-first opening |
51
+ | 2, 3 Equal cards, identical sections | Structure that follows the content: a numbered process as a vertical index list with large numerals; a menu as a two-column price list with hairline rules; work as an editorial grid with one hero item; a comparison as a real table |
52
+ | 4 Gray and white alternation | Rhythm by density and surface: one dark or deeply colored section, one full-bleed image band, one quiet text-only section at a narrow measure |
53
+ | 5 Invented stats and quotes | Specific proof: a real menu with prices, a named project with its brief, a plan table with actual limits. Or nothing |
54
+ | 6 Four-column footer | A footer proportional to the site: one line with the address, hours and a contact, or a short two-column band |
55
+ | 7 to 9 One sans, one weight | A named pairing from [typography](typography.md): display face plus text face plus an eyebrow style; display at 56 to 96 px on desktop with negative tracking; one italic or handwritten accent phrase |
56
+ | 11, 12 Blue accent, white and gray | A palette derived from the subject ([color](color.md)): tinted canvas, deep brand color, one warm or cool accent, ink that is not pure black |
57
+ | 13 Rounded and shadowed | One surface system: hairline borders on a tinted canvas, or flat color blocks, or sharp corners. Shadows only on things that float |
58
+ | 15, 16 Emoji, category clip art | One icon set at one stroke width; photography chosen for a specific subject and cropped for the layout; or no imagery and strong type |
59
+ | 17, 18 Generic copy | Copy made of this business's nouns: the roast, the street, the neighborhood, the service radius, the dish, the camera body, the venue |
60
+ | 19 Pill badge | An eyebrow label that says something ("Open 6:30 to 15:00 · Roasting Thursdays") |
61
+ | 20 Stacked phone | Recompose per archetype: the image gets its own crop, the action comes before the explanation, lists become a compact rhythm |
62
+ | 21 Wall of text | Material from [visual material](visual-material.md): a sourced photograph stored locally, the product rendered as an object (a board, a ticket, a screen), an illustration with depth, texture on the brand surface |
63
+ | 22 Flat page | One full-bleed image or color band, a tinted panel behind item-like content, a dark section with the demonstration in it |
64
+
65
+ ## Score sheet
66
+
67
+ Record this in the run evidence for the signature section and for the finished page, at desktop and phone width:
68
+
69
+ ```text
70
+ View: desktop 1440 | phone 390
71
+ Tells present: [numbers] Count: N Verdict: pass (<3) | fail (>=3)
72
+ Material: [kinds present, largest non-text element as % of viewport width in viewports 1 and 2]
73
+ Changed decisions: ...
74
+ ```
75
+
76
+ Counting is deliberate. It stops "it feels fine" from passing a page a reviewer recognizes as default at a glance. Tell 21 alone fails the page: a document with a good headline is still a document. The count is a self-review, not a measurement of quality; a page can score zero and still be weak, which the [experience review](experience-review.md) exists to catch.