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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/bin/cyc.mjs +55 -7
- package/docs/README.md +2 -0
- package/docs/runtime.md +4 -0
- package/docs/work-queue.md +187 -0
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-design/frontend-design/SKILL.md +125 -28
- package/methods/cyc-design/frontend-design/references/color.md +42 -50
- package/methods/cyc-design/frontend-design/references/craft-rules.md +13 -10
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +94 -98
- package/methods/cyc-design/frontend-design/references/experience-review.md +10 -2
- package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +82 -33
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
- package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
- package/methods/cyc-design/frontend-design/references/typography.md +59 -44
- package/methods/cyc-design/frontend-design/references/visual-material.md +40 -7
- package/methods/cyc-design/frontend-design/scripts/contrast.mjs +1 -1
- package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
- package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
- package/methods/cyc-verify/SKILL.md +1 -1
- package/package.json +6 -1
- package/plugin.json +1 -1
- package/scripts/hub-page.mjs +275 -0
- package/scripts/hub.mjs +139 -0
- package/scripts/queue-board.mjs +287 -0
- package/scripts/queue.mjs +283 -0
- package/scripts/run-gate.mjs +1 -1
- package/scripts/runtime.mjs +248 -13
- package/scripts/source-snapshot.mjs +1 -1
- package/scripts/work-review.mjs +1 -1
- package/skills/cyc/SKILL.md +8 -0
- package/skills/cyc/references/playbooks/plan.md +2 -0
|
@@ -1,116 +1,112 @@
|
|
|
1
1
|
# Decision sheet
|
|
2
2
|
|
|
3
|
-
|
|
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: <
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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>
|
|
36
51
|
```
|
|
37
52
|
|
|
38
|
-
|
|
53
|
+
## Example of the level of detail: a neighborhood café
|
|
39
54
|
|
|
40
|
-
|
|
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.
|
|
41
56
|
|
|
42
57
|
```markdown
|
|
43
58
|
# Design decisions: Halvard Coffee, Ballard
|
|
44
59
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
Display face: Bricolage Grotesque 800 · Text face: Figtree · Accent voice: none; the numbers are the voice
|
|
86
|
-
Display size: 64 px / 38 px, tracking −0.02 em, line height 1.05
|
|
87
|
-
|
|
88
|
-
Palette: #f3f4f1 #ffffff #15202b #55606b #1f3a5f #e4572e #b94b2d #d6dad3
|
|
89
|
-
Contrast: ink 14.9, muted 5.8, canvas on brand 10.4, accent-ink 4.6, accent display 3.3
|
|
90
|
-
Derived from: workwear navy, safety orange, plaster dust, galvanized conduit.
|
|
91
|
-
Radius: 8 · Surface system: flat blocks and hairlines · Dark section: crew and radius
|
|
92
|
-
|
|
93
|
-
Signature element: the request card with the problem picker and the promised window ("today before 6 pm" / "tomorrow 8 to 12").
|
|
94
|
-
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.
|
|
95
|
-
Icons: Phosphor regular, 24 px, in the problem picker only.
|
|
96
|
-
|
|
97
|
-
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.
|
|
98
|
-
Primary action: "Request a window" → confirmation with the chosen window; labeled demo, nothing sent.
|
|
99
|
-
Access: keep the ZIP code label visible. On invalid input, associate the error text with the field, retain the entry, and check keyboard correction through confirmation.
|
|
100
|
-
|
|
101
|
-
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.
|
|
102
99
|
```
|
|
103
100
|
|
|
104
|
-
|
|
101
|
+
The numbers in the example's Measurements block illustrate the format. Record what the judge prints for the real page.
|
|
105
102
|
|
|
106
|
-
|
|
103
|
+
## Several sites in one request
|
|
107
104
|
|
|
108
|
-
|
|
109
|
-
| --- | --- | --- | --- | --- | --- |
|
|
110
|
-
| Café | 1 split with bleed | Fraunces | warm cream | counter photograph bleeding right | weekly filter index list |
|
|
111
|
-
| 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 |
|
|
112
|
-
| Searchable catalog | 4 tool first | Space Grotesk | cool paper | search input on a signal-color band | results as an index list with tabular numbers |
|
|
113
|
-
| 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 |
|
|
114
|
-
| 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.
|
|
115
106
|
|
|
116
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,6 +38,8 @@ In a prototype, local state and example data can be the intended outcome. Label
|
|
|
32
38
|
|
|
33
39
|
## Access and comfort pass
|
|
34
40
|
|
|
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
|
+
|
|
35
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
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.
|