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,51 +1,66 @@
1
1
  # Typography
2
2
 
3
- Type is the fastest way to leave the default page. Choose a pairing by the character the product needs, set the display size and tracking by the numbers below, and load the fonts so they actually render.
4
-
5
- ## Pairings
6
-
7
- All are free on Google Fonts and as `@fontsource` packages. Character notes say what the pairing does, not what it is "for"; choose against the decision sheet's premise.
8
-
9
- | Display | Text | Character | Fits |
10
- | --- | --- | --- | --- |
11
- | DM Serif Display | DM Sans | High-contrast serif with tight tracking; confident, editorial, warm when set on cream | Services that sell judgment: careers, finance, consulting, premium local trades |
12
- | Lora (regular and italic) | DM Sans | Calm book serif; the italic reads as a second, softer voice | Health, food, daily tools, anything that should feel taken care of |
13
- | Fraunces | Inter Tight or Work Sans | Soft "wonky" serif with optical sizes; cozy without being cute | Cafés, bakeries, craft products, small hospitality |
14
- | Playfair Display | Source Sans 3 | Classic high-contrast; luxury if restrained, costume if overused | Photography, weddings, galleries, hotels |
15
- | Cormorant Garamond (500 to 600) | Manrope | Delicate, long ascenders; needs size to work (72 px and up) | Fine dining, perfume, art, editorial covers |
16
- | Instrument Serif | Instrument Sans | Narrow, modern serif; tech with taste | Software with a point of view, studios, agencies |
17
- | Newsreader | Public Sans | Journal serif with real italics; long-form comfort | Blogs, documentation with voice, reports |
18
- | Libre Caslon Text | Karla | Bookish and even; quiet authority | Education, nonprofits, archives |
19
- | Space Grotesk | IBM Plex Sans + IBM Plex Mono | Geometric with quirks; engineering honesty | Catalogs, data tools, developer products |
20
- | Bricolage Grotesque (700 to 800) | Figtree | Friendly, slightly condensed, punchy at size | Local services, home repair, community events |
21
- | Archivo Black or Archivo Expanded | Archivo | Heavy industrial grotesque | Workshops, trades, sports, bold retail |
22
- | Syne (800) | Inter | Wide, poster-like, a little strange | Festivals, music, art events |
23
- | Bebas Neue | Barlow | Tall condensed caps; loud and cheap in a good way | Events, gyms, schedules, menus on walls |
24
- | Epilogue (variable) | Epilogue | One family, 100 to 900; wide headings, clean text | Dashboards and apps that want one voice |
25
-
26
- Not for display: Inter, Roboto, Poppins, Montserrat, Open Sans, Lato, `system-ui`. They are tell 7 on the [generic list](generic-tells.md). Inter or a system stack is acceptable as the text face in a dense tool when the decision sheet says why.
27
-
28
- One accent voice per page, at most: a Kalam or Caveat phrase, or the display face's italic, on the two or three words that carry the promise. On every heading it stops being an accent.
29
-
30
- ## Numbers
31
-
32
- | Role | Desktop | Phone | Tracking | Line height |
33
- | --- | --- | --- | --- | --- |
34
- | Display (page opening) | 56 to 96 px, `clamp(2.75rem, 6vw, 6rem)` | 36 to 44 px | −0.02 em to −0.04 em | 0.95 to 1.1 |
35
- | Section heading | 32 to 44 px | 28 to 32 px | −0.01 em to −0.02 em | 1.1 to 1.2 |
36
- | Body, marketing | 17 to 19 px | 16 to 17 px | 0 | 1.5 to 1.65 |
37
- | Body, dense tool | 14 to 16 px | 14 to 15 px | 0 | 1.4 to 1.5 |
38
- | Eyebrow label | 11 to 13 px, uppercase | same | +0.08 em to +0.14 em | 1 |
39
- | Caption, meta | 12 to 13 px | same | 0 to +0.02 em | 1.3 |
40
-
41
- - Measure: body 55 to 72 characters; a display headline at most 12 words and about 20 characters wide per line, so it wraps on purpose.
42
- - Weight: serif display faces usually at 400 to 500; one heavy weight on the page, not three.
43
- - Oversized numerals: index numbers (01, 02), prices and the one real statistic set in the display face at display size. `font-variant-numeric: tabular-nums` on any column of numbers.
44
- - Hierarchy test: screenshot at 25% zoom. If display, heading, body and eyebrow are not distinguishable as four roles, the scale is too flat.
3
+ The eight studied sites do not share a typeface or a size. Each chose a voice and held to it: one has no headline at all, one sets a light 40 px line, one sets 88 px at the heaviest weight. What they share is discipline. Each family has one job, interface text is small and steady, and the display size is far from the body size or absent.
4
+
5
+ Choose one voice below from the subject and write it in the [decision sheet](decision-sheet.md). An existing brand's type replaces all of this.
6
+
7
+ ## Voices
8
+
9
+ Sizes are what was measured at 1440 wide. Phone sizes follow each voice.
10
+
11
+ ### Quiet: a short headline, small everything else
12
+
13
+ The items carry the page, so the interface stays small and steady. A scene-led offer can use a short 44 to 64 px headline. A catalog can lead straight into a compact department heading and its items. Section and shelf headings 20 to 28 px at weight 600 to 700. Body and item titles 13 to 16 px. Secondary facts 12 px in gray. One family, two or three weights.
14
+
15
+ Fits a finder, a store, a dealer, a marketplace: anywhere the items carry the page once the opening has set the mood. A working surface may drop the headline entirely; nothing else should. Phone: headline 34 to 40 px, the rest the same.
16
+
17
+ ### Light: a calm, thin headline
18
+
19
+ Headline 40 px at weight 300, column headings 32 px at 300, sub-points 24 px at 300. Body 16 px at 400 with a 1.5 line height. Eyebrows 16 px at 600 in capitals with 0.5 px tracking. One family in three weights: 300, 400, 600.
20
+
21
+ Fits money, health, insurance, anything where calm is the promise. Needs a family with a true light weight, such as Source Sans 3, Nunito Sans or Figtree. Phone: 32 px.
22
+
23
+ ### Editorial serif: a serif headline over a plain sans
24
+
25
+ Headline 52 px in the hero and 60 to 70 px in later sections, in a display serif, line height about 1.0, tracking about −0.035 em. Body 17 px sans with a 1.7 line height. Small capital eyebrows with wide tracking. Optionally one phrase of the headline in a handwriting face, in the accent color, with a drawn underline.
26
+
27
+ Fits a personal service, craft, food, heritage, anything sold on care and judgment. Three families at most and each has one job: the serif only for headlines, the sans for everything else, the handwriting only for the one phrase. Candidates: DM Serif Display, Fraunces, Instrument Serif or Newsreader, with DM Sans, Figtree or Instrument Sans; Kalam or Caveat for the handwritten phrase. Phone: 44 to 48 px. Set it on a white or dark canvas: on a warm tint it is the look builds without this method chose ([tell 40](generic-tells.md#the-unchosen-look)), and the judge fails it unless a brand you were given sets both.
28
+
29
+ ### Large grotesque: one big plain statement
30
+
31
+ Headline 80 px at weight 500 with a line height of 1.0, centered, two lines. Section headings 54 px at 500. Body 18 px under the headline and 16 px elsewhere. Navigation 14 px. Weights stay in the middle: 400 to 500, never bold.
32
+
33
+ Fits software and tools, where the product picture below the headline is the proof. Candidates: Inter, Geist, Schibsted Grotesk, Hanken Grotesk. Phone: 40 px.
34
+
35
+ ### Heavy: very large and very bold
36
+
37
+ Headline 88 px at weight 800, tracking about −0.06 em, line height 0.95. Section headings 68 px, smaller ones 43 to 53 px. Body 18 to 20 px. A second, handwritten family at 36 to 48 px for short labels and photo captions that sound like a person talking.
38
+
39
+ Fits a community, an event, a cause, a brand with energy. Needs a family with an 800 weight, such as Plus Jakarta Sans, Bricolage Grotesque, Outfit or Epilogue. Phone: 52 px.
40
+
41
+ ### Display on photographs: type as part of the picture
42
+
43
+ Display capitals at 60 to 90 px set on full-bleed photographs, tracked out by about 2 px, for offers and prices. Interface text small: 12 to 14 px navigation and labels, 16 px body. A third, seasonal display face may carry one campaign.
44
+
45
+ Fits fashion, retail campaigns, entertainment. The type and the photograph are designed together; check its contrast on the picture. Candidates for the display face: Anton, Oswald, Barlow Condensed, Bebas Neue. Phone: 30 to 50 px.
46
+
47
+ ## Rules that held across all of them
48
+
49
+ - **Body text is 14 to 20 px**, most often 16 px. Navigation, labels and facts are 12 to 16 px.
50
+ - **Choose the scale for the task.** A display headline can dominate an invitation. A department or workspace heading should leave room for the first useful comparison.
51
+ - **Tight tracking on large type.** About −0.035 em at 50 px and −0.06 em near 90 px. Line height 0.95 to 1.05 above 48 px.
52
+ - **Each family has one job.** Four of the eight sites use one family. The others use two or three and never mix their jobs.
53
+ - **Weights are few.** Two or three per family.
54
+ - **Numbers people compare** use `font-variant-numeric: tabular-nums` and sit in the same place on every item. Check it in the render: set “11111” and “88888” and compare their widths. A builder found that DM Sans ignored it.
55
+ - **A price or a date may take display size** when it is the thing to read first.
56
+ - Measure: body 55 to 72 characters. A display line wraps on purpose, at about 20 characters per line.
57
+ - Hierarchy test: screenshot at 25 percent zoom. The lead, the items and the action should still be told apart.
58
+
59
+ Rotate families between projects. Do not reach for the same one each time, and never choose a family because the page felt plain: choose the voice first, then a family that can carry it.
45
60
 
46
61
  ## Loading
47
62
 
48
63
  - Local-only sites: `npm i @fontsource/<name>` and import the weights used, or copy the woff2 files into `/fonts` with `@font-face { font-display: swap; }`. Do not link Google Fonts on a site that must work offline.
49
- - Networked sites: the Google Fonts `<link>` with `display=swap`, two families at most, only the weights used.
64
+ - Networked sites: the Google Fonts `<link>` with `display=swap`, only the weights used. A site that opens from disk but loads its pictures from the network is a networked site.
50
65
  - Declare a fallback stack with `size-adjust` so the layout holds before the web font arrives, and render the page once with the font blocked to confirm nothing breaks.
51
- - Verify in the rendered page (`document.fonts.check` or the computed style) that the display face loaded. A pairing chosen in the decision sheet and silently replaced by Times is the worst outcome on this list.
66
+ - Verify in the rendered page (`document.fonts.check` or the computed style) that the family loaded. Inputs, selects and buttons need `font: inherit`.
@@ -1,6 +1,37 @@
1
1
  # Visual material
2
2
 
3
- A page made only of type and hairlines is a document, not a website. Every site held up as the bar carries visual material in every viewport: a photograph with a person in it, a product screenshot in a frame, a technician at a door, a ring chart beside a photo card. "No imagery and strong type" is a valid opening for one viewport; it is not a valid page. This reference says what counts, how much, and how to get it when the brief says local only.
3
+ Choose the material that reveals the subject. A meetup can use a single shared gesture. A fit guide can use several comparable photographs. A working calendar can communicate its most important relationship through dates, titles and their positions. Use the density check below for a page whose promise depends on showing the work.
4
+
5
+ ## What the studied sites show
6
+
7
+ Every one of the eight studied sites fills its first desktop screen with pictures: rows of item photographs, one photograph run to the edge of the screen, or the product itself. The method's [floor](../SKILL.md#step-4-build-the-first-screen-and-the-journey-then-measure) is four pictures in the first desktop screen, or one covering a quarter of it.
8
+
9
+ - **Photographs are of real people and real things:** the listings, the members, the clothes on people, the product, a person doing the task. Not a symbol of the category.
10
+ - **A set is framed alike:** the same shape, the same distance, the same kind of background across every item.
11
+ - **Show the differences a visitor judges.** Give people, products or places comparable photographs when appearance matters. For a record chosen by timing or status, show that information directly.
12
+ - **The opening photograph runs to an edge** of the screen, or fills its width. It is not a small rectangle in a side column.
13
+ - **Quality decides.** One well-lit, well-composed photograph does more than five dim or cluttered ones. Look at each picture at full size in the render before keeping it, and replace any you would not put on a real business's site.
14
+ - **Invented people.** For a fictional brief, put a photograph of the person's work on their card, such as a finished haircut or a plated dish, or use a stock portrait and list it in the handoff as a placeholder to replace. Never present a stock stranger as a named real person on a site that is going live.
15
+
16
+ ## The opening photograph
17
+
18
+ When a photograph communicates the subject best, give it enough space to read at both widths. A full-width scene with the task over it worked for a dealership; a room gallery or fit comparison earns space differently. For a scene-led opening, check the following qualities.
19
+
20
+ - **One subject.** A car on an empty road, a barber mid-cut, a hand fanning a deck of cards. Not a lot full of cars or a wide shot of a room.
21
+ - **Real light.** Dusk, a window, a lit counter, a single lamp. Flat midday light and flash read as a listing photo, not an opening.
22
+ - **Room for the text.** A calm area on one side, or a darkened side through a gradient scrim, so the headline and the task panel sit on it without covering the subject.
23
+ - **Full width.** It runs edge to edge with no frame, border or rounded corners, and the header can sit over it.
24
+ - **The right subject for the business.** The thing itself in use, or the place at its best. A symbol of the category (a generic handshake, a stock skyline) does not count.
25
+
26
+ Pick it before writing the headline, look at it at full size in the render, and try two or three before keeping one. The item photographs below it can be plainer; the opening cannot.
27
+
28
+ Text on a photograph has to be read by everyone, at both widths. The judge measures it from the marked and hidden screenshots in Step 4, behind the letters themselves. Three ways to make it pass, in order of reliability:
29
+
30
+ - **A solid panel.** The task panel on the opening sits on a solid colour; it is measured like any other text.
31
+ - **A scrim where the text is.** A gradient from clear to a dark tint, 0.6 to 0.8 opacity, under the headline and fading away from the subject. Check the phone: there the text block is taller and often climbs above the scrim, as on photo tiles whose names sit halfway up.
32
+ - **The calm side.** Set the text where the photograph is already dark and even, and choose the crop at each width so it stays there.
33
+
34
+ A text shadow helps only where it lies directly behind the letters; a soft glow around them does not count.
4
35
 
5
36
  ## The density rule
6
37
 
@@ -8,8 +39,8 @@ Use these checks on composed pages where the material helps visitors understand
8
39
 
9
40
  Measured on the desktop render, checked again on the phone:
10
41
 
11
- - In each of the first two viewports, at least one non-text element at least 25 percent of the viewport width: a photograph, an illustration with depth, a rendered object (a ticket, a menu board, a map, a product panel), or a color surface holding content.
12
- - Across the full page, at least three kinds of material from the list below, and at least one full-bleed band (image or color) that breaks the content column.
42
+ - Within the first two viewports, look for a visual element at least 25 percent of the viewport width. A first screen that opens on a search or a task entry may hold none when the next screen does. A deliberately aligned group can occupy that space together when each item is legible and comparing the items is the point. Inspect the detail people need to see at actual size.
43
+ - Follow the material into the next section. A single photograph can reveal a framing decision, lead into a sequence and show what the editor contributed. Bring in a second kind of material when it adds information, such as a plan beside a finished installation. Choose full bleed when scale helps the visitor see the subject.
13
44
  - No run of more than two consecutive sections that are text on the flat canvas.
14
45
 
15
46
  A page that fails this is tell 21 on the [generic list](generic-tells.md) however good its type is.
@@ -20,7 +51,7 @@ A page that fails this is tell 21 on the [generic list](generic-tells.md) howeve
20
51
  | --- | --- | --- |
21
52
  | Photograph with a subject | Puts a person, a place or the work in the room; the single biggest difference between a site and a document | Download under a permissive license and store in `/assets` with source and license noted (below) |
22
53
  | Product or interface rendered as an object | A ticket, a chalkboard, a receipt, a schedule card, an app screen in a device frame; proves the thing exists | Build it in HTML and CSS with the page's own tokens; it is content, not decoration |
23
- | Illustration with depth | A scene, not an icon: layered shapes, a horizon, shadow, texture, a drawn object at the size it would be | Inline SVG of 40 or more paths, or a generated bitmap when an image tool is available |
54
+ | Illustration with depth | A scene, not an icon: layered shapes, a horizon, shadow, texture, a drawn object at the size it would be | Use a drawing or generated image whose composition and detail read at the intended size |
24
55
  | Color surface holding content | A dark band, a brand block with a list inside it, a panel behind a form | Use a CSS background where it groups or emphasizes related content. Check its text, links and controls on that surface. |
25
56
  | Texture | Paper grain, a subtle noise, a halftone, a printed-ink edge; makes flat color feel like a material | CSS: an SVG `feTurbulence` filter at 4 to 8 percent opacity, or a repeating gradient; never a stock "mesh" blob |
26
57
  | Map or diagram | Where the place is, how the process runs | Inline SVG drawn from the real streets or steps |
@@ -28,14 +59,16 @@ A page that fails this is tell 21 on the [generic list](generic-tells.md) howeve
28
59
 
29
60
  Icons are not material. A row of icons in circles is tell 2.
30
61
 
31
- ## Getting photographs when everything must stay local
62
+ ## Getting photographs
63
+
64
+ A site that may load from the network can link photographs from a source whose license allows it, such as Unsplash, Pexels or Wikimedia Commons. Choose by how the photograph looks first, then confirm the license, and list every picture with its source in the handoff. Give each linked picture its dimensions, a description and a fallback color, and render the page once with pictures blocked.
32
65
 
33
- "Local" means the site runs without a server and without hot-linking. It does not mean the build may not fetch an asset once and store it.
66
+ When everything must stay local, the site runs without a server and without hot-linking. That does not mean the build may not fetch an asset once and store it.
34
67
 
35
68
  1. Search a permissive source. Wikimedia Commons answers without a key and returns the license with each file (checked 2026-11-02): `https://commons.wikimedia.org/w/api.php?action=query&generator=search&gsrsearch=<subject>&gsrnamespace=6&gsrlimit=10&prop=imageinfo&iiprop=url|extmetadata&format=json`; read `LicenseShortName` and keep CC0, CC BY and CC BY-SA with attribution. Openverse (`https://api.openverse.org/v1/images/?q=<subject>&license=cc0,by`) is a second source when reachable; it was not from the checking machine. The project's own asset folder comes first when it has anything usable.
36
69
  2. Pick for the composition, not the subject alone: where is the quiet area for text, is the subject sharp, does the light match the palette temperature. Reject anything that looks like a stock handshake. Open the downloaded file at full size and look for a watermark, a photographer's logo, a border or a caption baked into the pixels; a mark that is faint in a thumbnail is obvious across a full-bleed band, and a second copy of the same photograph on another host may carry it too.
37
70
  3. Fetch the file into `/assets/<name>.jpg`, resize to the largest displayed width (1600 px is enough for a full-bleed), and write `/assets/SOURCES.md` with the URL, author and license for each.
38
- 4. Set `width`, `height` and `object-position` for the desktop and phone crops, and one treatment for every photograph on the site (warm, duotone, hairline, untouched).
71
+ 4. Set image dimensions and choose the crop separately for desktop and phone. Protect the detail the design depends on, such as people looking at a laptop. Decide whether each group of pictures needs context, close detail or consistent framing.
39
72
 
40
73
  When an image-generation tool is available in the host, use it for a specific brief ("a two-group espresso machine on an oak counter, morning light from the left, quiet space on the right third") and store the result the same way. When neither is possible, say so in the decision sheet and compensate with rendered objects and illustration with depth, not with more paragraphs.
41
74
 
@@ -18,7 +18,7 @@ function report(role, foreground, background, minimum) {
18
18
 
19
19
  const colors = process.argv.slice(2);
20
20
  if (![2, 8].includes(colors.length) || !colors.every(color => /^#[0-9a-f]{6}$/i.test(color))) {
21
- console.error('Expected two opaque #RRGGBB colors or the eight palette colors in decision-sheet order.');
21
+ console.error('Expected two opaque #RRGGBB colors or the eight palette colors in the order given in references/color.md.');
22
22
  process.exitCode = 1;
23
23
  } else if (colors.length === 2) {
24
24
  report('normal text', ...colors, 4.5);