cyc-stack 0.10.0 → 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 (36) 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/bin/cyc.mjs +55 -7
  5. package/docs/README.md +2 -0
  6. package/docs/runtime.md +4 -0
  7. package/docs/work-queue.md +187 -0
  8. package/methods/cyc-build/SKILL.md +1 -1
  9. package/methods/cyc-design/frontend-design/SKILL.md +125 -28
  10. package/methods/cyc-design/frontend-design/references/color.md +42 -50
  11. package/methods/cyc-design/frontend-design/references/craft-rules.md +13 -10
  12. package/methods/cyc-design/frontend-design/references/decision-sheet.md +94 -98
  13. package/methods/cyc-design/frontend-design/references/experience-review.md +10 -2
  14. package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
  15. package/methods/cyc-design/frontend-design/references/generic-tells.md +82 -33
  16. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
  17. package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
  18. package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
  19. package/methods/cyc-design/frontend-design/references/typography.md +59 -44
  20. package/methods/cyc-design/frontend-design/references/visual-material.md +40 -7
  21. package/methods/cyc-design/frontend-design/scripts/contrast.mjs +1 -1
  22. package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
  23. package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
  24. package/methods/cyc-verify/SKILL.md +1 -1
  25. package/package.json +6 -1
  26. package/plugin.json +1 -1
  27. package/scripts/hub-page.mjs +275 -0
  28. package/scripts/hub.mjs +139 -0
  29. package/scripts/queue-board.mjs +287 -0
  30. package/scripts/queue.mjs +283 -0
  31. package/scripts/run-gate.mjs +1 -1
  32. package/scripts/runtime.mjs +248 -13
  33. package/scripts/source-snapshot.mjs +1 -1
  34. package/scripts/work-review.mjs +1 -1
  35. package/skills/cyc/SKILL.md +8 -0
  36. package/skills/cyc/references/playbooks/plan.md +2 -0
@@ -1,57 +1,154 @@
1
1
  ---
2
2
  name: frontend-design
3
- description: "Design a distinctive, usable website or application screen from a brief as simple as “make my homepage look better.” Use for new pages, dashboards and visual redesigns. For a narrow UI repair, preserve the existing identity."
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
- Own the visual decisions. Someone with an existing project can point to the page and ask for a redesign. Inspect the current page, its destinations, brand assets, and representative content before asking for more input. For a new project, start with the brief and available material. A reference is optional. When supplied, use it to understand taste and verify its sample claims against the project. Ask a plain-language question only if an unresolved fact or preference would materially change the work and a reversible assumption is insufficient.
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
- Decide what the visitor should see, feel and be able to do. Ground that direction in something specific you can actually show. For example, a developer meetup can feel like walking up to a table where people are building together. That suggests a close photograph of shared work, a conversational headline and an event within reach. A dispatch tool might open on a late delivery, with the promised time easy to scan and reassignment at hand. Trace important existing offerings and actions into the new page, including what happens below the opening. Treat unconfirmed material as a proposal.
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
- Design the reading order, accessible name and keyboard path of the main action alongside its visual treatment. Identify where the signature idea could make the experience harder to use and how you will test it. Use the project's accessibility requirements and WCAG 2.2 AA as the working target when none is specified. Preserve stricter commitments. The [UX foundations](references/ux-foundations.md) give criteria and exceptions for common design choices.
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):
15
16
 
16
- 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:
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% |
17
22
 
18
- - [Generic tells](references/generic-tells.md): the default page, numbered, and what replaces each tell.
19
- - [Typography](references/typography.md): pairings with character notes, sizes, tracking and loading.
20
- - [Color](references/color.md): deriving a palette from the subject, token roles, example palettes.
21
- - [Layout archetypes](references/layout-archetypes.md): nine compositions with CSS skeletons. Archetype 0 is the banned default.
22
- - [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.
23
- - [Reference standards](references/reference-standards.md): what the sites held up as the bar actually do, with observed values.
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
- 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.
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
- 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.
27
+ ## Step 1. Write the inventory before any visual decision
28
28
 
29
- ## Gate 2: the signature section is rendered and scored before the page is extended
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
- Compose the section that carries the identity with the real headline or task, chosen material, primary action and transition to the next section. For implementation, build this slice in the real page and include the next action state. For a concept request, use the requested mockup format and identify any proposed behavior.
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
- Before the first handoff, compare rendered treatments of the most consequential visual decision. When direction is open, explore different ways to present the same real material. When the brand or direction is settled, compare a focused choice within it, such as the headline weight and crop. Two studies can be successive renders of the same slice. Keep alternatives internal unless the user requests options.
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
- Look at the pictures side by side. Where does the eye land first and next? What do the type size, weight and line breaks do to the actual words? Does the area of accent color lead toward the important content or compete with it? Which detail survives the phone crop? At DSD, a framed table photo made a friendly invitation. A closer view of people looking at a laptop gave “What are you building?” a subject. The yellow mark behind *building?* singled out the word the image answered. Use that reasoning with this project's material.
41
+ ## Step 2. Choose the site model and its patterns by the visitor's job
36
42
 
37
- Before adopting a treatment, exercise its main action on the working slice. Tab to it from the page, see where focus lands, activate it and inspect the next state. Check its accessible name, actual text and control contrast, and narrow-screen reading order. For static concepts, assess the visible risks and specify the intended interaction. Repair a barrier in the treatment and check it again before extending it. For example, move an unreadable photo caption to an opaque print label and keep the photograph at its intended scale.
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
- Choose among the usable treatments on visual merit. Record the difference that decided it in the decision sheet. Check the selected slice at desktop and phone width with the [generic-tells score sheet](references/generic-tells.md#score-sheet) and [craft rules](references/craft-rules.md). Three or more tells fail the check. A low count still needs a visible, project-specific reason to choose this design.
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 |
40
55
 
41
- ## Gate 3: the finished page passes the tells check and the experience review
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.
42
57
 
43
- For a static concept, judge the rendered composition and identify the actions proposed. Apply the following interaction and browser checks to a working implementation.
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.
44
59
 
45
- Read the full page as a sequence. Cover the hero and inspect the next section and the action it leads to. Can a visitor find concrete evidence for the opening promise? Give a collection, a story and a task the space each needs. Carry a recognizable type or alignment choice across the transition. Remove decoration or repeated copy that competes with the work. Check the result again at reading size and on a phone.
60
+ ## Step 3. Choose the look from the subject
46
61
 
47
- Score the full page, including the applicable [material checks](references/visual-material.md#the-density-rule), and test the decision sheet's rejection condition. Run the [experience review](references/experience-review.md) on the primary journey, including its access pass at desktop and phone widths. Record repairs, retests and remaining gaps. A known accessibility failure in the changed journey keeps it open for repair.
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.
48
63
 
49
- 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.
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 |
50
71
 
51
- ## What this method does not require
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.
52
73
 
53
- 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.
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.
54
151
 
55
152
  ## Handoff
56
153
 
57
- Give the owner the preview or working page and show the desktop and phone result. Explain one choice in everyday language by pointing to a visible detail. When a preference remains open, frame it in terms of what the visitor would experience. Carry the decision sheet, renders, tells scores and findings through [Build](../../cyc-build/SKILL.md) and [Verify](../../cyc-verify/SKILL.md). Keep the rationale with the project for its next change.
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,72 +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
- Keep the supplied brand identity. When a brand color is too faint for a label or focus indicator, give the color a different role or pair it with an accessible ink. Record the pairing.
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
- - Use a dark or brand-colored band when the content calls for a change of emphasis. Choose readable text, links and focus colors for that surface and measure each pairing.
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
- Run the bundled [contrast calculator](../scripts/contrast.mjs) with Node before committing to a palette. Quote each hex color. Give it eight colors in decision-sheet order to inspect possible pairings. Use two colors for a specific use, such as the lettering on an accent button or a required control outline against its adjacent surface. Run this example from the frontend method directory.
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
58
  ```sh
51
- node scripts/contrast.mjs "#995d25" "#f6efe4"
59
+ node scripts/contrast.mjs "#ffffff" "#1d4ed8"
52
60
  ```
53
61
 
54
- Read the verdict for the role you intend to use. The tool compares the full ratio and truncates only the printed value. A pale brand accent can work as a background with dark lettering even when it fails as small text. Resolve failing combinations used by the page and check the actual rendered states, including focus, captions over photographs, and translucent surfaces. The calculator takes opaque sRGB hex colors. Use the [experience review](experience-review.md#access-and-comfort-pass) for those browser checks. [W3C text contrast guidance](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
55
-
56
- ## Example palettes
57
-
58
- Starting points to adapt. Eight values in the order canvas, surface, ink, ink-muted, brand, accent, accent-ink, line. Check each accent against the surface where you use it. The café accent works as a mark on cream. For a word on cream, the darker accent ink works at body size.
59
-
60
- | Subject | Values |
61
- | --- | --- |
62
- | Café, espresso | `#f6efe4` `#fff9ef` `#2a1f16` `#6d5d50` `#3b2419` `#c9772b` `#995d25` `#e4d6c3` |
63
- | Photographer, dark | `#111111` `#1a1a1a` `#f2efe9` `#9a9690` `#f2efe9` `#d9c58b` `#d9c58b` `#2a2a2a` |
64
- | Photographer, light | `#f7f5f0` `#ffffff` `#161616` `#6a6660` `#161616` `#b8952e` `#846c26` `#e2ddd3` |
65
- | Catalog, paper and signal | `#f4f4f1` `#ffffff` `#121417` `#5b6066` `#121417` `#e8412c` `#c83a29` `#d9d9d4` |
66
- | Event, night | `#0f0e17` `#1b1930` `#fffffe` `#a7a9be` `#ff8906` `#e53170` `#e84880` `#2e2b4a` |
67
- | Home repair, workwear | `#f3f4f1` `#ffffff` `#15202b` `#55606b` `#1f3a5f` `#e4572e` `#b94b2d` `#d6dad3` |
68
- | Careers, green and gold | `#f8f5ee` `#fffaf0` `#171b18` `#5c625d` `#104034` `#e5a128` `#8e6921` `#e3ddd0` |
69
- | Daily tool, sage | `#f8faf7` `#ffffff` `#102333` `#5f6b66` `#17674e` `#c9a24a` `#817041` `#d5e1dd` |
70
- | 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)
71
63
 
72
- 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.
@@ -1,16 +1,18 @@
1
1
  # Craft rules
2
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.
3
+ Execution rules with numbers, applied once the first screen clears the [floor](../SKILL.md#step-4-build-the-first-screen-and-the-journey-then-measure) and before the system is carried to every page. They make the site consistent; they do not decide what it contains.
4
4
 
5
5
  ## Spacing and containers
6
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.
7
+ - One spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 px. Section padding follows the model: 32 to 64 px on a catalog, a booking page or a working surface, where the first screen has to hold real items; 96 to 128 px on a page that persuades. On a phone, 24 to 72 px by the same rule.
8
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
+ - Main buttons 44 to 56 px tall at every width, with 16 to 24 px of padding each side. One radius for controls and one for pictures, from the corners chosen in the decision sheet.
9
10
  - 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.
11
+ - Every other target, at every width, is at least 24 px each way, or has no other target within 12 px of its centre. A footer link gets a 24 px line or block padding. A title link takes the whole row or card, not the 16 px of its text. The [judge](../SKILL.md#step-4-build-the-first-screen-and-the-journey-then-measure) fails a smaller one.
10
12
 
11
13
  ## Surfaces
12
14
 
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.
15
+ - Group surfaces by purpose. A button and an event listing can share an edge treatment while the underlying photographic scene stays open. Keep repeated controls visually consistent.
14
16
  - 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
17
  - Make a surface change mark a real transition, such as moving from a finished project to its commission details. A change in scale, density or spacing can carry that transition on a single surface.
16
18
 
@@ -18,9 +20,10 @@ Execution rules with numbers, applied after the signature section passes the [te
18
20
 
19
21
  - Every image has a reason recorded in the decision sheet: which subject, why this crop, what it proves.
20
22
  - `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
+ - Art-direct each photograph for its role. A candid may fill the opening, a group portrait may sit beside community facts, and a speaker directory may use tightly aligned headshots. Keep related pictures consistent within each group.
24
+ - When the visitor needs to see the work, source it or render a representative example at readable scale. In a record-based tool, give that room to the working records and controls. [Visual material](visual-material.md)
23
25
  - Local-only sites store assets in the repository with their source and license noted.
26
+ - Alt text says what the picture shows that the words beside it do not: “Worn tuck box, seal broken, corners rounded”, not the deck's name a second time. Write it for every picture of an item, a person or a place. An empty alt is for decoration only: a texture, a divider, a second view of something already described. The opening photograph gets alt text when it shows the subject.
24
27
 
25
28
  ## Icons and marks
26
29
 
@@ -40,9 +43,9 @@ Execution rules with numbers, applied after the signature section passes the [te
40
43
  ## Copy
41
44
 
42
45
  - 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".
46
+ - Give the main task a clear verb and object, such as "Reserve a table". When returning and first-time visitors have genuinely separate tasks, each can have a distinct entry. Use grouping, placement and emphasis to make the right one easy to find.
44
47
  - 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".
48
+ - 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, with a small tag such as "Local demo" or "Estimated · editable".
46
49
 
47
50
  ## States
48
51
 
@@ -53,9 +56,9 @@ Execution rules with numbers, applied after the signature section passes the [te
53
56
 
54
57
  ## Navigation
55
58
 
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.
59
+ - Size the header to the real destinations. Give the main action clear priority and group related routes. On a phone, let labels wrap or move secondary destinations into a keyboard-operable menu while keeping the main action reachable.
60
+ - Skip link, a visible focus ring that reaches 3:1 against what it sits on (the brand color when it does, the ink when the brand color is too light), logical tab order, `Escape` closes what opened. The ring may be drawn on a wrapper or a label, as with a styled select or radio, but every control changes visibly when it takes focus; removing an outline without replacing it fails the judge.
58
61
 
59
62
  ## Phone recomposition
60
63
 
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.
64
+ Each archetype in the [catalog](layout-archetypes.md) says how it recomposes. Beyond that: display text at 32 to 52 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.