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
@@ -1,26 +1,29 @@
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
- - Exactly one dark section on a light site. Its text is the canvas color, not white.
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
 
17
19
  ## Imagery
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
 
@@ -29,20 +32,20 @@ Execution rules with numbers, applied after the signature section passes the [te
29
32
 
30
33
  ## Details that signal craft
31
34
 
32
- - Eyebrow labels (uppercase, tracked, 11 to 13 px) above display text and section headings, saying something specific.
33
- - Index numerals (01, 02) on lists and steps, set in the display face.
35
+ - Add a short label when it gives a heading needed context. Remove it if the heading already says the same thing.
36
+ - Use index numerals for a sequence the visitor actually follows. For an unordered collection, give that space to the work.
34
37
  - Hairline rules between rows instead of boxes around them.
35
38
  - Captions under images; meta lines under titles (date, place, duration, price).
36
- - A footer line with a real-sounding address, hours and one contact, proportional to the site.
39
+ - Close with a useful next action or verified contact details, proportional to the site.
37
40
  - Hover and focus change one property (color, underline offset, background), 150 to 250 ms, and respect `prefers-reduced-motion`.
38
41
  - `text-wrap: balance` on display and section headings, `text-wrap: pretty` on paragraphs; `touch-action: manipulation` on buttons and links; a `theme-color` meta matching the canvas; the display face preloaded when it is self-hosted.
39
42
 
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.
@@ -1,110 +1,112 @@
1
1
  # Decision sheet
2
2
 
3
- Write this before any markup, as `design/decisions.md` in the project. Every field holds a value a reviewer could check against the rendered page, and the palette line carries the contrast ratios the script in [color](color.md) printed. Adjectives are not values. Two filled examples follow the template, then the set-divergence table for several sites.
3
+ Keep this as `design/decisions.md` in the project. Fill the inventory and the model before any markup. Choose the look before styling. Add the measurements after the first render. Every field holds something a reviewer could check against the rendered site. “Warm and modern” is not a value.
4
+
5
+ On a handoff or resumed build, open the sheet at **Study decision**. It names the entry in the [frontend field guide](field-guide.md), the project material and the expected behavior. If an older sheet predates these fields, add the decision for the current composed change using the brief and existing assets. Reuse it through Build and Verify. A narrow repair can use the existing task evidence and stay within its original scope.
4
6
 
5
7
  ## Template
6
8
 
7
9
  ```markdown
8
- # Design decisions: <site>
9
-
10
- Subject and audience: <who arrives, what they came to do, what they already know>
11
- Premise (one sentence a visitor could verify in the first screen): <...>
12
- Rejection condition: fail if <the opening could belong to any ... / the work is buried under a slogan / ...>
13
-
14
- Opening archetype: <1 to 4 from layout-archetypes.md> because <...>
15
- Content archetypes: <5 to 9> for <which sections>
16
- Section plan: <section: its job, its surface (canvas / brand-dark / image), its density>
17
-
18
- Display face: <name, weight> · Text face: <name> · Accent voice: <italic phrase / handwritten word / none>
19
- Display size: <desktop px / phone px>, tracking <−0.0x em>, line height <x>
20
-
21
- Palette (canvas, surface, ink, ink-muted, brand, accent, accent-ink, line): <8 hex values>
22
- Contrast (from the script in color.md): <ink/canvas, muted/canvas, canvas/brand, accent-ink/canvas, accent display/canvas>
23
- Derived from: <two materials and a place>
24
- Radius: <0 / 4 / 8 / 999> · Surface system: <hairline / flat blocks / sharp panels> · Dark section: <which one>
25
-
26
- Signature element: <the one thing a visitor would describe afterwards>
27
- Imagery (see visual-material.md): <kinds: photograph / rendered object / illustration / surface / texture / map>, <subject, crop, treatment>, <source and license, stored in /assets>. "None" only for a tool-dense screen, with the reason.
28
- Icons: <set, stroke, size>
29
-
30
- Voice: <how it talks> · Headline candidates: 1. <...> 2. <...> 3. <...>
31
- Primary action: <verb + object> → <what happens next, and what is demo>
32
-
33
- Tells to watch: <numbers from generic-tells.md this subject tends to attract>
10
+ # Design decisions: <project>
11
+
12
+ ## Inventory
13
+ Visitors and jobs: <who arrives, first visit or return, what each came to do>
14
+ Pages: <the requested pages, views or in-place states; the job of each>
15
+ Records: <the kinds of thing a visitor chooses between, how many of each, and the facts shown on every one>
16
+ Visual evidence: <scene, comparable pictures, product example or legible records; source and rights for any media>
17
+ Working journey: <the task, its steps, what the visitor sees at the end; the empty state and the error state; what is local or demo>
18
+ True now: <what the site computes from data: open or closed, next date, availability, turnaround>
19
+ Proof: <specific and checkable; or none>
20
+ Data: <the file that holds the records; which facts are real, which are invented for this brief>
21
+
22
+ ## Model
23
+ Site model: <one or two from reference-standards.md> because <the visitor's job>
24
+ Patterns: <from patterns.md, by name: the opening; header; items; trust; phone>
25
+ Study decision: <field-guide chapter and practice> → <visitor question> → <specific asset, record or control and where it appears>
26
+ Through the click: <selection or criteria and next state; what survives returning or closing; keyboard or other access need>
27
+ First screen holds: <header rows; the task entry or the items; what is true now>
28
+ One item is built as: <name, deciding facts and action; picture when it helps someone choose>
29
+ Section order: <home page, top to bottom, each with its job>
30
+ Phone pattern: <what stays within reach; how the items recompose>
31
+ Without this method I would have built: <one line: the opening, the sections, the page count>
32
+ What a visitor can do here that they could not do there: <one line>
33
+
34
+ ## Look
35
+ Brand: <existing identity and assets, or "none supplied">
36
+ Canvas: <white, warm tint or dark; hex values for canvas, ink and muted text> because <a reason from this subject>
37
+ Type voice: <one voice from typography.md; the families and the job of each; headline size, weight and tracking, or "no headline"> because <reason>
38
+ Corners: <radius for controls; radius for pictures> because <reason>
39
+ Color source: <one from color.md; the action color's hex and its jobs; any second color and its jobs> because <reason>
40
+ Signature move: <one or two details taken from this subject; where each appears, at least three places>
41
+ Against the unguided look: <how this canvas and type voice differ from a cream canvas under a serif headline, or the brand that sets both>
42
+ Contrast: <measured pairs for the text, the action and the control cues in use>
43
+ Spacing: <the scale; section padding>
44
+
45
+ ## Measurements
46
+ First screen (desktop 1440, phone 390): <paste the judge's lines, or link design/first-screen.json>
47
+ Study check: <route, viewport and what you actually saw or operated; selected item/state after the click and on return; repair and recheck or observed limitation>
48
+ Tells present: <numbers from generic-tells.md> · Count: <N>
49
+ Rejection condition: fail if <what this visitor could still not find or do>
50
+ Access: <the judge's access lines for each page; the marked and hidden screenshots behind them for text on photographs; how the main control is named, reached and used by keyboard; what was checked by hand>
34
51
  ```
35
52
 
36
- ## Example: café
37
-
38
- ```markdown
39
- # Design decisions: Halvard Coffee, Ballard
40
-
41
- Subject and audience: a neighborhood café that roasts on Thursdays; regulars checking hours and the week's filter, newcomers deciding whether to walk over.
42
- Premise: the first screen shows the counter in morning light, this week's coffees and the hours, so you can decide to come in without reading a paragraph.
43
- Rejection condition: fail if the opening could belong to any café in any city, or if the menu is three cards with cup icons.
44
-
45
- Opening archetype: 1, split with bleed, because the one good photograph is the counter and it should run off the right edge.
46
- Content archetypes: 9, index list, for the menu and the weekly filters; 7, stacked bands, for the roasting-day story on a dark band.
47
- Section plan: opening (canvas, airy) → this week's filters as an index list (canvas, dense) → roasting Thursdays (brand-dark band, one statement and three facts) → menu by category (canvas, index list) → find us (image band with a map crop and the hours line).
53
+ ## Example of the level of detail: a neighborhood café
48
54
 
49
- Display face: Fraunces 500, optical size 96 · Text face: Work Sans · Accent voice: Fraunces italic on "roasted here"
50
- Display size: 84 px / 40 px, tracking −0.03 em, line height 1.0
51
-
52
- Palette: #f6efe4 #fff9ef #2a1f16 #6d5d50 #3b2419 #c9772b #995d25 #e4d6c3
53
- Contrast: ink 14.1, muted 5.5, canvas on brand 12.7, accent-ink 4.7, accent display 2.99 (fails 3:1, so the accent word in the headline uses accent-ink)
54
- Derived from: espresso and crema, the cream paper of the menu board, the counter at 7 a.m.
55
- Radius: 4 · Surface system: hairline on tinted canvas · Dark section: roasting Thursdays
56
-
57
- Signature element: the weekly filter list with origin, process and tasting notes, set like a wine list with index numerals.
58
- Imagery: counter photograph (Openverse, CC BY, author noted in /assets/SOURCES.md) cropped to keep the grinder and the window light, warm treatment, bleeding off the right edge; the day's board rendered as a dark chalkboard panel; bean close-up behind the dark band at 8 percent texture; a drawn street map in the footer. Material kinds: photograph, rendered object, surface, map.
59
- Icons: Lucide, 1.5 px stroke, 20 px, only for hours, map and phone.
60
-
61
- Voice: short, specific, no exclamation marks · Headline candidates: 1. Roasted here on Thursdays. 2. Two shots, textured milk, no hurry. 3. The 6:30 pour for the 7:15 ferry.
62
- Primary action: "See this week's coffees" → scrolls to the index list; "Order ahead" is labeled demo and shows the pickup form with a saved-locally notice.
63
-
64
- Tells to watch: 2, 16 (cup icons), 17 ("crafted with care").
65
- ```
66
-
67
- ## Example: home-repair service
55
+ This shows how specific each line should be. It is not a design to reuse; another café has different visitors and a different menu.
68
56
 
69
57
  ```markdown
70
- # Design decisions: Keel & Timber Home Repair
71
-
72
- Subject and audience: homeowners with something broken today; they want to know if the job is covered, what it costs and how fast someone comes.
73
- Premise: the first screen asks for the problem and the zip code and promises a window, with the plan limits visible directly beneath.
74
- Rejection condition: fail if the opening is a slogan over a stock handshake, or if the services are three equal cards with a wrench, a pipe and a plug.
75
-
76
- Opening archetype: 4, tool first, because the visitor came to request a repair, not to be welcomed.
77
- Content archetypes: 9, index list, for services with their response windows and from-prices; a real table for plan comparison; 7, stacked bands, for one dark band with the service radius and the crew.
78
- Section plan: brand band with the request card (dense) → services index (canvas) → plan table with actual limits (surface) → crew and radius (brand-dark band with a photograph of a technician at a real door) → request again, short.
79
-
80
- Display face: Bricolage Grotesque 800 · Text face: Figtree · Accent voice: none; the numbers are the voice
81
- Display size: 64 px / 38 px, tracking −0.02 em, line height 1.05
82
-
83
- Palette: #f3f4f1 #ffffff #15202b #55606b #1f3a5f #e4572e #b94b2d #d6dad3
84
- Contrast: ink 14.9, muted 5.8, canvas on brand 10.4, accent-ink 4.6, accent display 3.3
85
- Derived from: workwear navy, safety orange, plaster dust, galvanized conduit.
86
- Radius: 8 · Surface system: flat blocks and hairlines · Dark section: crew and radius
87
-
88
- Signature element: the request card with the problem picker and the promised window ("today before 6 pm" / "tomorrow 8 to 12").
89
- Imagery: one photograph of a technician at a door in a branded jacket, cropped to the handshake and the jacket mark; conduit and copper close-ups for the dark band.
90
- Icons: Phosphor regular, 24 px, in the problem picker only.
91
-
92
- Voice: plain, direct, numbers first · Headline candidates: 1. Broken today. Fixed today. 2. Tell us what failed; we tell you when. 3. Twelve miles, four crews, one window.
93
- Primary action: "Request a window" → confirmation with the chosen window; labeled demo, nothing sent.
58
+ # Design decisions: Halvard Coffee, Ballard
94
59
 
95
- Tells to watch: 2 (service cards), 5 (invented 10k+ repairs), 11 (blue accent is close to navy; keep orange as the only accent).
60
+ ## Inventory
61
+ Visitors and jobs: a regular checking today's hours and this week's filter coffees before walking over; a newcomer deciding whether to come; someone ordering ahead for pickup.
62
+ Pages: Home (what is on today and the way in to ordering); Menu (drinks and food by category, with prices); Beans (the week's roasts to buy, with origin and notes); Order ahead (build a pickup order); Visit (hours by day, map, parking, the roasting schedule).
63
+ Records: 14 drinks (name, size, price), 8 pastries (name, price, baked today or sold out), 5 beans (origin, process, notes, price per 250 g, roast date). 27 records, all shown with their facts.
64
+ Visual evidence: the counter in morning light, full width, as the opening; every pastry and every bag photographed straight on against the same pale wall, 13 in all, three of them in the first screen; stock photographs under a free license, listed in assets/SOURCES.md as placeholders.
65
+ Working journey: Order ahead. Pick items → choose a pickup time from the slots left today → review → confirmation with the order and the time. Empty state: "Nothing in your order yet" with the three most ordered drinks. Error: a slot that filled is named and the next two are offered. Demo: the order is kept on this device and nothing is charged, stated on the review step.
66
+ True now: open or closed with the closing time, from the hours table; the next pickup slot; which pastries are sold out; days since roast for each bean.
67
+ Proof: the roast date on every bag; the price on every item. No testimonials.
68
+ Data: data/menu.json and data/hours.json. Every item, price and hour is invented for this brief.
69
+
70
+ ## Model
71
+ Site model: Store, because most visitors come to see what they can get today. The order page takes its item from the Finder.
72
+ Patterns: Hero photograph with the task on it; Items under the hero; Context row; Header that stays; The picture is the card; Three facts under the picture; Practical line under the button; Bottom bar.
73
+ Study decision: Catalog and pickup / Make timing a way to narrow the catalog → Can I collect coffee before my train? → show the next available slot from the hours data beside Order ahead. The counter photograph shows the shop at work; keep the time legible on a solid panel on the phone.
74
+ Through the click: selecting 9:40 carries the time into review beside the drink; Back keeps the slot if still available. Closing the time chooser restores focus to the slot control.
75
+ First screen holds: a context row (Open until 3:00 pm · Ballard Ave · next pickup 9:40); a header with Menu, Beans, Order ahead, Visit; this week's three filter coffees as items with origin, notes and price; "Order ahead" as the one filled button.
76
+ One item is built as: a square photograph, the name, one gray line of facts (size and price, or origin and process), and an Add button on the order page.
77
+ Section order: today's filters → the pastry case with sold-out states → roasting Thursdays, with the date of the next roast → menu by category → hours by day and the map.
78
+ Phone pattern: a fixed bottom bar with Menu, Order and Visit; the context row stays at the top; items go two across.
79
+ Without this method I would have built: a cream page with a serif slogan beside one illustrated cup, a strip of three facts, six menu cards and a contact block, on one page.
80
+ What a visitor can do here that they could not do there: see what is on today with prices, and place a pickup order for a time that is still free.
81
+
82
+ ## Look
83
+ Brand: none supplied.
84
+ Canvas: white #ffffff with ink #1c1917 and muted text #57534e, because the pastries and the bags are the color and need a clean counter under them.
85
+ Type voice: quiet. One family, Figtree. "This week at the counter" at 56 px bold on the opening photograph of the counter at 7 am, with "Order ahead" and the next pickup slot on a white panel; interface 13 to 16 px, section titles 28 px semibold, because the coffees carry the page once the photograph has set the morning.
86
+ Corners: 12 px on pictures, full pills on buttons, because the cups, lids and stickers in the shop are all round.
87
+ Color source: the photographs. One roast brown #7c2d12 for the Order button, the selected slot and the wordmark.
88
+ Signature move: the roast date as a round ink stamp, tilted, on every bag photograph, on the order confirmation and beside "roasting Thursdays".
89
+ Against the unguided look: a white canvas, not cream, and one sans family with no serif headline.
90
+ Contrast: ink on canvas 17.4:1; white on the brand color 9.3:1; the gray facts line #57534e on white 7.6:1.
91
+ Spacing: 4 px scale; 64 px between sections.
92
+
93
+ ## Measurements
94
+ First screen: desktop pass 19 actions, pass 4 pages linked, pass 4.2 screens, pass 5 pictures, pass canvas #ffffff with the headline in Figtree; phone pass 9 actions.
95
+ Study check: /order, phone. Chose 9:40 by keyboard. Review showed the drink and 9:40; closing the chooser returned focus to the time button.
96
+ Tells present: none · Count: 0
97
+ Rejection condition: fail if a visitor cannot tell what is on today or cannot finish a pickup order on a phone.
98
+ Access: no access FAIL on any of the five pages; four menu photographs carry alt that names the cup and the pour. "Order ahead" is the second tab stop after the skip link; slots are radio buttons with the time as the label; the filled-slot error is tied to the group and read on change.
96
99
  ```
97
100
 
98
- ## Set divergence (several sites)
101
+ The numbers in the example's Measurements block illustrate the format. Record what the judge prints for the real page.
99
102
 
100
- Fill this before building the first site. No two rows share a column value.
103
+ ## Several sites in one request
101
104
 
102
- | Site | Opening archetype | Display face | Palette temperature | Hero mechanism | Signature element |
103
- | --- | --- | --- | --- | --- | --- |
104
- | Café | 1 split with bleed | Fraunces | warm cream | counter photograph bleeding right | weekly filter index list |
105
- | Photography portfolio | 5 editorial grid as the opening | Playfair Display | dark | one lead image at 8 columns, no headline above it | project sequence with captions |
106
- | Searchable catalog | 4 tool first | Space Grotesk | cool paper | search input on a signal-color band | results as an index list with tabular numbers |
107
- | Event registration | 3 typographic poster | Syne | night with one hot accent | 120 px date and venue, no image | the schedule as a sticky-panel scroll |
108
- | Home-repair service | 4 tool first (different band color and card content from the catalog) | Bricolage Grotesque | neutral with orange | problem picker and zip code | plan table with actual limits |
105
+ Fill this before building the first site. No two rows share a model, an inventory and a journey, and no two share both a canvas and a type voice.
109
106
 
110
- Two sites sharing archetype 4 is allowed only when band color, card content and the next section differ; mark it in the table, as above. If the table cannot be filled without repetition, the set does not yet have five identities.
107
+ | Site | Visitor's job | Model | Records | Working journey | Canvas and type voice | Without the method |
108
+ | --- | --- | --- | --- | --- | --- | --- |
109
+ | Café | See what is on today, order ahead | Store | 27 menu items and beans | Pickup order with time slots | White, quiet | Slogan and a cup |
110
+ | Home repair | Get a visit booked for a problem today | Front door over Finder | 18 jobs with price ranges and response windows | Problem → zip code → window → confirmation | White, light | Slogan and three service cards |
111
+ | Photographer | Judge the work for a commission | Campaign | 6 projects, 60 photographs with captions | Filter by kind of work, open a project, send an inquiry | Dark, display on photographs | One hero photo and a quote |
112
+ | Meetup | Decide to come to the next event | Gathering | 10 upcoming and past events, 12 speakers | RSVP for a dated event | Warm tint, heavy | Slogan and three feature cards |
@@ -4,9 +4,13 @@ Use the project's existing browser or preview tooling. Adapt checks to the chang
4
4
 
5
5
  ## Visual pass
6
6
 
7
- Score the view first with the [generic-tells score sheet](generic-tells.md#score-sheet) at desktop and phone width and record the numbers. Three or more tells is a fail whatever the rest of this pass finds, and the repair is a changed decision in `design/decisions.md`, not a color swap. Then read the sheet's rejection condition and judge the render against it.
7
+ Read the decision sheet's line “Without this method I would have built” and look at the first screen and its next meaningful page or in-place state without rereading the reasons written in the sheet. Could that line describe what was delivered? If so, return to [Step 2](../SKILL.md#step-2-choose-the-site-model-and-its-patterns-by-the-visitors-job), even when the page passed every tell and accessibility check. Then name what a visitor can do on the delivered site that they could not do on that page, and do it in the browser. Keep owner-fixed compositions and conventional interactions within their brief.
8
8
 
9
- Read the visual criterion before judging the screenshot. If it only names colors, an illustration and readable layout, it cannot establish the intended design quality. Refer back to the decision sheet's premise and rejection condition to make its intended effect and rejection condition explicit. Preserve the user's ambition and criterion count; do not rewrite a failed criterion to match the result.
9
+ Use the measurement scope selected before implementation in Step 4. For a visual public homepage read the [first-screen judge](../SKILL.md#step-4-build-the-first-screen-and-the-journey-then-measure) result for the finished home page at desktop and phone width. A FAIL keeps the work open. A pass says only that the site is neither a brochure nor bare. It does not say the page looks good.
10
+
11
+ Then use the [generic-tells score sheet](generic-tells.md#score-sheet) at desktop and phone width. Record the numbers, apply its failing check and test the decision sheet's rejection condition. Keep the visual judgment even when the count is zero.
12
+
13
+ Read the visual criterion before judging the screenshot; when the brief states none, use the decision sheet's rejection condition. If it only names colors, an illustration and readable layout, it cannot establish the intended design quality. Refer back to the decision sheet's model and rejection condition to make the intended effect explicit. Preserve the user's ambition and criterion count; do not rewrite a failed criterion to match the result.
10
14
 
11
15
  Inspect a representative desktop and phone view. Also inspect the narrowest supported width for a new layout or a suspected breakpoint defect; include a middle width when the transition itself is in question. Choose dimensions from the project; 1440, 390 and 320 CSS pixels are possible samples, not a universal support contract.
12
16
 
@@ -24,6 +28,8 @@ Apply the relevant [UX foundations](ux-foundations.md) to the chosen visual mech
24
28
 
25
29
  ## Primary-task pass
26
30
 
31
+ Start from the study decision saved in the project sheet. On the recorded route, identify the actual item, time, filter or variant. Follow it to the destination and back at desktop and phone widths. Check the label, unit, selected state and return focus that matter to that task. On a one-view tool, inspect the in-place change and how someone reverses it. Add the observed outcome or the remaining evidence gap to the same sheet. A cited practice or a screenshot alone cannot demonstrate continuity.
32
+
27
33
  Follow the promised action to its outcome. A modal opening is not a completed booking, a submit click is not a saved record, and a toast alone is not persistence evidence. Where the feature promises saving, check the displayed result and reload or revisit it. Check cancellation and an applicable failure/recovery path using permitted test fixtures, not consequential live submissions.
28
34
 
29
35
  Use honest first-use state, representative populated state, and an edge state that could break this layout. Depending on the feature, that might mean a long name, missing photo, large value, many rows, narrow locale, delayed response or validation error. Exercise only states relevant to the feature. Avoid filling production screens with invented success, progress, testimonials or personal records to make them look complete.
@@ -32,11 +38,14 @@ In a prototype, local state and example data can be the intended outcome. Label
32
38
 
33
39
  ## Access and comfort pass
34
40
 
35
- Run an automated check in the rendered page first (axe-core through Playwright or the browser extension, or Lighthouse) at desktop and phone width, and record every reported contrast ratio and target size in the evidence. The decision sheet's script checks the palette; this step checks what the page actually rendered, including text on photographs, the dark band and button labels. Then:
41
+ The [judge](../SKILL.md#step-4-build-the-first-screen-and-the-journey-then-measure) has already counted, on each page you measured, the language and title, alt attributes, field labels, link and button names, tap-target size, a visible change on focus and contrast on solid backgrounds and, from the two screenshots, behind text on photographs. It cannot tell whether an alt describes the picture, whether the tab order makes sense, whether an error is announced, or whether text stays readable on a video, a slideshow or an animation. This pass is those.
42
+
43
+ Scan the rendered page with axe-core or an equivalent at desktop and phone widths. Exercise the relevant opened, error or success state and scan changed controls there too. Investigate incomplete results, particularly text over photos or translucent surfaces. Measure the actual foreground/background at the least legible part under the text, or give it a known surface and retest. Record the state and result. Leave an uncheckable item visibly unverified.
36
44
 
37
- - Follow the primary path with a keyboard. Check focus visibility, logical order, activation, modal containment where needed, Escape/close and focus return.
38
- - Inspect labels and semantic roles for controls, alternatives for meaningful images and text equivalents for visual data. Icon-only actions need accessible names. Check reading order when layouts reorder content.
39
- - Check contrast and legibility on actual surfaces, zoom/reflow, and targets that are practical to tap. Use project or applicable accessibility requirements; visual taste does not excuse inaccessible controls.
45
+ - Start with the keyboard at the page entry. Use Tab and Shift+Tab to reach the main control and Enter or Space as appropriate to its role. Check visible, unobscured focus, dialog containment where needed, close and return. Clicking a control or calling `focus()` directly can hide a missing tab stop.
46
+ - Follow focus through recovery too. If a Retry button disappears while content reloads, check where the keyboard user lands and how they learn the outcome.
47
+ - Inspect names, roles, states, heading order, meaningful alternatives and form error associations in the browser's accessibility tree. Check reading order when layouts reorder content. If assistive technology is available, exercise the changed journey with it and name the tool used. Record a tree inspection as such.
48
+ - Enlarge text to 200% and check the primary task for clipping or lost controls. Check reflow of vertical content at a 320 CSS pixel viewport, allowing applicable two-dimensional content exceptions. Inspect the action's touch target and spacing. Apply the [criterion-specific guidance](ux-foundations.md#keep-visual-treatment-accessible).
40
49
  - Check fixed navigation, banners and overlays for obscured actions or content. Phone keyboards and safe areas matter when they affect the requested input flow.
41
50
  - Check reduced motion and any automatic tour's pause/manual controls. Read status and errors without relying on animation or color alone.
42
51