beehaven 0.8.24 → 0.8.29

package/skills/clearly-canvas/authoring.md

@@ -49,6 +49,12 @@ do not blindly resend only skipped operations. Mixed live/headless actions may h
 different rollback behavior. Use deterministic layer names and returned IDs to avoid
 duplicate content during retries.
 
+Also check ignored/rejected fields, warnings, mutation outcome and actual changed IDs. A matched
+node or `ok:true` receipt alone is not proof of an update. The bundled `assertReceipt` helper can
+reject partial drops; `requireChange:true` rejects an unexpected no-op. A deliberate replay may
+be unchanged and should reuse its previous evidence instead of recreating nodes.
+Keep executed payloads and returned-ID manifests separate from regenerated plans.
+
 ## Node shape and coordinates
 
 Fields are flat: `{name,type,x,y,w,h,text,size,family,fontWeight,fill,...}`.
@@ -71,6 +77,13 @@ Create normalizes hex colours; raw stored scenes use RGBA arrays in 0..1.
   moves/resizes use the catalog's frame/arrangement/scale actions; do not assume a patch
   reflows children.
 - Build backgrounds before foregrounds. Use `canvas.order` to change stacking.
+
+For create/update geometry, `coordinateSpace:"world"` or `"parent"` makes the intent explicit.
+Default behavior remains compatible with the rules above. Receipts include normalized world
+bounds and parent offsets where available. Template coordinates remain relative to their root.
+An SVG's bytes may be stored in `svgRef` once it exceeds the inline limit; this is valid artwork,
+not a missing node. Replacing `svg` clears and rebuilds its reference automatically. Never patch
+`svgRef` manually or guess its storage URL. Image `fit` is explicitly `contain` or `cover`.
 - Name nodes uniquely; use returned IDs where names collide. Parent content to its
   frame so movement, selection, clipping and reviews can treat it as one artifact.
 - Give an intended stroke both `stroke` and `strokeWidth`. Zero explicitly removes it.
@@ -106,6 +119,16 @@ and tokens when relevant. Constraints reflow children on frame resize; they do n
 a static canvas into a responsive website. Design explicit mobile artboards when the
 deliverable requires them, with content order and hierarchy reconsidered for the width.
 
+## Technique
+
+The same rules the in-app assistant works to (canvas-catalog returns them as `technique`).
+
+- AUTO-LAYOUT: rows and stacks (nav links, button groups, card rows, form fields) are a frame whose children you create in reading order, then canvas.auto-layout { id, direction, gap, padding, align, justify, hug }. hug:false keeps the frame size, which a full-width bar needs with justify:"space-between"; set a child to layoutSizingH/V "fill" | "hug" | "fixed" with canvas.update-nodes.
+- GRADIENTS: gradient { kind, angle, stops: [{ offset, color }] } replaces the solid fill. angle is the direction the colour travels: 0 = left to right, 90 = top to bottom, 45 = top-left to bottom-right (not CSS degrees). Use two or three stops from the brand palette, and keep text off a busy gradient or check its contrast in canvas.review.
+- SHADOWS AND BLUR: effects on any node. A soft card shadow is { type: "drop-shadow", x: 0, y: 4, blur: 16, spread: 0, color: "#0000001F" }; frosted glass is { type: "background-blur", blur: 16 }. Never fake a shadow with an extra rectangle.
+- SVG PLACEHOLDERS: until real imagery exists, draw it as an svg node at its final size in a muted tone from the brand palette, never a flat accent block, e.g. for a 400×240 slot svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 240"><rect width="400" height="240" rx="12" fill="#EDE6DF"/><circle cx="170" cy="96" r="14" fill="#CDBFB2"/><path d="M150 168l40-48 30 34 22-20 40 34z" fill="#CDBFB2"/></svg>' — <svg viewBox="0 0 W H"> always matches the node w and h. Put a label in its own text node and name the svg "<section> image placeholder". Hand-write only simple marks like this (placeholders, dividers, UI icons); logos, illustrations and finished artwork come from svg-make.
+- SECTIONS: one frame per page section, named exactly as its ticket says, inside the page artboard. Build a section in one canvas-act batch that ends with canvas.review of the artboard and carries ticket: { id: "<its key>", status: "done", resolution: "<what changed>" }. The ticket moves only when that review is clean or look; result.ticket says whether it did. Then start the next section.
+
 Use `arrow.create {from,to,routing,label}` for connected diagrams, so arrows remain bound
 when nodes move. Use native shapes and SVG for custom vector details. Keep labels as
 native text so they remain editable and measurable.
@@ -163,11 +186,11 @@ the backing shows through as dark wedges at the corners.
 
 ### Images from MCP
 
-The seven artifact MCP tools do not upload local binary files or dispatch `canvas-act`.
+The artifact MCP tools do not upload local binary files or dispatch `canvas-act`.
 For an image already reachable by an absolute URL, read the composition with
 `clearly_read {type:"composition",target:<id>}`; append an image node
 `{id,type:"image",src,x,y,w,h,fit:"contain",parentId?}` to the returned complete node
-array; then call `clearly_write {type:"composition",target:<id>,content:<JSON array>,
+array; then call `clearly_replace {type:"composition",target:<id>,content:<JSON array>,
 expectedRev:<canvasNodesRev>}`. Preserve every existing node. A stale revision is a
 merge prompt, never a reason to drop `expectedRev`. `clearly_edit` can change an
 existing image's `src`, `fit` or geometry, but cannot create a node. For a local file,
@@ -212,8 +235,8 @@ MCP's artifact tools are split by operation:
 
 - `clearly_catalog {type:"composition"}` exposes the current schemas.
 - `clearly_read` returns nodes and `canvasNodesRev`.
-- `clearly_write` creates a composition or replaces its full node array; use
-  `expectedRev` from the read for replacement.
+- `clearly_create {type:"composition"}` makes a composition; `clearly_replace` replaces its full
+  node array — pass `expectedRev` from the read.
 - `clearly_edit` patches existing nodes with `changes:{ids,patch}`.
 
 Canvas action dispatch and targeted pixels use the CLI. Do not invent

package/skills/clearly-canvas/review.mjs

@@ -1,20 +1,69 @@
 #!/usr/bin/env node
 /** Save review pixels outside the model context. No shell interpolation, no workspace mutations. */
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-export function rpc(action, payload) {
+export function assertReceipt(result, { requireChange = false } = {}) {
+  if (result?.ok === false || result?.error || result?.results?.some(r => r.ok === false)) {
+    throw new Error(result.error || result.results?.find(r => !r.ok)?.error || 'Canvas request failed');
+  }
+  for (const row of result?.results ?? [result]) {
+    const value = row.value ?? row;
+    if (value.ignoredFields?.length || value.rejectedFields?.length) {
+      throw new Error(`Fields were not applied: ${[...(value.ignoredFields ?? []), ...(value.rejectedFields ?? [])].join(', ')}. Some work may have landed; inspect the saved scene before retrying.`);
+    }
+    if (requireChange) {
+      const delta = value.canvasChanges;
+      const changed = ['changed', 'partial'].includes(value.outcome) || (Array.isArray(delta) ? delta.length > 0 : delta && typeof delta === 'object'
+        ? Number(delta.added || 0) + Number(delta.changed || 0) + Number(delta.removed || 0) > 0
+        : value.placed === true || /\.create(-node)?$/.test(String(row.action || '')) && !!value.id && !value.duplicate);
+      if (!changed) throw new Error('No nodes changed, or the receipt does not prove a change. Inspect the saved scene; do not treat a match as an update.');
+    }
+  }
+  return result;
+}
+
+export function rpc(action, payload, options) {
   const stdout = execFileSync('beehaven', ['call', action, '-'], {
     input: JSON.stringify(payload), encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
     stdio: ['pipe', 'pipe', 'pipe'], timeout: 120_000,
   });
   const result = JSON.parse(stdout);
-  if (result.ok === false || result.error || result.results?.some((r) => r.ok === false)) {
-    throw new Error(result.error || result.results.find((r) => !r.ok)?.error || 'Canvas request failed');
+  return assertReceipt(result, options);
+}
+
+export function sceneNodes(result) {
+  if (!Array.isArray(result?.nodes)) throw new Error('Expected composition-detail includeScene:true to return top-level nodes. Refusing to interpret a missing field as an empty canvas.');
+  return result.nodes;
+}
+
+/** Resume creates only. Existing layers are preserved, including the person's later edits. */
+export function resumeCanvasPlan(plan, snapshot, idManifest = {}) {
+  const nodes = sceneNodes(snapshot), byId = new Map(nodes.map(n => [n.id, n]));
+  const names = new Map();
+  for (const n of nodes) { const list = names.get(n.name) ?? []; list.push(n); names.set(n.name, list); }
+  const roots = new Map(), batch = [], skipped = [];
+  for (const step of plan.batch ?? []) {
+    const args = { ...(step.args ?? {}) };
+    if (!['frame.create', 'canvas.create-node'].includes(step.action)) { skipped.push({ action: step.action, reason: 'Resume preserves existing mutations; revise explicitly.' }); continue; }
+    const type = step.action === 'frame.create' ? 'frame' : args.type;
+    const pinned = args.id || idManifest[args.name];
+    const matches = names.get(args.name) ?? [];
+    if (!pinned && matches.length > 1) throw new Error(`Ambiguous layer name ${args.name}; use its recorded ID.`);
+    const existing = pinned ? byId.get(pinned) : matches[0];
+    if (existing) {
+      if (existing.type !== type) throw new Error(`Layer ${args.name} has type ${existing.type}, expected ${type}. No automatic replacement.`);
+      roots.set(args.name, existing.id); skipped.push({ id: existing.id, name: args.name, reason: 'Already exists; preserved.' }); continue;
+    }
+    args.id = pinned || `plan-${createHash('sha256').update(`${plan.compositionId}:${args.name}`).digest('hex').slice(0, 24)}`;
+    if (args.parentId && roots.has(args.parentId)) args.parentId = roots.get(args.parentId);
+    roots.set(args.name, args.id);
+    batch.push({ ...step, args });
   }
-  return result;
+  return { compositionId: plan.compositionId, expectedCanvasNodesRev: snapshot.canvasNodesRev, batch, skipped };
 }
 
 export function saveReview(report, prefix) {
@@ -24,7 +73,21 @@ export function saveReview(report, prefix) {
   }
   const bytes = Buffer.from(preview.dataUrl.slice('data:image/png;base64,'.length), 'base64');
   if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) throw new Error('Invalid PNG response');
-  const base = resolve(prefix);
+  if (bytes.length < 45 || bytes.readUInt32BE(8) !== 13 || bytes.subarray(12,16).toString() !== 'IHDR'
+    || !bytes.readUInt32BE(16) || !bytes.readUInt32BE(20)) throw new Error('Invalid PNG response: missing image header/body');
+  let offset = 8, imageData = false, end = false;
+  while (offset + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset), tag = bytes.subarray(offset+4,offset+8).toString();
+    if (offset + length + 12 > bytes.length) throw new Error('Invalid PNG response: truncated image chunk');
+    if (tag === 'IDAT' && length > 0) imageData = true;
+    offset += length + 12;
+    if (tag === 'IEND') { end = length === 0; break; }
+  }
+  if (!imageData || !end) throw new Error('Invalid PNG response: missing image data/end');
+  let base = resolve(prefix);
+  const original = base;
+  let version = 0;
+  while (existsSync(`${base}.png`) || existsSync(`${base}.json`)) base = `${original}-r${report.canvasNodesRev ?? 'unknown'}-${++version}`;
   mkdirSync(dirname(base), { recursive: true });
   const { dataUrl, url, ...metadata } = preview;
   const saved = { ...report, preview: { ...metadata, path: `${base}.png` } };
@@ -34,16 +97,47 @@ export function saveReview(report, prefix) {
   return { png: `${base}.png`, report: `${base}.json`,
     // `fix` = a probable defect remains: fix it, or pass its check/id in `ignore` with a reason.
     // `look` = only things worth a second look. `clean` = nothing mechanical found — NOT "good".
-    verdict: report.verdict ?? 'unknown', blocking: report.blocking,
+    verdict: report.verdict ?? 'unknown', acceptanceStatus: report.acceptanceStatus,
+    acceptedFindings: report.acceptedFindings ?? [], blocking: report.blocking,
     craft: craft.map((f) => `${f.severity} ${f.check}: ${f.detail}`),
+    audit: (report.audit?.violations ?? []).map(v => ({check:v.kind,layer:v.name || v.id,detail:v.detail || v.message || v.reason || `${v.kind} on ${v.name || v.id}`})),
+    scopeWarnings: report.scopeWarnings ?? [],
+    assets: (report.assets ?? []).filter(a => a.status !== 'ready'),
+    typography: (report.typography?.text ?? []).filter(t => t.issue || t.horizontalOverflow > 1 || !t.autoHeight && t.verticalOverflow > 1 || t.exact === false)
+      .map(t => ({layer:t.name || t.id,issue:t.issue,horizontalOverflow:t.horizontalOverflow,verticalOverflow:t.verticalOverflow,
+        requestedFont:t.font?.requestedFamily,requestedWeight:t.font?.requestedWeight,resolvedFile:t.font?.file,exact:t.exact})),
     nodes: report.scope?.nodeCount, findings: report.audit?.total, textChecked: report.typography?.checked,
     textOmitted: report.typography?.omitted, visualReviewRequired: true,
     note: report.verdict === 'fix'
-      ? 'Fix every warn (or justify it with ignore), then review again. Then open the PNG and critique it.'
+      ? 'Fix every warn (or accept an exact finding with a reason), then review changed artboards. Then open the PNG and critique it.'
       : 'Open the PNG with your image-viewing tool, critique it against the studio bar, revise and render again.' };
 }
 
-export function main(argv = process.argv.slice(2)) {
+export async function saveReviewPixels(report, prefix, fetchImage = fetch) {
+  if (report.preview?.dataUrl) return saveReview(report, prefix);
+  const url = report.preview?.url;
+  if (!url || !/^https?:\/\//.test(url)) throw new Error(report.previewError || 'No downloadable preview. Visual verification is incomplete.');
+  const response = await fetchImage(url);
+  if (!response.ok) throw new Error(`Preview download failed (HTTP ${response.status}); request a fresh review.`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  return saveReview({ ...report, preview: { ...report.preview, dataUrl: `data:image/png;base64,${bytes.toString('base64')}` } }, prefix);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  if (argv.includes('--many')) {
+    const args = argv.filter(a => a !== '--many');
+    if (args.length !== 3) throw new Error('Usage: node review.mjs --many <compositionId> <artboard-ids.json> <output-directory>');
+    const [compositionId, manifest, directory] = args;
+    const ids = JSON.parse(readFileSync(manifest, 'utf8'));
+    if (!Array.isArray(ids) || !ids.length) throw new Error('The manifest must be a non-empty artboard ID/name array.');
+    const response = rpc('canvas-act', { compositionId, action: 'canvas.review-many', args: { ids, preview: 'files' } });
+    const reports = response.results?.[0]?.value?.reviews;
+    if (!Array.isArray(reports) || reports.length !== ids.length) throw new Error('Incomplete review-many result; do not claim all artboards passed.');
+    const saved = [];
+    for (let i = 0; i < reports.length; i++) saved.push(await saveReviewPixels(reports[i], resolve(directory, `${String(i + 1).padStart(2, '0')}-${String(ids[i]).replace(/[^a-z0-9_-]/gi, '-')}`)));
+    process.stdout.write(JSON.stringify(saved, null, 2) + '\n');
+    return;
+  }
   const legacy = argv.includes('--perceive');
   const args = argv.filter((a) => a !== '--perceive');
   if (args.length !== 3) throw new Error('Usage: node review.mjs <compositionId> <frame-id-or-name> <output-prefix> [--perceive]\n--perceive: older workers, preview only; pass a frame ID.');
@@ -60,9 +154,9 @@ export function main(argv = process.argv.slice(2)) {
     report = response.results?.[0]?.value;
     if (!report?.scope) throw new Error('canvas.review unavailable. Check canvas-catalog; use --perceive for an explicitly preview-only check on an older worker.');
   }
-  process.stdout.write(JSON.stringify(saveReview(report, prefix), null, 2) + '\n');
+  process.stdout.write(JSON.stringify(await saveReviewPixels(report, prefix), null, 2) + '\n');
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { main(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
 }

package/skills/design-craft/SKILL.md

@@ -298,6 +298,11 @@ fewer elements, tighter type, one accent*. Every ornament added is a step away f
 
 ## Sources
 
+The full shelf — about fifty books across grid, type, print production, colour, graphic form,
+brand identity, information and interface design, each reduced to one rule — is in
+[references.md](references.md). In Research pick two or three whose lens fits the brief, and name
+the one behind each direction in its rationale.
+
 Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981) · Massimo Vignelli, *The
 Vignelli Canon* (semantics / syntactics / pragmatics; "Design is one") · Michael Bierut,
 *How to* (Pentagram; brief → rationale → trade-offs) · Paula Scher / Pentagram, The Public

package/skills/design-craft/references.md

@@ -0,0 +1,95 @@
+# The design shelf
+
+<!-- Generated from apps/cloudflare/src/agent/design-references.ts (the design-references and brand-references house skills).
+     Edit the list there, then run: WRITE_DESIGN_REFERENCES=1 npx vitest run src/__tests__/verify-design-references.test.ts -->
+
+Books a studio designer works from, each reduced to one rule you can act on. The in-app
+assistant gets the same list as the `design-references` and `brand-references` workspace skills.
+
+## How to use it
+
+- In Research, pick two or three references whose lens fits the brief: a print piece or poster → grid, type, print; an identity → brand; a chart or report → information; a screen or flow → interface. Write what each one changes in this design.
+- In Direction, name the reference behind each direction's idea in one line ("a Müller-Brockmann modular grid, type as the image after Scher").
+- In Review, critique against the same rules you chose.
+- These are paraphrased principles, not quotations. Never invent a quote or page number; cite author and title only.
+
+## Method — deciding before drawing
+
+- Massimo Vignelli, *The Vignelli Canon* (2010): Answer semantics (what it means, to whom), syntactics (its visual grammar) and pragmatics (will they get it) before placing a node; few typefaces, a grid, discipline.
+- Michael Bierut, *How to* (2015): Present brief → idea → trade-offs; the idea comes out of the problem, and the rationale is part of the deliverable.
+- Paul Rand, *Thoughts on Design* (1947): Form and content are one: simplify until the idea is legible, and allow wit — play is a way of making it memorable.
+- Bruno Munari, *Design as Art* (1966): Solve the problem with the simplest means; decoration that solves nothing is noise.
+- Karl Gerstner, *Designing Programmes* (1964): Design the rules, not one layout: define the variables (size, position, colour) and generate the set from them.
+- Dieter Rams, *Less but Better* (1995): As little design as possible: every element must earn its place by use; remove what does not.
+- Alan Fletcher, *The Art of Looking Sideways* (2001): Look for the idea sideways — a visual pun or found connection beats a literal illustration of the brief.
+
+## Grid and layout
+
+- Josef Müller-Brockmann, *Grid Systems in Graphic Design* (1981): Construct margins, columns, gutter and baseline first; every element lands on the grid; break it once, on purpose.
+- Timothy Samara, *Making and Breaking the Grid* (2002): Pick the grid for the content (manuscript, column, modular, hierarchical); a deliberate break needs a grid to break.
+- Kimberly Elam, *Geometry of Design* (2001): Place the focal point on a proportional line (golden section, root rectangles, thirds), not at dead centre.
+- Beth Tondreau, *Layout Essentials* (2009): Grids by job: a single column for reading, multi-column for mixed content, modular for catalogues and dashboards.
+
+## Typography
+
+- Robert Bringhurst, *The Elements of Typographic Style* (1992): Measure 45–75 characters, leading to suit the measure, honour the content: type exists to be read.
+- Ellen Lupton, *Thinking with Type* (2004): Build hierarchy by changing one variable at a time — size, weight, colour or space — and track capitals open.
+- Jan Tschichold, *The New Typography* (1928): Asymmetric, functional layout: hierarchy by size, weight and position, never ornament.
+- Emil Ruder, *Typographie* (1967): White space is active form: the counter, the gap and the margin are composed like the type itself.
+- Jost Hochuli, *Detail in Typography* (1987): Letter, word and line spacing decide readability: tighten display type, keep word spaces even, open the leading for long lines.
+- Erik Spiekermann and E. M. Ginger, *Stop Stealing Sheep & Find Out How Type Works* (1993): A typeface is a voice: choose it for the message and audience, then set it with care before anything else.
+- Ellen Lupton, *Type on Screen* (2014): On screen, type is motion and interaction too: sizes, scales and states are a system, not one setting.
+
+## Print and editorial production
+
+- Jan Tschichold, *The Form of the Book*: Classical page proportions: inner margin smallest, foot margin largest; the text block sits high and toward the spine.
+- Richard Hendel, *On Book Design* (1998): A book design serves the reading; decide trim, margins, type and running heads together, and stay invisible.
+- Andrew Haslam, *Book Design* (2006): Plan the whole object — format, grid, pagination, binding — before designing a spread.
+- Jan V. White, *Editing by Design* (1974): Editorial layout starts from what the story says; headline, picture and caption are one unit.
+- International Paper, *Pocket Pal*: Production rules: CMYK for press, 300 dpi images at final size, 3 mm (0.125 in) bleed, a safe area inside the trim.
+- Alan Pipes, *Production for Graphic Designers*: Specify for the press: paper stock, ink coverage, rich black for large areas only, overprint and trap small type.
+
+## Colour
+
+- Josef Albers, *Interaction of Color* (1963): Colour is relative: judge it beside its neighbours on the real ground, never as a swatch alone.
+- Johannes Itten, *The Art of Color* (1961): Choose the one contrast that leads (light–dark, warm–cool, complementary, saturation, extent) and let the rest support it.
+
+## Graphic form and visual perception
+
+- Armin Hofmann, *Graphic Design Manual* (1965): Build with elementary contrasts — point, line, plane, black and white, large and small — before colour.
+- Ellen Lupton and Jennifer Cole Phillips, *Graphic Design: The New Basics* (2008): Point, line, plane, rhythm, scale, texture, figure/ground and framing are variables; change one deliberately.
+- Wucius Wong, *Principles of Two-Dimensional Design* (1972): Repetition, gradation and radiation give a field structure; an anomaly in that structure is the focal point.
+- Rudolf Arnheim, *Art and Visual Perception* (1954): Visual weight balances on the frame's hidden axes; size, value, isolation and position all add weight.
+- Robin Williams, *The Non-Designer's Design Book* (1994): Contrast, repetition, alignment, proximity: if two things differ, make them clearly different.
+- Alex W. White, *The Elements of Graphic Design* (2002): Treat space as an element: emptiness gives the content its shape and its importance.
+- Kenya Hara, *Designing Design* (2007): Emptiness invites the viewer in: leave room for the reader's imagination instead of filling the frame.
+- Paula Scher, *Make It Bigger* (2002): Type can be the image: scale and crop a word until it carries the identity on its own.
+- Philip B. Meggs, *A History of Graphic Design* (1983): Know the lineage of a style so a reference is chosen, not a pastiche of the first thing found.
+- Adrian Frutiger, *Signs and Symbols*: A sign reads by its simplest form; test a mark small, at a distance and in one colour.
+
+## Brand and identity
+
+- Alina Wheeler, *Designing Brand Identity* (2003): Identity is a process — research, strategy, design, touchpoints, asset management; design the touchpoints, not just the logo.
+- Marty Neumeier, *The Brand Gap* (2003): A brand is the customer's gut feeling; close the gap between strategy and the look by testing what people actually perceive.
+- Marty Neumeier, *Zag* (2006): When everyone zigs, zag: state what makes this the only one, then design to that difference.
+- Wally Olins, *On Brand* (2003): A brand shows in product, environment, communication and behaviour; keep all four saying the same thing.
+- Byron Sharp, *How Brands Grow* (2010): Growth comes from being easy to notice and buy: protect distinctive assets and stay consistent.
+- Jenni Romaniuk, *Building Distinctive Brand Assets* (2018): An asset (colour, shape, character) works once it is famous and unique to the brand; use it everywhere, change it rarely.
+- Tom Geismar, Ivan Chermayeff and Sagi Haviv, *Identify* (2011): A mark must be appropriate, distinctive and simple; it earns meaning through use over time.
+- David Airey, *Logo Design Love* (2009): Test a logo at 16 px, in one colour and in reverse; if it needs detail or colour to survive, simplify it.
+- Danne & Blackburn, *NASA Graphics Standards Manual* (1975): A standards manual fixes the mark, clear space, colours, type, grid and applications so anyone can apply the system.
+- Unimark International (Vignelli, Noorda), *New York City Transit Authority Graphics Standards Manual* (1970): A system scales by rules: one typeface, fixed modules, colour coding and consistent placement.
+
+## Information design
+
+- Edward R. Tufte, *The Visual Display of Quantitative Information* (1983): Maximise data-ink: remove chart junk, label directly, show the comparison; use small multiples for change.
+- Edward R. Tufte, *Envisioning Information* (1990): Layer and separate: quiet the grid and background so the data reads first.
+- Otto Neurath, *International Picture Language* (1936): Isotype: count with repeated identical pictograms, never by enlarging one.
+
+## Interface and product design
+
+- Don Norman, *The Design of Everyday Things* (1988): Make the action visible: signifiers, feedback, mapping and constraints; a control must say how it is used.
+- Steve Krug, *Don't Make Me Think* (2000): People scan, they do not read: obvious hierarchy, conventions, one clear next action per page.
+- Adam Wathan and Steve Schoger, *Refactoring UI* (2018): Hierarchy by weight and colour before size, de-emphasise secondary text, use a spacing and shadow scale.
+- Jenifer Tidwell, *Designing Interfaces* (2005): Use the known pattern for the job (navigation, forms, lists, dashboards) before inventing one.
+- William Lidwell, Kritina Holden and Jill Butler, *Universal Principles of Design* (2003): Check the design against named principles (Fitts, Hick, proximity, progressive disclosure) and say which one a choice serves.

package/skills/index.json

@@ -4,7 +4,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "2d33d2ecfb166fa6"
+    "sha": "6233057bd1a44b51"
   },
   {
     "name": "clearly-canvas",
@@ -17,7 +17,7 @@
       "project-plans.md",
       "review.mjs"
     ],
-    "sha": "9b34f0b8326257d0"
+    "sha": "7d79406b37f611a8"
   },
   {
     "name": "agent-home",
@@ -36,9 +36,10 @@
   {
     "name": "design-craft",
     "files": [
-      "SKILL.md"
+      "SKILL.md",
+      "references.md"
     ],
-    "sha": "260c3a6967b08a8b"
+    "sha": "bf2f4fac6f57ea46"
   },
   {
     "name": "layout-systems",
@@ -52,7 +53,7 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "50587f531bfab1c6"
+    "sha": "cd891499599ccb7b"
   },
   {
     "name": "pair-on-canvas",
@@ -81,6 +82,6 @@
     "files": [
       "SKILL.md"
     ],
-    "sha": "9e94e53b90ded575"
+    "sha": "b3f47988cb9235b9"
   }
 ]