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,51 +1,66 @@
|
|
|
1
1
|
# Typography
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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`,
|
|
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
|
|
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
|
-
|
|
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
|
-
-
|
|
12
|
-
-
|
|
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 |
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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);
|