markilo 1.0.0 → 1.1.1

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 (18) hide show
  1. package/README.md +81 -51
  2. package/package.json +1 -1
  3. package/plugin/.claude-plugin/icon.png +0 -0
  4. package/plugin/.claude-plugin/plugin.json +1 -1
  5. package/plugin/agents/concept-designer.md +111 -85
  6. package/plugin/agents/design-critic.md +30 -95
  7. package/plugin/dist/markilo.mjs +222 -196
  8. package/plugin/skills/concepts/SKILL.md +18 -23
  9. package/plugin/skills/design/SKILL.md +125 -117
  10. package/plugin/skills/design/references/cli.md +49 -47
  11. package/plugin/skills/design/references/construction.md +42 -68
  12. package/plugin/skills/design/references/design-principles.md +163 -156
  13. package/plugin/skills/design/references/svg-authoring.md +11 -8
  14. package/plugin/skills/design/references/workflow.md +19 -20
  15. package/plugin/skills/export/SKILL.md +2 -1
  16. package/plugin/skills/gallery/SKILL.md +10 -8
  17. package/plugin/skills/refine/SKILL.md +18 -13
  18. package/plugin/skills/research/SKILL.md +3 -2
package/plugin/skills/design/references/cli.md CHANGED
@@ -24,46 +24,47 @@ Brief fields: `oneLiner`, `mode` (new/refresh/redesign/evaluate), `product{type,
24
24
 
25
25
  ## Research
26
26
 
27
- | Command | Purpose |
28
- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
- | `research site <url> --brand s --allow-network [--pages 8] [--download-assets] [--allow-private]` | Multi-page read: robots, sitemap, brand pages, JSON-LD, colors/fonts, logo candidates; access gaps recorded. |
30
- | `research competitors --brand s --allow-network [--url U --name N]… [--pages 3]` | Competitor findings + logos/icons collected as reference marks. |
31
- | `research app "<name | id | url>" --brand s --allow-network [--store ios\|android] [--competitor] [--as-reference]` | App Store (iTunes Search API) / Google Play listing. |
32
- | `research monorepo <repo> [--register --groups products,apps --parent p --lock a,b --scan]` | Find sites/apps/packages; register brandable ones with `codePaths`; scan each. |
33
- | `research repo [<path>] --brand s [--full]` | Local scan: package.json, README, logos, icon sets, design-system docs, manifests, CSS colors, fonts. Summary by default (full scan cached). Skips secret-like files. |
34
- | `profile understanding --brand s` | What the product does, for whom, where and at what price — with sources, stated vs inferred, and what is unknown. |
35
- | `profile tidy --brand s` | Rewrite the profile without absolute local paths (before committing a workspace). |
36
- | `profile show --brand s [--full] [--topic t]` | Brand Intelligence Profile summary. |
37
- | `profile add-source --brand s --type url\|search\|registry\|file\|user --ref R [--notes N]` | Log a source with date. Returns its id (S1…). |
38
- | `profile add-finding --brand s --topic T --status observed\|inferred\|verified\|user-provided --statement "…" --source S1,S2 [--confidence low\|medium\|high]` | Record a finding. observed/verified need sources. |
39
- | `profile add-gap --brand s --text "…"` | Record an unknown. |
40
- | `answers --brand s [--question Q --answer A]` | Questions already asked; record new ones. |
41
- | `reference remove --brand s --id ID[,ID]` | Remove wrong or duplicate reference marks. |
42
- | `reference dedupe --brand s [--apply]` | Find (and remove) files that add no evidence: near-identical files of one brand, one artwork under two names. |
43
- | `reference list --brand s` | References grouped by brand, with source quality (official, store, catalog, unverified). |
44
- | `similarity calibrate (--brand s \| <folder>)` | Measure how well copies are caught and different marks kept apart on real logos. |
45
- | `reference add --brand s --file F --name "Brand" --source URL [--category direct\|indirect\|category]` | Add a reference mark (SVG/PNG/JPG) for similarity checks. |
27
+ | Command | Purpose |
28
+ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29
+ | `research site <url> --brand s --allow-network [--pages 8] [--download-assets] [--allow-private]` | Multi-page read: robots, sitemap, brand pages, JSON-LD, colors/fonts, logo candidates; access gaps recorded. |
30
+ | `research competitors --brand s --allow-network [--url U --name N]… [--pages 3]` | Competitor findings + logos/icons collected as reference marks. |
31
+ | `research app "<name | id | url>" --brand s --allow-network [--store ios\|android] [--competitor] [--as-reference]` | App Store (iTunes Search API) / Google Play listing. |
32
+ | `research monorepo <repo> [--register --groups products,apps --parent p --lock a,b --scan]` | Find sites/apps/packages; register brandable ones with `codePaths`; scan each. |
33
+ | `research repo [<path>] --brand s [--full]` | Local scan: package.json, README, logos, icon sets, design-system docs, manifests, CSS colors, fonts. Summary by default (full scan cached). Skips secret-like files. |
34
+ | `profile understanding --brand s` | What the product does, for whom, where and at what price — with sources, stated vs inferred, and what is unknown. |
35
+ | `profile tidy --brand s` | Rewrite the profile without absolute local paths (before committing a workspace). |
36
+ | `profile show --brand s [--full] [--topic t]` | Brand Intelligence Profile summary. |
37
+ | `profile add-source --brand s --type url\|search\|registry\|file\|user --ref R [--notes N]` | Log a source with date. Returns its id (S1…). |
38
+ | `profile add-finding --brand s --topic T --status observed\|inferred\|verified\|user-provided --statement "…" --source S1,S2 [--confidence low\|medium\|high]` | Record a finding. observed/verified need sources. |
39
+ | `profile add-gap --brand s --text "…"` | Record an unknown. |
40
+ | `answers --brand s [--question Q --answer A]` | Questions already asked; record new ones. |
41
+ | `reference remove --brand s --id ID[,ID]` | Remove wrong or duplicate reference marks. |
42
+ | `reference dedupe --brand s [--apply]` | Find (and remove) files that add no evidence: near-identical files of one brand, one artwork under two names. |
43
+ | `reference list --brand s` | References grouped by brand, with source quality (official, store, catalog, unverified). |
44
+ | `similarity calibrate (--brand s \| <folder>)` | Measure how well copies are caught and different marks kept apart on real logos. |
45
+ | `reference add --brand s --file F --name "Brand" --source URL [--category direct\|indirect\|category\|form-family\|inspiration\|dislike\|existing] [--notes "…"]` | Add a reference mark or image. Competitor categories feed similarity and the context sheet; `inspiration`, `dislike` and `existing` are the user's own references (logos, screenshots, mood boards, sketches) — read for characteristics, compared for originality, never shown as competitors. |
46
46
 
47
47
  Topics: product, audience, market, competitor, visual-identity, typography, color, naming, trend, culture, trademark, platform.
48
48
 
49
49
  ## Design
50
50
 
51
- | Command | Purpose |
52
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
53
- | `concept new --brand s --id ID --title T --direction D --rationale R --semantics a,b --primary '#hex' [--secondary --accent --ink --paper] [--font id --weight n] [--lead wordmark]` | Create `concepts/ID/`; then write `symbol.svg` there. |
54
- | `concept list --brand s` | Concepts with status, files, palette and `gate` (`passed`, `failed`, `not-reviewed`) with the critic average. |
55
- | `concept show --brand s --concept ID` | One concept with its files, palette, typography, critique and `gate`. |
56
- | `wordmarks --brand s --concept ID [--fonts a,b] [--weights 500,700] [--tracking -20,0,20] \| --pick wN` | The name in several faces next to the symbol on `review/wordmarks.png`, measured; `--pick` commits one as `wordmark.svg` with its typography. |
57
- | `sketches --brand s --concept ID` | Build `sketches/*.json` in the concept palette into `sketches/board.png` for the critic's sketch review; says which are `ready` (with `fix` lines). Specs with `members` also get `sketches/family.png`. |
58
- | `construct spec.json -o out.svg [--guides c.png] [--set k=v,…]` | Build a mark from a construction spec (see construction.md). |
59
- | `construct spec.json --brand s --concept ID [--vary [--max 24]] [--set k=v,…] [--member name] [--role small]` | Into the concept: `symbol.svg`, `construction.json`, `review/construction.png`; `--vary` ranks variants in `sketches/variants/`. |
60
- | `wordmark --text T --font id --weight n -o out.svg [--tracking=-10] [--case lower] [--color '#hex'] [--locale tr]` | Outlined wordmark with real kerning. Negative tracking needs `=`. |
61
- | `lockup --symbol a.svg --wordmark b.svg --layout horizontal\|stacked -o out.svg` | Cap-height aligned lockup. |
62
- | `ideas --brand s [--add "<hook>" --means "<why>" --source product\|audience\|name\|type\|abstract] [--idea iN (--keep "<reading>" [--rank n] \| --strike "<reading>") \| --concept ID]` | The idea longlist before directions: designer adds hooks, critic keeps/strikes from the words and ranks; `next` says what follows. |
63
- | `concept update --brand s --concept ID [--wordmark wordmark.svg] [--status shortlisted\|rejected] [--judgment memorability=8:"reason"] [--present yes\|no:"reason"] [--blind distinctiveness=n,memorability=n,brand-fit=n,craft=n,versatility=n] [--reviewer <model>] [--reads-as "a; b; c"] [--sketch-pick s3\|none --sketch-notes "…"] [--look <five scores> --look-present yes\|no:"reason"]` | Update files/status/judgment; `--look` records a fresh critic's second look when the gate says `second-look`. Criteria: brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft, typography, color, cultural-fit, timelessness, premium-perception, versatility. Prints the `gate` (blind scores when recorded) with `next` (`present`, `fix` once, `reject`, `second-look`), the `reviewer` and whether the gate was calibrated on it. |
64
- | `color compare #a #b [#c…]` | ΔE00 and WCAG contrast between colors (e.g. an accent vs a well-known brand color). |
65
- | `palette '#primary' [--secondary '#…'] [--accent '#…']` | OKLCH scales, neutrals, semantic colors, WCAG pairs. |
66
- | `fonts` | Bundled OFL fonts (inter, manrope, space-grotesk, sora, dm-sans, outfit, plus-jakarta-sans, fraunces, ibm-plex-serif, jetbrains-mono). |
51
+ | Command | Purpose |
52
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
53
+ | `concept new --brand s --id ID --title T --direction D --rationale R --semantics a,b --primary '#hex' [--secondary --accent --ink --paper] [--font id --weight n] [--lead wordmark] [--round n [--directed "<user's words>"]]` | Create `concepts/ID/`. `--round`: the exploration round (at most 3 proposals per round; a round beyond 2 needs the user's direction). Then write `symbol.svg` (the compact icon) and `wordmark.svg`. |
54
+ | `concept list --brand s` | Concepts with status, files, palette and `gate` (`passed`, `failed`, `not-reviewed`) with the critic average. |
55
+ | `concept show --brand s --concept ID` | One concept with its files, palette, typography, critique and `gate`. |
56
+ | `wordmarks --brand s --concept ID [--fonts a,b] [--weights 500,700] [--tracking -20,0,20] \| --pick wN` | The name in several faces next to the symbol on `review/wordmarks.png`, measured; `--pick` commits one as `wordmark.svg` with its typography. |
57
+ | `sketches --brand s --concept ID` | Optional: build `sketches/*.json` construction specs onto `sketches/board.png` and say which are not `ready` (with `fix` lines). Specs with `members` also get `sketches/family.png`. |
58
+ | `construct spec.json -o out.svg [--guides c.png] [--set k=v,…]` | Build a mark from a construction spec (see construction.md). |
59
+ | `construct spec.json --brand s --concept ID [--vary [--max 24]] [--set k=v,…] [--member name] [--role small]` | Into the concept: `symbol.svg`, `construction.json`, `review/construction.png`; `--vary` ranks variants in `sketches/variants/`. |
60
+ | `wordmark --text T --font id --weight n -o out.svg [--tracking=-10] [--case lower] [--color '#hex'] [--locale tr]` | Outlined wordmark with real kerning. Negative tracking needs `=`. |
61
+ | `lockup --symbol a.svg --wordmark b.svg --layout horizontal\|stacked -o out.svg` | Cap-height aligned lockup. |
62
+ | `ideas --brand s [--add "<hook>" --means "<why>" --source …]` | Optional idea log (kept for compatibility; the default workflow does not need it). |
63
+ | `proposals --brand s [--round n \| --concepts a,b,c]` | Render a round for the user's decision: `concepts/<id>/review/proposal.png` per concept (the identity on its paper and reversed, the icon as app tile, avatar, 32 and 16 px, the idea) and `proposals/round-<n>.png` side by side; `missing` lists what a proposal still lacks (word, icon, strengths/weaknesses). |
64
+ | `concept update --brand s --concept ID [--idea "<sentence>" --strengths "a; b" --weaknesses "a; b"] [--wordmark wordmark.svg] [--status shortlisted\|rejected] [--judgment memorability=8:"reason"] [--present yes\|no:"reason"] [--blind distinctiveness=n,memorability=n,brand-fit=n,craft=n,versatility=n] [--reviewer <model>] [--reads-as "a; b; c"] [--sketch-pick s3\|none --sketch-notes "…"] [--look <five scores> --look-present yes\|no:"reason"]` | Update files/status/judgment; `--look` records a fresh critic's second look when the gate says `second-look`. Criteria: brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft, typography, color, cultural-fit, timelessness, premium-perception, versatility. Prints the `gate` (blind scores when recorded) with `next` (`present`, `fix` once, `reject`, `second-look`), the `reviewer` and whether the gate was calibrated on it. |
65
+ | `color compare #a #b [#c…]` | ΔE00 and WCAG contrast between colors (e.g. an accent vs a well-known brand color). |
66
+ | `palette '#primary' [--secondary '#…'] [--accent '#…']` | OKLCH scales, neutrals, semantic colors, WCAG pairs. |
67
+ | `fonts` | Bundled OFL fonts (inter, manrope, space-grotesk, sora, dm-sans, outfit, plus-jakarta-sans, fraunces, ibm-plex-serif, jetbrains-mono). |
67
68
 
68
69
  ## Verify
69
70
 
@@ -79,18 +80,19 @@ Topics: product, audience, market, competitor, visual-identity, typography, colo
79
80
 
80
81
  ## Deliver
81
82
 
82
- | Command | Purpose |
83
- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84
- | `finalize --brand s --concept ID [--tagline T] [--note "usage rule"]... [--accept-risk] [--user-choice "why"] [--force]` | Freeze masters, build lockups (horizontal/stacked/compact), write `final/brand.json`. Refuses a concept that failed the critic gate unless `--user-choice`. |
85
- | `lock --brand s --primary '#hex' [--symbol f] [--wordmark f] [--lockup f]` | Register an existing identity to preserve byte-for-byte. |
86
- | `deliverables --brand s [--set g,…] [--add g,…] [--remove g,…]` | Which groups this brand needs; suggests from product type and platforms. |
87
- | `export --brand s [--only logos,web,ios,macos,android,windows,social,marketing,tokens,guidelines] [--all] [--clean]` | Chosen groups (deliverables) + `asset-manifest.json`. |
88
- | `gallery [--brand s] [--serve [--port N]]` | `brand/gallery/index.html`; `--serve` serves it on 127.0.0.1 (token, read-only, stops when idle) so "Send to your agent" saves decisions. |
89
- | `feedback [--brand s] [--import file] [--apply]` | Decisions from the gallery: keep/refine/drop, tags, notes, pinned spots, preferred concept, ready-to-act requests; `--apply` sets concept status. |
90
- | `install-assets --brand s --framework auto\|next\|laravel\|flutter\|static [--project <dir>] [--apply [--expect <planId>]] [--force]` | Files where the framework expects them (plan unless `--apply`; one transaction, replaced files backed up; `--expect` refuses a stale plan). Without `--framework`: `--group web --into public`. `install-assets --undo [--apply]` reverses the last installation. |
91
- | `agent-setup --target codex\|cursor\|vscode\|generic [--model critic=<id>]... [--apply]` | The workflow for another coding agent, and the researcher, designer and critic as its sub-agents (`.codex/agents`, `.cursor/agents`, `.github/agents`) on the models named with `--model`. Dry run unless `--apply`. |
92
- | `shortcut install\|uninstall\|status [--yes]` | Optional personal `/markilo` skill. |
93
- | `doctor` | Environment check. |
83
+ | Command | Purpose |
84
+ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85
+ | `finalize --brand s --concept ID --user-choice "<the user's words>" [--tagline T] [--note "usage rule"]... [--accept-risk] [--force]` | Freeze masters, build lockups (horizontal, stacked, compact) and `brand.json`. Needs the user's choice (a critic's pass alone never finalizes) and an originality verdict of `no-conflicts-found` unless `--accept-risk`. |
86
+ | `lock --brand s --primary '#hex' [--symbol f] [--wordmark f] [--lockup f]` | Register an existing identity to preserve byte-for-byte. |
87
+ | `deliverables --brand s [--set g,…] [--add g,…] [--remove g,…]` | Which groups this brand needs; suggests from product type and platforms. |
88
+ | `export --brand s [--only logos,web,ios,macos,android,windows,social,marketing,tokens,guidelines] [--all] [--clean]` | Chosen groups (deliverables) + `asset-manifest.json`. |
89
+ | `gallery [--brand s] [--serve [--port N]]` | `brand/gallery/index.html`; `--serve` serves it on 127.0.0.1 (token, read-only, stops when idle) so "Send to your agent" saves decisions. |
90
+ | `feedback [--brand s] [--import file] [--apply]` | Decisions from the gallery: select / change / drop, combine, reject a whole round (with a note), tags, notes, pinned spots, the preferred concept, and ready-to-act `requests`. `--apply` marks selected concepts shortlisted and dropped or round-rejected ones rejected. |
91
+ | `cost --brand s [--phase understand\|explore\|refine\|verify\|export (--tokens n \| --usd x) [--minutes m] [--rate r] [--note t]] [--budget usd]` | Cost per creative phase against a budget (default $12). Tokens are estimated at $0.60 per million (measured on Markilo 1.0 runs; a lower bound — the orchestrating session is not counted) unless `--usd` records a measured cost. `status: over` means stop paid work and ask; `warn` at 80 %. |
92
+ | `install-assets --brand s --framework auto\|next\|laravel\|flutter\|static [--project <dir>] [--apply [--expect <planId>]] [--force]` | Files where the framework expects them (plan unless `--apply`; one transaction, replaced files backed up; `--expect` refuses a stale plan). Without `--framework`: `--group web --into public`. `install-assets --undo [--apply]` reverses the last installation. |
93
+ | `agent-setup --target codex\|cursor\|vscode\|generic [--model critic=<id>]... [--apply]` | The workflow for another coding agent, and the researcher, designer and critic as its sub-agents (`.codex/agents`, `.cursor/agents`, `.github/agents`) on the models named with `--model`. Dry run unless `--apply`. |
94
+ | `shortcut install\|uninstall\|status [--yes]` | Optional personal `/markilo` skill. |
95
+ | `doctor` | Environment check. |
94
96
 
95
97
  Error codes: USAGE, NOT_FOUND, EXISTS, UNSAFE_PATH, INVALID_INPUT, INVALID_SVG, NETWORK_DISABLED, NETWORK,
96
98
  ROBOTS_DISALLOWED, LOCKED, NO_WORKSPACE, INTERNAL.
package/plugin/skills/design/references/construction.md CHANGED
@@ -1,10 +1,10 @@
1
- # Building marks with construction specs
1
+ # Construction specs — an optional drawing tool
2
2
 
3
- Do not hand-type path coordinates for a symbol. Describe how the mark is **built** — primitives, cuts, gaps,
4
- offsets, repeats, real letterforms — in a JSON construction spec, and let `markilo construct` turn it into exact,
5
- filled, optimized SVG. A spec is how a designer thinks ("a 300-unit ring, cut open at 2 o'clock, with a bar
6
- crossing it and a 32-unit gap where they meet"). Every measurement is a named parameter, so one spec gives many
7
- measured variants.
3
+ `markilo construct` turns a JSON description of how a mark is built — primitives, real letterforms, your own paths,
4
+ booleans, gaps, repeats — into exact, filled, optimized SVG. Use it when it helps: to join or cut real letters, to
5
+ outline a stroked skeleton into a custom letter, to keep measurements consistent, or to try measured variants. It is
6
+ not required. Freeform SVG paths written by hand are equally valid (`svg-authoring.md`), and the best work often mixes
7
+ both: a drawn contour, merged with a letter, cleaned up by a boolean.
8
8
 
9
9
  ```
10
10
  markilo construct <spec.json> -o <out.svg> [--guides <construction.png>] # build one
@@ -79,28 +79,20 @@ With `--brand/--concept`, palette roles come from the concept, the result is wri
79
79
  Every shape also takes `round` (fillet all corners with this radius), `grow` (offset), `scale`, `rotate`, `flip`
80
80
  (`x`/`y`), `move` `[dx, dy]` and `origin` (default: the shape's centre). Order: grow, round, scale, flip, rotate, move.
81
81
 
82
- ## Process
83
-
84
- 1. **Write the idea sentence first** (design-principles.md). Then pick the _move_ that makes it ownable (below).
85
- Write it as what the eye catches, then what it means: _"one stem shared by two arches — research and verification
86
- meet in an m"_. The first half must be visible at 32 px; a story without a visible hook ("a safe crossing from work
87
- to payment") is not a sketch yet.
88
- 2. **Sketch wide**: 3–5 specs (`sketches/s1.json …`), each a different move, not a nudge, each with an `"idea"`
89
- sentence in that form. `markilo sketches --brand <slug> --concept <id>` builds them all onto `sketches/board.png` for the
90
- critic's sketch review. Build each with
91
- `construct sN.json -o sN.svg --brand <slug> --concept <id>` (with `-o` the concept's palette is used and nothing
92
- in the concept changes), compare with `markilo render s1.svg s2.svg … --compare --paper <paper> -o
93
- compare.png`, `Read` it. Keep one; say why the others lost.
94
- 3. **Tune by measurement**: put the uncertain measurements (stroke weight, gap, cut angle, overlap) in `vary`, run
95
- `--vary`, `Read` `variants.png`. The score is a guide, not the judge: pick by eye among the top rows. A red
96
- label names the first failing check; `variants.json` has every check's message.
97
- 4. **Commit**: `construct … --brand --concept --set …` → `symbol.svg`, `construction.json`, `construction.png`.
98
- 5. **Verify** (`markilo verify`) and look at the 16 px, dark and one-color rows. Fix in the spec, not the SVG.
99
- 6. For wordmarks, start from `markilo wordmark`; for a custom letter (a cut, a ligature, a terminal that carries
100
- the idea) build that letter as a `glyph` with booleans and compose it with `lockup`, or build the whole word
101
- with `glyph` and `"role": "wordmark"` (its recipe is saved as `construction-wordmark.json`). `construct` prints
102
- each letter's box, baseline, cap and x-height (`glyphs`), so cuts can be aimed at a stem or a bar by expression
103
- rather than by reading path data. Judge wordmarks with `markilo render wordmark.svg -o wm.png --width 1200`.
82
+ ## Using it well
83
+
84
+ - **Custom letters as skeletons.** Draw a letter's centre line as a `path` with `width` (and `cap`/`join`); Béziers
85
+ (`C`) give it a drawn quality. The same `width` across letters gives a consistent stroke; `union` with real glyphs
86
+ where you keep the font's letters. This is the quickest route to lettering no font has.
87
+ - **Real letters, edited.** A `glyph` gives the font's outline; `subtract` a shape to cut a terminal or open a
88
+ counter, `union` a drawn stroke to make a ligature between neighbours. `construct` prints each glyph's box, baseline,
89
+ cap and x-height (`glyphs`), so edits are aimed by expression, not guessed.
90
+ - **Words.** Build the whole word in one spec with `"role": "wordmark"` (the recipe is saved as
91
+ `construction-wordmark.json` and the wordmark keeps its type metrics for lockups).
92
+ - **Variants.** Put an uncertain measurement (stroke, gap, angle) in `params` + `vary` and run `--vary`; choose by eye
93
+ among the top rows of `variants.png`.
94
+ - **Look.** Render (`markilo render out.svg -o out.png --width 1200`) and `Read` it after every change. A spec is only
95
+ as good as the drawing it produces.
104
96
 
105
97
  ## A worked example
106
98
 
@@ -148,9 +140,9 @@ a letter, and a strict independent judge rated it 5.8/10 (the knockout where the
148
140
  One move (overlap), one unit system, one accent on the idea, every gap ≥ 80 units. Its weakness is the idea's
149
141
  first reading — a letter m — which is why most directions should not start from the name's initial.
150
142
 
151
- ## Moves that make a mark ownable
143
+ ## Moves that can make a mark ownable
152
144
 
153
- Each is a construction technique, not a shape to copy. Combine at most two.
145
+ Techniques, not recipes — use one when it serves the idea.
154
146
 
155
147
  - **Letter carries the metaphor**: a `glyph` whose counter, terminal or stem becomes the object — `subtract` the
156
148
  metaphor from the letter, or `union` a part of it in. Only when the object is the first reading; an initial with a
@@ -192,39 +184,22 @@ product with `construct <spec> --brand <product> --concept <id> --member <name>`
192
184
 
193
185
  ## Wordmarks
194
186
 
195
- Carry the symbol's idea into the wordmark **once**: one or two letters that share the symbol's move (a cut, a corner,
196
- a terminal), on top of a calm, well-spaced typeface. Rebuilding every letter from the idea makes the word busy and
197
- harder to read, and it reads as a display face rather than a brand. Every letter must still be readable on its own:
198
- check `e`, `a`, `w`, `m` and other complex forms at 1200 px and at 64 px wide.
199
-
200
- A treatment can also run through the whole word instead of living in one letter — the usual way a coined name gets
201
- character. Transforms on a `glyph` apply to every letter at once: `"round": 18` softens every corner and terminal,
202
- `"grow": 6` adds weight evenly, and a `subtract` of one repeated `rect` (`repeat` with `step`) cuts every stem at the
203
- same angle. Pick one treatment from the brief's form language, check it at 12 px, and keep the letters themselves
204
- untouched.
205
-
206
- ### Wordmark-led concepts (`--lead wordmark`)
207
-
208
- The word is the identity, so it is built, not typeset:
209
-
210
- 1. Choose the face on the wordmark board: `markilo wordmarks --brand <slug> --concept <id>` (the bundled faces,
211
- weights and spacing, measured), and commit one with `--pick`.
212
- 2. Build the word as one spec with `glyph` and `"role": "wordmark"`, then change one or two letters with booleans so
213
- they carry the idea — join two letters into a ligature, reshape a counter, extend or cut a terminal, share a stroke
214
- between neighbours. Aim the change by the printed `glyphs` boxes (stem, bowl, x-height), not by eye.
215
- 3. Cut the icon from the same drawing: a second spec with the same `glyph` and the same change, keeping only the
216
- changed letter or pair (`"letters": [i]`), fitted to the square — `construct … --role symbol`. Add a small version
217
- when the change disappears at 16 px.
218
- 4. `markilo verify` writes `review/wordmark-sheet.png` (the word at 12–64 px on light, dark, black and white). Read it
219
- as a stranger: the word must stay readable at 12 px, and the change must be visible at 24 px.
220
-
221
- `construct` and `sketches` measure every changed letter against the font's own alphabet. A letter that now looks more
222
- like another letter ("o" cut open on the right is a "c": the word reads "necn") makes the sketch not `ready`; a letter
223
- that lost its counter (an e without its eye) or two letters merged into one shape is a note the critic weighs. Most
224
- misread wordmarks in Markilo's benchmark came from exactly these: "portwise" read as "partwise", an "ll" as a "4" or
225
- an "n", a "pinehold" whose e lost its eye. Change a terminal, a join or a counter's shape; keep the stroke that names
226
- the letter. A separate element dropped into the word is read as punctuation: between letters a hyphen ("searve-x"),
227
- over a letter an accent ("jourílo"), after the word a full stop. Put it inside a counter or attach it to a letter.
187
+ See "Wordmark first" in `design-principles.md` for what to aim for. With construct:
188
+
189
+ 1. Compare faces quickly: `markilo wordmarks --brand <slug> --concept <id> --fonts a,b,c --weights 500,700
190
+ [--tracking -20,0,20]` (`review/wordmarks.png`).
191
+ 2. Build the word in one spec with `glyph` and `"role": "wordmark"`, then apply the treatment across it: a ligature
192
+ from a `union` of two neighbours and a drawn stroke, terminals cut at one angle by a repeated `subtract`, `round` to
193
+ soften every corner, `grow` for weight, custom letters drawn as skeleton paths. Aim by the printed `glyphs` boxes.
194
+ 3. Derive the icon from the same drawing: the same spec keeping only some letters (`"letters": [i]`), fitted to the
195
+ square, with `construct … --role symbol`; then redraw it until it stands on its own.
196
+ 4. `markilo verify` writes `review/wordmark-sheet.png` (12–64 px on light, dark, black and white): the word must stay
197
+ readable at 12 px.
198
+
199
+ `construct` and `sketches` measure every changed letter against the font's own alphabet: a letter that now looks more
200
+ like another letter ("o" cut open on the right reads as "c") is flagged; a letter that lost its counter or two letters
201
+ merged into one shape is a note to weigh. A separate element dropped into a word reads as punctuation — a hyphen
202
+ between letters, an accent over one, a full stop after the word — so attach it to a letter or put it inside a counter.
228
203
 
229
204
  ## Craft checklist
230
205
 
@@ -246,9 +221,8 @@ over a letter an accent ("jourílo"), after the word a full stop. Put it inside
246
221
  - Before you commit, describe the mark in one sentence without naming a shape ("a ring and a bar" is a shape; "a
247
222
  door left ajar" is an idea). If you can only name shapes, go back to step 1.
248
223
 
249
- ## Patterns the critic scores low
224
+ ## Patterns that read as generic
250
225
 
251
- Circle + bar, plain rings, a single letter in a stock font in a rounded square, generic arrows/checkmarks/sparkles,
252
- radial petals, interlocking circles, gradient blobs, swooshes, abstract "network" dots, and shapes that are already
253
- UI icons (paperclip/hairpin = attachment, power symbol, refresh arrows, padlock, cloud). Clean execution does not
254
- rescue a generic idea.
226
+ Circle + bar, plain rings, a single letter in a stock font in a rounded square, generic arrows, check marks and
227
+ sparkles, radial petals, interlocking circles, gradient blobs, swooshes, "network" dots, and shapes that are already UI
228
+ icons (paperclip, power symbol, refresh arrows, padlock, cloud). Clean execution does not rescue a generic idea.