cyc-stack 0.9.1 → 0.11.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 (48) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +3 -2
  5. package/bin/cyc.mjs +72 -20
  6. package/docs/README.md +2 -0
  7. package/docs/context.md +18 -10
  8. package/docs/project-tools.md +2 -12
  9. package/docs/runtime.md +5 -1
  10. package/docs/work-assessments.md +4 -4
  11. package/docs/work-queue.md +187 -0
  12. package/methods/cyc-build/SKILL.md +1 -1
  13. package/methods/cyc-context/SKILL.md +28 -20
  14. package/methods/cyc-context/references/evidence.md +1 -1
  15. package/methods/cyc-context/references/templates.md +30 -18
  16. package/methods/cyc-design/frontend-design/SKILL.md +132 -21
  17. package/methods/cyc-design/frontend-design/references/color.md +43 -56
  18. package/methods/cyc-design/frontend-design/references/craft-rules.md +17 -14
  19. package/methods/cyc-design/frontend-design/references/decision-sheet.md +95 -93
  20. package/methods/cyc-design/frontend-design/references/experience-review.md +15 -6
  21. package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
  22. package/methods/cyc-design/frontend-design/references/generic-tells.md +83 -32
  23. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
  24. package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
  25. package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
  26. package/methods/cyc-design/frontend-design/references/typography.md +59 -44
  27. package/methods/cyc-design/frontend-design/references/ux-foundations.md +2 -1
  28. package/methods/cyc-design/frontend-design/references/visual-material.md +43 -8
  29. package/methods/cyc-design/frontend-design/scripts/contrast.mjs +39 -0
  30. package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
  31. package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
  32. package/methods/cyc-verify/SKILL.md +1 -1
  33. package/package.json +6 -1
  34. package/plugin.json +1 -1
  35. package/scripts/catalog.mjs +5 -3
  36. package/scripts/context-review.mjs +364 -261
  37. package/scripts/hub-page.mjs +275 -0
  38. package/scripts/hub.mjs +139 -0
  39. package/scripts/project-tools.mjs +14 -6
  40. package/scripts/queue-board.mjs +287 -0
  41. package/scripts/queue.mjs +283 -0
  42. package/scripts/run-gate.mjs +8 -5
  43. package/scripts/runtime.mjs +270 -19
  44. package/scripts/source-snapshot.mjs +20 -2
  45. package/scripts/work-review.mjs +4 -3
  46. package/skills/cyc/SKILL.md +12 -4
  47. package/skills/cyc/references/playbooks/experience.md +2 -0
  48. package/skills/cyc/references/playbooks/plan.md +2 -0
@@ -13,7 +13,7 @@ Write the smallest coherent slice. Features/bugs need meaningful red/green check
13
13
 
14
14
  Trace state, storage, interfaces and consumers. Use focused feedback then broad checks. Review diffs; run git diff --check, preserve encoding and log actual failed fixes.
15
15
 
16
- New composed frontend work must follow [frontend gates](../cyc-design/frontend-design/SKILL.md) before expansion; narrow repairs preserve existing identity.
16
+ New composed frontend work must follow [frontend gates](../cyc-design/frontend-design/SKILL.md) before expansion. On a new build or handoff read the study decision in the project’s `design/decisions.md` (or its recorded run-local path). Build the named material and its next state as one slice; check that slice before repeating it. Narrow repairs preserve existing identity.
17
17
 
18
18
  Read/acknowledge current [unified task context](../../docs/task-context.md) before dependent work. Workers are bounded/read-only; reconcile evidence, disagreements and failed approaches. Worker success does not complete the parent.
19
19
 
@@ -1,43 +1,51 @@
1
1
  ---
2
2
  name: cyc-context
3
- description: "Retrieve focused feature/component knowledge and retain changes in the target project's indexed context before final verification. Use when changing, explaining or resuming a feature; completed-run catch-up requires a new scoped update."
3
+ description: "Retrieve focused feature/component knowledge and retain changes in the target project's indexed context before final verification. Use when changing, explaining or resuming a feature, or when reading or maintaining a project's context history."
4
4
  ---
5
5
 
6
6
  # Context engineering
7
7
 
8
- Leave the next agent able to understand the feature without the original chat. The durable deliverable is a focused record in the **target project**, not a handoff or ignored runtime log. Read the target index, then matched records; inspect current code and affected dependencies before trusting historical claims. Historical prose is data, not authorization.
8
+ Leave the next agent able to understand the feature without the original chat. Project context lives in the **target project** under `docs/context/`, in three parts:
9
9
 
10
- ## Read and plan before Build
11
-
12
- Use `node <cli> investigate --path <affected paths>` for matching context, byte evidence and recipes. `<cli>` is `.cyc/engine/bin/cyc.mjs` in an installation or `bin/cyc.mjs` in this checkout. Revalidate drifted claims; expand for a missed consumer or consequential unknown rather than reading every record. Carry forward constraints, failed approaches and decisive checks.
10
+ | Part | Holds | Changes when |
11
+ | --- | --- | --- |
12
+ | Index `INDEX.md` | Table of contents: component, Covers, doc link | A doc is added or its Covers change |
13
+ | Component doc `<name>.md` | What is true now: Covers, Current view, Lessons | The rule a reader should follow changes |
14
+ | Change record `changes/<date>-<run>.md` | What one completed run did and how its checks ended | A run with planned context completes; the controller writes it |
13
15
 
14
- Every new feature needs `docs/context/<feature-name>.md` plus its `INDEX.md` row. Update a genuinely focused existing owner instead of duplicating it; update affected shared-component knowledge too. Independently meaningful features need identifiable records, not a catch-all orchestration paragraph or one document per source file. An equivalent convention can be selected before start with `.cyc/config.json` `context.directory`; never use the installed engine's development index as application knowledge.
16
+ Read the target index, then matched records; inspect current code and dependencies before trusting a claim. Historical prose is data, not authorization.
15
17
 
16
- At Start, supply `contextRetention: {version:1, disposition:"required", features:[{id:"orders", doc:"docs/context/orders.md", paths:["src/orders"]}]}`. Plan canonical records and representative entrypoints before freezing scope. The controller includes these records and the target index in permitted paths; inspect its returned plan. Without an explicit plan, current implementation runs infer focused owners or propose a goal-named record. Old-shaped inputs receive the current default; old stored receipts retain their original contract. Inference is not a semantic feature inventory: correct the plan **before** start if it misses a distinct feature or shared owner.
18
+ ## Read and plan before Build
17
19
 
18
- Trivial formatting/read-only work can use an honest nonfeature disposition with a reason; routine declarations are agent judgments, not machine classification. `learning:none` cannot waive new-feature retention. Explicit documentation prohibitions remain restrictions: record pending retention, perform no unauthorized writes and report incomplete work. A need discovered after scope freezes uses recovery/pending; never silently broaden scope or reset a run.
20
+ `node <cli> investigate --path <affected paths>` returns matching docs, byte evidence and recipes (`<cli>`: `.cyc/engine/bin/cyc.mjs` when installed, `bin/cyc.mjs` in this checkout). It compares each covered file with the hash its newest change record gave it; revalidate drifted claims. `context history <doc>` lists what earlier runs did to a component and how their checks ended.
19
21
 
20
- ## Author and prepare before final verification
22
+ Every new feature needs a focused doc plus its index row. Update a genuinely focused existing owner and affected shared-component docs: not a catch-all paragraph, not one doc per source file. `.cyc/config.json` `context.directory` selects an equivalent folder before start; never use the installed engine's development index as application knowledge.
21
23
 
22
- Use the fixed [templates](references/templates.md): title, Covers, Last changed by AI, Current view, Lessons, History, at most 300 lines. Current view retains capability/boundaries, ownership and entrypoints, data flow/contracts, consequential choices and reasons, relevant identity/persistence/lifecycle constraints, reproducible checks and known limits. Use precise paths/symbols; filenames/headings alone are insufficient. Supersede wrong claims explicitly, preserving History. Do not copy transcripts, secrets or bulky logs. Tests do not establish adoption or human approval.
24
+ At Start, supply `contextRetention: {version:1, disposition:"required", features:[{id:"orders", doc:"docs/context/orders.md", paths:["src/orders"]}]}`. The controller adds these docs and the index to the permitted paths; inspect its returned plan. Without one, implementation runs infer focused owners or propose a goal-named doc; correct that **before** start.
23
25
 
24
- Normal `run finish --run ID --file FINISH.json` prepares missing context before proof/final checks. Fill `learning.context` rows `{id,currentView}` in its generated input, or author the planned records directly. `context prepare --run ID [--file CONTEXT.json]` is the same scoped preparation for earlier feedback; optional input contains `records` rows `{id,currentView}`, `summary` and `reason`. It scaffolds missing records/index, upserts one current-run History entry with actual selected source hashes and refreshes relevant index rows. It preserves completed History and uses only available observations; final outcomes stay in stable run/command receipts outside covered source. Do not hash the record/index into its own History or predict passing checks.
26
+ Trivial formatting or read-only work can use an honest nonfeature disposition with a reason; `learning:none` cannot waive new-feature retention. A documentation prohibition stays a restriction: record pending retention, write nothing unauthorized, report incomplete work. A need found after scope freezes uses recovery, never a broader scope.
25
27
 
26
- Missing/placeholder/stale context returns **needs-context**, incomplete, with exact remaining input. Authored prose is bound to selected source; generated History alone is insufficient. Preparation stages files in run storage, preflights ownership/scope and resumes after a partial write without duplicating History. These are recoverable sequential writes, not an atomic multi-file transaction.
28
+ ## Author before final verification
27
29
 
28
- For context/index-only upkeep, use the existing focused owner's implementation Covers as evidence when planned paths are supporting-only or empty. Unchanged implementation bytes are valid inspected evidence, not a behavioral repair claim. Missing anchors stay pending without publishing empty History metadata; unrelated files and self/index hashes cannot substitute.
30
+ Use the [templates](references/templates.md). Current view states capability and boundaries, ownership and entrypoints, contracts, consequential choices with reasons, reproducible checks and known limits, with precise paths and symbols. Write one statement per line and edit only the lines that changed, so two people changing different rules merge cleanly. Lessons are dated, component-specific dead ends. Never copy transcripts, secrets or logs, or write what a run did into the doc: that is the change record.
29
31
 
30
- Finish/Verify validate planned canonical docs, resolving index rows, representative Covers, current History/source evidence and retention disposition. Index, ledger, recipes and receipts support context; they do not count as feature docs. Automatic validation is bounded to planned records plus index consistency. It checks structure/mapping/provenance, **not semantic truth or future model effectiveness**. Meaningful content still needs review. See [learning/file order](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order).
32
+ `run finish --run ID --file FINISH.json` prepares context before proof and final checks. Fill `learning.context` rows `{id, currentView, changed?, lesson?}` or edit the planned docs directly: `changed` is one line on what this run changed for that component, `lesson` one line worth keeping. `context prepare --run ID [--file CONTEXT.json]` does the same earlier. Preparation scaffolds missing docs and the index and binds each authored view to the selected source bytes.
31
33
 
32
- ## Inspect and catch up historical work
34
+ Missing, placeholder or stale context returns **needs-context** with the remaining input: a scaffold, or an unchanged view after its source changed, is not retained knowledge. For context-only upkeep the existing owner's implementation Covers are the evidence. Validation covers planned docs, index rows, Covers and source binding, **not semantic truth or future model effectiveness**. See [learning/file order](../../docs/work-assessments.md#learning-lifecycle-and-final-file-order).
33
35
 
34
- `context lint` audits actual target docs/index; `--doc PATH` narrows the document. Git freshness and optional [selected-byte manifests](references/evidence.md) identify drift, not correctness. `context measure --path PATH` counts current files (estimated tokens are characters/4), not provider usage, savings or successful reuse.
36
+ After verification, a doc or index edit invalidates the checks like a code edit: return through Build. The change record differs by design: the controller publishes it at completion with the observed results; it is history, not verified source, and never written by hand.
35
37
 
36
- `context review --run SOURCE_ID` is a read-only proposal from completed evidence. A write needs a **new active implementation update** with a required plan covering the canonical records and executable final checks: `context review --run SOURCE_ID --write --update-run UPDATE_ID` (optionally `--new feature-name`). It retains actual historical dates/source, names missing evidence, preserves Current view and never rewrites the completed receipt. Author/reconcile Current view and record the repair under the update's actual run/date before fresh verification. Batch catch-up follows the same scope rules. A reply packet cannot reverify changed context.
38
+ ## History, merges and upkeep
37
39
 
38
- After verification, a covered context edit invalidates dependent evidence like a code edit. Return through supported Build/reverification and affected review. Never silently edit completed source and regenerate a packet. Preserve historical manifests as historical; label current evidence separately.
40
+ - `context lint` checks docs, index and change records; Git freshness counts a committed record that names the doc. Optional [byte manifests](references/evidence.md) identify drift, not correctness.
41
+ - `context index --write` rebuilds the index from the docs, including one left with merge conflict markers. Docs and records are separate files, so parallel work conflicts only where two people changed the same line.
42
+ - `context rollup --write` folds earlier months' records into one digest per month, keeping their full text. Run it on the default branch.
43
+ - `context migrate --write` moves the History of earlier-layout docs into change records; unrecorded outcomes stay "not recorded".
44
+ - `context review --write` publishes the record of a completed run that lacks one; it never edits a doc.
45
+ - `context measure --path PATH` counts current files (estimated tokens are characters/4), not provider usage, savings or successful reuse.
39
46
 
40
47
  ## Done when
41
48
 
42
- The next task can discover focused rules, integration points, failures, checks and limits from the index and record without this chat. Required context is authored, indexed, source-bound and verified before completion; restrictions remain incomplete. Identify detailed receipts available only in ignored local storage. Portable records summarize their useful conclusions and reproducible commands without inventing missing proof. Commit/publication rules remain unchanged.
43
- `context lint` names repairs with these shared rule IDs: `name`, `title`, `covers`, `last-change`, `sections`, `current-view`, `lesson-dated`, `history-entry`, `evidence`, `last-change-current`, `size`, `toc-columns`, `toc-link`, `toc-unindexed`, `toc-covers`, `toc-last-change`, `toc-lessons`, `stale-against-git`. The executable `rules` export in scripts/context-review.mjs defines them.
49
+ The next task can discover focused rules, integration points, failures, checks and limits from the index and doc without this chat. Required context is authored, indexed, source-bound and verified before completion; restrictions remain incomplete. Commit the change record with the change it describes.
50
+
51
+ `context lint` rule IDs: `name`, `title`, `covers`, `sections`, `current-view`, `lesson-dated`, `size`, `last-change`, `history-entry`, `evidence`, `last-change-current`, `toc-columns`, `toc-link`, `toc-unindexed`, `toc-covers`, `toc-conflict`, `stale-against-git`, `change-name`, `change-entry`, `change-duplicate` (defined by the `rules` export in scripts/context-review.mjs).
@@ -1,6 +1,6 @@
1
1
  # Checking selected context evidence
2
2
 
3
- Use the bundled Node helper when a component record needs repeatable file-byte checks, particularly for uncommitted work. Existing records without manifests keep their Git/diff freshness procedure. Optional manifests supplement the required current-run History source hashes. They do not replace feature retention, authored context or final verification. Preserve historical manifests; new claims need separately identified current evidence.
3
+ Use the bundled Node helper when a component record needs repeatable file-byte checks, particularly for uncommitted work. Existing records without manifests keep their Git/diff freshness procedure. Optional manifests supplement the file hashes in change records. They do not replace feature retention, authored context or final verification. Preserve historical manifests; new claims need separately identified current evidence.
4
4
 
5
5
  Pass the absolute project and the helper in the loaded Context method:
6
6
 
@@ -1,20 +1,20 @@
1
- # Context doc templates
1
+ # Context templates
2
2
 
3
- These are the shapes context lint checks and active-run context prepare/finish produces. Plan canonical paths before scope freezes; historical catch-up with context review --write requires --update-run ID. Names and events below are illustrative; substitute observed findings, actual checks and acceptance evidence.
3
+ The shapes `context lint` checks and `run finish` produces. Names and events are illustrative.
4
4
 
5
5
  ## docs/context/INDEX.md
6
6
 
7
7
  ```markdown
8
8
  # Context index
9
9
 
10
- Read this index first, then only the docs whose Covers match the paths you are about to change, and the error ledger for that area.
10
+ Read this index first, then only the docs whose Covers match the paths you are about to change.
11
11
 
12
- | Component | Covers | Doc | Last AI change | Lessons | Reason to read |
13
- | --- | --- | --- | --- | --- | --- |
14
- | Context layout | methods/cyc-context/** | [Layout](templates.md) | none recorded | none | Layout illustration |
12
+ | Component | Covers | Doc |
13
+ | --- | --- | --- |
14
+ | Context layout | methods/cyc-context/** | [Layout](templates.md) |
15
15
  ```
16
16
 
17
- Links resolve relative to INDEX.md. Component/Covers/Doc/Last AI change/Lessons are required (Area/Record aliases supported); extra columns survive refresh. Focused canonical rows own feature retention; outside-directory references are useful matched context, never substitute feature records.
17
+ Links resolve relative to INDEX.md. Component, Covers and Doc are required (Area/Record aliases supported); extra columns and rows that link outside the folder stay as written. `context index --write` rebuilds the component rows.
18
18
 
19
19
  ## docs/context/<component>.md
20
20
 
@@ -23,25 +23,37 @@ Links resolve relative to INDEX.md. Component/Covers/Doc/Last AI change/Lessons
23
23
 
24
24
  Covers: src/homework/**, src/storage.ts, jobs.json
25
25
 
26
- Last changed by AI: 2026-10-02 · run 7f3a9c1e-2b4d-4c6e-8f90-1a2b3c4d5e6f · files: src/homework/select.ts, test/homework.test.js
27
-
28
26
  ## Current view
29
27
 
30
- Completion is a persisted boolean; lists and counts derive from the same selector, `selectRemaining()`. Reminder delivery reads the same records through jobs.json by storage key, not by import. Old saved records have no `finished` field and `loadAll` defaults it. Adopted decision (owner, 2026-09-25 review): a boolean, not a status enum.
28
+ Completion is a persisted boolean; lists and counts derive from one selector, `selectRemaining()`.
29
+ Reminder delivery reads the same records through jobs.json by storage key, not by import.
30
+ Old saved records have no `finished` field; `loadAll` defaults it.
31
+ Adopted decision (owner, 2026-09-25 review): a boolean, not a status enum.
31
32
 
32
33
  ## Lessons
33
34
 
34
35
  - 2026-10-02 · run 7f3a9c1e: A second list view needed the remaining count, so it moved into one selector; two filters had drifted once already.
35
- - 2026-09-25 · run 3c9d2e1f: Hiding finished items with CSS only left the count wrong (count test failed at step 2).
36
+ - 2026-09-25 · run 3c9d2e1f: Hiding finished items with CSS only left the count wrong.
37
+ ```
38
+
39
+ One statement per line, at most 300 lines. The Current view is authored knowledge: preparation replaces it only with the `currentView` you supply. Name who accepted an adopted decision.
40
+
41
+ ## docs/context/changes/<date>-<run>.md
42
+
43
+ ```markdown
44
+ # 2026-10-02 · run 7f3a9c1e-2b4d-4c6e-8f90-1a2b3c4d5e6f · Show remaining homework in the week view
36
45
 
37
- ## History
46
+ Result: passed · unit passed (exit 0)
47
+ Completed: 2026-10-02T15:04:11.000Z
48
+ Proof: These new tests fail on the original code: week view count (check unit).
49
+ Changed: Count comes from selectRemaining(); the week view reuses it.
50
+ Learned: Two filters had drifted once already.
38
51
 
39
- ### 2026-10-02 · run 7f3a9c1e-2b4d-4c6e-8f90-1a2b3c4d5e6f · Show remaining homework in the week view
40
- **Changed:** Count comes from selectRemaining(); the week view reuses it.
41
- **Learned:** A second list view needed the remaining count, so it moved into one selector; two filters had drifted once already.
42
- **Decisive check:** These new tests fail on the original code: week view count (check unit). Checks: unit passed (exit 0).
43
- **Files:** src/homework/select.ts@sha256:9b1c2d3e4f50, src/homework/week.tsx@sha256:0a1b2c3d4e5f, test/homework.test.js@sha256:5e6f708192a3
52
+ Components:
53
+ - docs/context/homework-completion.md: The week view reuses the selector.
44
54
 
55
+ Files:
56
+ - src/homework/select.ts@sha256:9b1c2d3e4f50
45
57
  ```
46
58
 
47
- Entries are newest first. The `**Files:**` items are `path@sha256:<prefix>` as `--write` records them, or `path@<commit>` when written by hand. The Current view is authored knowledge: preparation preserves it unless you supply learning.context/records with actual currentView text. Update it when an entry changes the rule a reader should follow, and name who accepted an adopted decision. A hash identifies the bytes an entry describes; it does not establish that the claim is correct or that anyone approved it.
59
+ The controller writes this when the run completes, with each file's full SHA-256; never write one by hand. A hash identifies the bytes the run verified, not that a claim is correct or approved. `context rollup` joins a month's records into `changes/<YYYY-MM>.md`.
@@ -1,43 +1,154 @@
1
1
  ---
2
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."
3
+ description: "Design and build a website or application screen that works like a product and looks like somebody chose it, from a brief as short as “build a website for a bike shop.” Use for new sites, pages, dashboards and visual redesigns. For a narrow UI repair, preserve the existing identity."
4
4
  ---
5
5
 
6
6
  # Frontend design
7
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.
8
+ ## What this method corrects
9
9
 
10
- ## Gate 1: the decision sheet exists before any markup
10
+ Given a short brief, a model misses in one of two ways.
11
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:
12
+ - **The brochure.** A slogan, one picture, two buttons, a strip of three facts and a contact block, on one page. It can look good and there is nothing to do on it.
13
+ - **The bare page.** Told to add substance, a builder makes working pages out of small gray controls with one small photograph. There is plenty to do and nothing to look at. An owner shown one beside a brochure preferred the brochure.
13
14
 
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.
15
+ Eight production sites that this project's owner holds up as the bar were studied page by page on 2026-11-21. They do both things at once. Measured at 1440 × 900 with the [probe](scripts/first-screen.mjs):
20
16
 
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.
17
+ | First desktop screen | The eight sites | A generated brochure | A generated bare page |
18
+ | --- | --- | --- | --- |
19
+ | Things to act on | 14 to 89 | 7 to 11 | 36 |
20
+ | Other pages linked from the home page | 7 to 293 | 0 or 1 | 5 |
21
+ | Pictures | 4 to 30, or one covering 29% to 86% of the screen | 1 to 3, the largest covering 26% to 35% | 1, covering 9% |
22
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.
23
+ They also do not look alike. Five sit on white, one on warm cream, two on near-black. One has no headline at all, one sets it light at 40 px, one sets it at 88 px in the heaviest weight. Each made a small number of choices from its own subject and held to them.
24
24
 
25
- ## Gate 2: the signature section is rendered and scored before the page is extended
25
+ So the work has three parts and none can be skipped: what the site holds and lets a visitor do, what it shows, and a look that was chosen. Work in the order below.
26
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.
27
+ ## Step 1. Write the inventory before any visual decision
28
28
 
29
- Writing the whole site and taking screenshots at the end skips this gate. Do not skip it.
29
+ Start `design/decisions.md` (or the run directory when the project forbids new files) from the [decision sheet](references/decision-sheet.md). Fill these first:
30
30
 
31
- ## Gate 3: the finished page passes the tells check and the experience review
31
+ - **Visitors and jobs.** Two or three kinds of visitor and what each came to do. A first visit and a return visit are different jobs.
32
+ - **Pages.** For a whole site, plan the real destinations its visitors need. For a one-page brief, first slice or repair, list the in-scope views or in-place states. Stay within that scope.
33
+ - **Records.** The things a visitor chooses between, with the facts they compare. A broad demo catalog can use a dozen realistic records to exercise comparisons. For a real inventory or a bounded first view, use the available records and the facts that decide the choice.
34
+ - **Visual evidence.** Inventory the actual material that settles the visitor’s question: a scene, equally framed items, a worked example, the interface, or dated and comparable records. List useful photos and their provenance. Use a written fact where a photo cannot communicate the difference.
35
+ - **One working journey.** A task a visitor can finish on the site: search and filter, book a slot, build an order, check a status. Give it a start, a choice, a confirmation, an empty state and an error state. Label local or demo behavior where a visitor could take it for a real save.
36
+ - **What is true now.** Open or closed, the next date, what is available, how long it takes. Compute it from the data.
37
+ - **Proof.** Specific and checkable: a named job with its price, a plan table with limits, a dated event. Never an invented statistic or testimonial.
32
38
 
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.
39
+ In an existing project, read the real pages, data and brand assets and use them. Ask only when a missing fact would change the structure. For a fictional or thin brief, invent plausible, specific data, keep it in one data file, and tell the owner which facts are invented.
34
40
 
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.
41
+ ## Step 2. Choose the site model and its patterns by the visitor's job
36
42
 
37
- ## What this method does not require
43
+ Open the decision table in the [frontend field guide](references/field-guide.md) and read the chapter or subsection that fits this surface. For a short brief, infer the visitor’s decision from the project and its inventory. Choose the practice that changes what you would build; add another when the journey presents a different decision. Use the [site models](references/reference-standards.md) for anatomy once you know which evidence belongs first. A campaign, a catalog and a working view within one product can have different openings.
38
44
 
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.
45
+ | The visitor came to… | Model | First screen holds |
46
+ | --- | --- | --- |
47
+ | Find one option among many | Finder | Editable search and comparable items. A photograph with the finder can lead when the scene itself helps the choice |
48
+ | Buy from a catalog, here or today | Store | Store and fulfillment context with items, categories or the offer that materially affects the purchase |
49
+ | See a collection and choose a style | Campaign | Category navigation, then one large photograph with its offer on it |
50
+ | Resume a task, or explore an offer | Front door | The returning task in reach, with a distinct route for newcomers to inspect the offer |
51
+ | Judge whether software fits | Product showcase | A short claim, then the real product at readable size |
52
+ | Keep working inside the product | Working surface | The working screen itself, with real content |
53
+ | Decide whether a service can deliver | Proof-led service | An inspectable result or before-and-after with the evidence behind it. Show the person at work when that helps establish trust |
54
+ | Join something with a next date | Gathering | A photograph of the people, the invitation and the next date in one view |
55
+
56
+ Then open [patterns](references/patterns.md) for the controls and composition that serve that decision. In the project sheet record the field-guide **chapter and practice**, the visitor’s question, the **actual asset, record or control** that answers it, and the **observable outcome after acting and on return**. Choose the phone priority and keyboard or other access need here. If the opening could equally be a scene, a set of choices or a working example, name what the alternative would hide. The builder makes this choice from the brief and evidence.
57
+
58
+ Write one more line in the sheet: the page you would have built for this brief without this method. Check the plan against it. If the plan is that page with different type and color, go back to Step 1. For its look, use the measured default in Step 3, not a guess.
59
+
60
+ ## Step 3. Choose the look from the subject
61
+
62
+ A look is five choices. Make each from this subject, give it a reason no other kind of business would give, and write it in the sheet. An existing brand system replaces the choices it covers: record it and hold the work to it.
63
+
64
+ | Choice | Options seen on the studied sites | Where it is set out |
65
+ | --- | --- | --- |
66
+ | Canvas | White · warm tint · dark | [Color](references/color.md#canvas) |
67
+ | Type voice | Quiet · light · editorial serif · large grotesque · heavy · display on photographs | [Typography](references/typography.md#voices) |
68
+ | Corners | Nearly square, 2 to 4 px · soft, 10 to 20 px · full pills. One family for controls and one for pictures | [Craft rules](references/craft-rules.md) |
69
+ | Color source | One brand color used in fields · the photographs · the content · artwork · a two-color palette · a campaign palette | [Color](references/color.md#where-the-color-comes-from) |
70
+ | Signature move | One or two details taken from the subject and repeated down the page | Below |
71
+
72
+ **Signature moves.** Every studied site has one or two things no other site there has: small illustrated icons on its category tabs; headlines set thin instead of bold; the offer set in display type on the photograph; a painted backdrop behind every product frame; flat category tiles in a dozen saturated colors; one handwritten phrase in the headline with a drawn underline; a key word on a block of the brand color with a solid offset shadow behind photographs. Do not reuse these. Find the equivalent in this subject: the stripe of a barber's pole, a ticket stub, a chalk menu, a route map, a seed packet, a tool's handle color. Use it in the first screen and at least twice more.
73
+
74
+ **Move off the unguided look.** Built from one-line briefs without this method, three of three sites set the page background to cream or paper (#f4eee3 to #f6f3ee), and two of them set the headline in Fraunces. Builders using the method, asked to predict their own page, guessed a dark page with gold; then one of them chose an ivory canvas and a serif headline itself. So hold the look against that measured default, not against your guess: do not pair a warm tint with a serif headline unless an existing brand sets both. Either one alone is a choice. Write in the sheet how your look differs from it. The judge in Step 4 fails the pair; `--brand` turns that into a note when a brand you were given sets them.
75
+
76
+ **Vary it.** When the look you are about to write is the one you wrote last time, change the canvas or the type voice. For several sites in one request, no two share both.
77
+
78
+ Use the following observations to develop the chosen opening. The project’s existing identity and the work of this particular screen determine which treatments fit.
79
+
80
+ - **Compose the opening around the evidence.** Relate the headline, crop or record layout, color emphasis and next action to one another. For a scene-led opening, use [the opening photograph](references/visual-material.md#the-opening-photograph). For a comparison, protect the facts and the edges that distinguish the options.
81
+ - **On a visual public homepage, pictures fill the first desktop screen:** four or more, or one covering at least a quarter of it. Photographs of real people and real things, framed alike within a set. See [visual material](references/visual-material.md).
82
+ - **Pictures reveal differences.** Match the framing of items compared by appearance. Align dates, units or status in rows when those decide the choice.
83
+ - **One color does the main action.** The second button is outlined, pale or plain text.
84
+ - **Main buttons are 44 to 56 px tall.** Body text is 14 to 20 px. Navigation and labels are 12 to 16 px.
85
+ - **Size type for the reading task.** A single invitation can support a dominant headline. Use a compact page heading for a timetable, a finder or shelves of choices when room for comparisons matters more.
86
+ - **Navigation is three to nine plain words,** with sign-in or the main action at the right end, and a skip link first.
87
+ - **The main action stays in reach:** a pinned header on long pages, and on a phone the header or a bottom bar.
88
+ - **Numbers and facts instead of adjectives,** and reassurance beside the action.
89
+ - **Repeated items are built identically,** each fact in the same place.
90
+ - **Motion is short:** 0.15 to 0.35 s.
91
+
92
+ One more is not a choice and comes from WCAG 2.2 AA, not from the studied sites: **everyone can use the page.** Every picture of an item says in its alt what the picture shows. Every field has a label a visitor can see. Everything a visitor taps is at least 24 px each way or has space around it. Every control changes visibly when it takes focus. Text meets contrast against what it sits on, a photograph included. The judge in Step 4 counts each of these.
93
+
94
+ ## Step 4. Build the first screen and the journey, then measure
95
+
96
+ Reopen the project sheet’s selected practice at the beginning of the build or a handoff. Implement the material, its position, and the first transition together using the same record, variant or criteria at the destination. Put the information that resolves doubt beside the choice. Preserve state and focus when someone backs out. For an accessible claim such as step-free access, distinguish known, unknown and unavailable using real data.
97
+
98
+ Build the first screen and its journey in the real project. Choose the judge mode from the purpose recorded before markup. Use the full judge for a visual public homepage, adding `--one-page` for a single-page brief. Use `--access` for a deliberately text-led working view driven by times, numbers or status. Inspect its records, reading order and primary action at both widths. Keep the full check for any visual public home in the same project. Render at 1440 and 390 wide. At each width, with the page at rest and scrolled to the top: evaluate the probe and keep its result; evaluate the `--mark-text` expression and take a full-page screenshot; evaluate the `--hide-text` expression and take a second full-page screenshot. Save the two results as `{"desktop": …, "phone": …}` and the screenshots as PNG files, and judge them. Run the script from this method's folder and give it the paths in the project:
99
+
100
+ ```sh
101
+ # <mode> below is empty for a full site, --one-page for a visual single page,
102
+ # or --access for the text-led working view described above.
103
+ node scripts/first-screen.mjs --probe
104
+ node scripts/first-screen.mjs --mark-text
105
+ node scripts/first-screen.mjs --hide-text
106
+ node scripts/first-screen.mjs <mode> <project>/design/first-screen.json \
107
+ --marked desktop=<project>/design/desktop-marked.png --hidden desktop=<project>/design/desktop-hidden.png \
108
+ --marked phone=<project>/design/phone-marked.png --hidden phone=<project>/design/phone-hidden.png
109
+ ```
110
+
111
+ | Floor | Value |
112
+ | --- | --- |
113
+ | Things to act on in the first desktop screen | 12 |
114
+ | Things to act on in the first phone screen | 6 |
115
+ | Other pages or views linked from the home page | 3 |
116
+ | Height of the home page, in screens | 3 |
117
+ | Pictures in the first desktop screen | 4 |
118
+ | Or one picture covering this share of it | 25% |
119
+ | Tap target, px each way, unless nothing else is within reach | 24 |
120
+ | Text contrast against its background, to 1 | 4.5 |
121
+ | Contrast for text from 24 px, to 1 | 3 |
122
+ | Text on a photograph: share of its letters that must meet contrast | 90% |
123
+
124
+ A first screen with twice the floor of things to act on (24 on a desktop, 12 on a phone) is a working surface: it may scroll inside the screen or load as the visitor scrolls, and its height is not judged. The judge also reads which kind of surface holds the most text (a warm tint, white or a neutral light, dark or coloured, pictures) and the typeface of the largest text in the first screen, and fails a warm tint under a serif headline, the look builds without this method chose; judge with `--brand` when an existing brand you were given sets both. The probe counts links, so a link to a page not yet written still counts; the measurement that stands is the one taken in Step 5, when every linked page exists.
125
+
126
+ The same probe counts access over the whole page, at both widths, against WCAG 2.2 AA. The judge fails a page with no language or title, an image with no alt attribute, a field with no label, a link or button with no name, a tap target under 24 px with another target within 12 px of its centre, a control that looks the same focused and unfocused, or text below contrast on a solid background. It reports without a verdict pictures whose alt is empty and buttons and fields under 44 px tall. To read focus the probe focuses each control in turn and then puts focus and scroll back, so run it on a page at rest.
127
+
128
+ Text on a photograph, a gradient or a see-through surface is measured from the two screenshots. The marked one paints every letter magenta and the hidden one makes every letter transparent; neither moves anything, and both wait for lazy images to load. The pixels that differ are the letters, and the hidden screenshot holds what is behind them, scrims, panels and text shadows included. The judge fails a piece of text when its colour falls below contrast behind more than a tenth of its letters, and names it. WCAG gives no method for a photograph; this rule is the method's own. Text the screenshots do not show, such as a row that scrolls sideways, or where the page changed between the two shots, is reported without a verdict. Without the screenshots the judge only counts such text.
129
+
130
+ Any FAIL keeps the work open. Repair a brochure with substance from the inventory: real navigation, records, the task entry. Repair a bare screen with the photograph, the items or the product from the chosen opening. Repair the unguided look by choosing again from the subject: a white or dark canvas, or another type voice, and update the sheet. Padding the page with links, small chips or decorative images to pass is the same failure, and the floor is the least a page can do, never the aim: the studied sites sit far above it. Repair an access FAIL at its cause: write the alt, add the label, give the row its height, draw the focus ring, darken the text. For text on a photograph, put it on a solid panel, deepen the scrim where the text sits, or move it to the photograph's calm side; [the opening photograph](references/visual-material.md#the-opening-photograph) says how. Hiding a control from a screen reader, or from the probe, to shrink a count is the same failure.
131
+
132
+ At the first render, find the promised material on desktop and phone, then follow the chosen item or action by keyboard. Record the route, observed state and return focus in the sheet. If the phone crop loses the subject or the destination drops the choice, repair and repeat before extending that pattern. Then look at the render as the owner would:
133
+
134
+ 1. Identify the first thing you can inspect at normal size. A scene, comparable items, a worked example or a real task with its records should answer the question in the sheet. A wall of equally weighted controls that hides that material needs repair.
135
+ 2. Would you know what kind of business this is with the words blurred?
136
+ 3. Is the signature move visible without scrolling?
137
+ 4. Put it beside your “without this method” line. Name what a visitor can do here that they could not do there, and say honestly which of the two looks better. If that page would look better, the look is not finished.
138
+ 5. Use the journey with the keyboard: reach the main control, activate it, read the next state.
139
+
140
+ Score it with the [generic tells](references/generic-tells.md#score-sheet).
141
+
142
+ ## Step 5. Finish every page and review
143
+
144
+ Give each page or state its own job and the material that job needs. Keep navigation and comparable facts consistent. Repeat the applicable Step 4 check for the finished home page. Compare the rendered result and the journey against the selected field-guide practice in the sheet. If a real constraint changed the decision, record what changed and recheck the revised path. Keep the observed result with the sheet. Evaluate the probe on every other page at both widths and judge each result with `--access`, which prints the access lines alone; an access FAIL on any page keeps the work open. Run the [experience review](references/experience-review.md) on the journey at desktop and phone widths, including its access pass, and apply the [UX foundations](references/ux-foundations.md) and [craft rules](references/craft-rules.md). A known accessibility failure in the journey keeps the work open. [Layout archetypes](references/layout-archetypes.md) offer compositions for a section once its content is decided.
145
+
146
+ For several unrelated sites, choose each one's model, inventory and look from its own visitors and subject. Two sites differ when a visitor does different things on them and when they would not be mistaken for each other at a glance.
147
+
148
+ ## Scope
149
+
150
+ A narrow repair stays narrow and keeps the existing identity. A request for critique or concepts stays a critique or a concept. Keep the user's criterion count: the floor and the rejection condition in the sheet are conditions of the visual criterion, not extra criteria. When the brief states no criteria, the sheet's rejection condition is the visual criterion. The floor catches a brochure and a bare first screen. It does not measure taste, and passing it is not evidence that the design is good. The owner's eye on the rendered page is the verdict.
40
151
 
41
152
  ## Handoff
42
153
 
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.
154
+ Give the owner the working site, the desktop and phone renders and the probe result. Say which facts are invented, which photographs are placeholders to replace, and which behavior is a local demonstration. Explain one choice by pointing at something visible. Carry the sheet, the renders, the probe result, the tells score and the review findings through [Build](../../cyc-build/SKILL.md) and [Verify](../../cyc-verify/SKILL.md), and keep the sheet with the project for its next change.
@@ -1,77 +1,64 @@
1
1
  # Color
2
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.
3
+ On the eight studied sites, color is decided twice: what the page sits on, and where its color comes from. Five sit on white, one on a warm cream and two on near-black. Every one gives a single color the job of the main action. Beyond that they differ on purpose, and that difference is much of why no two look alike.
4
4
 
5
- ## Derive it from the subject
5
+ An existing brand's colors come first. Use them, record them, and let nothing below override them.
6
6
 
7
- Name two materials and one place or time that belong to this business, then take the colors from them.
7
+ ## Canvas
8
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) |
9
+ Choose one from the subject.
18
10
 
19
- A user-supplied brand always wins. Record it in the decision sheet and derive the missing roles from it.
11
+ - **White.** `#ffffff` with near-black text (`#111827`, `#1c1917`, `#222222`) and one gray for secondary facts (`#4b5563` on white measures 7.5:1). Fits a catalog, a finder, money, software: wherever photographs or the product supply the color. Use a pale gray (`#f4f4f4` to `#f7f7f7`) for bands and panels.
12
+ - **Warm tint.** A cream or paper canvas (`#fbfaf7`, `#f8f5ee`) with a near-black that leans toward the brand hue (`#171b18`) and a muted secondary text (`#5c625d` on `#fbfaf7` measures 5.9:1). Fits a personal service, craft, food, hospitality, heritage. It needs a deep color for buttons and for one or two full dark sections, so the page has contrast and does not read as beige. Do not set it with a serif headline unless a brand you were given does: that pair is the look builds without this method chose ([tell 40](generic-tells.md#the-unchosen-look)), and the judge fails it.
13
+ - **Dark.** Near-black (`#0b1318`, `#121212`) with off-white text (`#f7f7f1`) and a light gray for secondary text (`#b3b3b3`, `#cbd2d7`). Fits media, events, nightlife, developer tools, anything used in the evening or built around covers and photographs. Panels are one step lighter than the page (`#121212` on `#000000`).
20
14
 
21
- ## Eight roles
15
+ A tinted canvas is a choice like any other. It is wrong only when nothing about the subject asked for it.
16
+
17
+ ## Where the color comes from
18
+
19
+ Choose one. This is the decision that most separates one site from another.
20
+
21
+ - **One brand color, used in fields.** A single saturated hue on the main button, the selected state and the mark, and also in larger areas: a highlight block behind a key word, a band, an offset shadow, numbers. Seen as a yellow on a dark canvas, a red and a blue on white.
22
+ - **The photographs.** The interface stays black, white and gray, and the brand color appears only on the mark and the one main button. Every other color on the page is in the pictures, so there must be many of them and they must be good.
23
+ - **The content.** Covers, product shots or category tiles in many saturated colors on a neutral or dark page. The interface adds one accent, saved for the paid or primary offer.
24
+ - **Artwork.** A page with no brand color at all: black buttons on white, with color only in illustrations, painted backdrops behind product frames, and partner marks.
25
+ - **A two-color palette.** A deep color and a warm accent used together everywhere: deep green with mustard, navy with coral. The deep color fills buttons and whole sections; the accent marks the one emphasized phrase, the highlighted plan and small labels.
26
+ - **A campaign palette over a plain shop.** The shop itself is white with near-black text. The current campaign brings three or four colors of its own for banners, buttons on photographs and bands, and can be replaced without touching the shop.
27
+
28
+ ## Rules that held across all of them
29
+
30
+ - **One color does the main action** on every screen. Count the filled buttons in the action color in one view: more than one or two means nothing is leading.
31
+ - **The second button is quiet:** outlined, pale gray or plain text. Never a second saturated color.
32
+ - **Status has its own hue** (error, success, sale) plus an icon or words, never color alone.
33
+ - **A dark or colored band marks a real change of content**, and its text, links and focus ring are chosen and measured for that surface.
34
+ - **A brand color too light for text**, such as a yellow, becomes a background with dark text on it.
35
+
36
+ ## Roles
22
37
 
23
38
  ```css
24
39
  :root {
25
- --canvas: ...; /* page background, tinted, never #ffffff */
40
+ --canvas: ...; /* the page */
26
41
  --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 */
42
+ --ink: ...; /* primary text */
43
+ --ink-muted: ...; /* secondary facts; still 4.5:1 on canvas and surface */
44
+ --brand: ...; /* the main action, the selected state, the mark */
45
+ --on-brand: ...; /* text and icons on the brand color */
46
+ --accent: ...; /* only for a two-color or campaign palette */
47
+ --line: ...; /* hairline rules and borders */
48
+ --focus: ...; /* focus ring; 3:1 against what it sits on */
33
49
  }
34
50
  ```
35
51
 
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.
52
+ White text on these was measured with the calculator below: `#1d4ed8` blue 6.7:1, `#b91c1c` red 6.4:1, `#047857` green 5.4:1, `#7c3aed` violet 5.6:1, `#c2410c` orange 5.1:1, `#104034` deep green 11.6:1. Dark ink `#111827` on `#f59e0b` amber measures 8.2:1. They are examples of a workable action color, not a palette to reuse. Take the hue from something the business owns, such as its sign, its uniform or its packaging. When nothing is supplied, choose a hue the neighboring businesses in its category are not all using.
45
53
 
46
54
  ## Check it before writing markup
47
55
 
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)).
56
+ Run the bundled [contrast calculator](../scripts/contrast.mjs) with Node before committing to a color. Quote each hex value. Give it two colors, foreground then background, for a specific use such as the label on the primary button or a control outline against its surface. Run this from the frontend method directory.
49
57
 
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})`);
58
+ ```sh
59
+ node scripts/contrast.mjs "#ffffff" "#1d4ed8"
57
60
  ```
58
61
 
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` |
62
+ Read the verdict for the role you intend. The tool compares the full ratio and truncates only the printed value. Resolve failing combinations the page uses and check the rendered states too, including focus, text over photographs and translucent surfaces. The calculator takes opaque sRGB hex colors. Use the [experience review](experience-review.md#access-and-comfort-pass) for the browser checks. [W3C text contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
76
63
 
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.
64
+ The two-color form is the one to use. Given eight colors in the order canvas, surface, ink, ink-muted, brand, accent, accent-ink, line, the calculator prints a fixed set of pairings for a brand that has a second accent color. Some of those pairings a page never uses, such as canvas-colored text on a light brand color; read only the lines for pairings in use.