Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions evals/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Cold-run briefs

Twelve briefs that show what the downloadable skill produces for someone who has never seen this repository. Run them after any change to `skills/plotter`, then compare the drawings with the previous run and with the catalogue.
Seventeen briefs that show what the downloadable skill produces for someone who has never seen this repository. Run them after any change to `skills/plotter`, then compare the drawings with the previous run and with the catalogue.

```sh
bun run downloads # rebuild the archive under test
Expand All @@ -11,13 +11,15 @@ evals/run.sh claude sonnet 07 # one brief, by number

Each brief runs in its own fresh session in a temporary folder outside this checkout, printed when the run ends; set `PLOTTER_EVAL_OUT` to choose another. A session started inside the checkout would read this repository’s `AGENTS.md` and stop being a clean install. The session's files are the deliverables; `transcript.jsonl` records what the agent read, ran, and reported.

| Briefs | What they test |
| ------ | -------------------------------------------------------------------------------------- |
| 01–03 | README briefs. Each describes a catalogue drawing, so they mostly test retrieval. |
| 04–05 | Open briefs. The agent should stop and offer three options. |
| 06–10 | Plain-language subjects with no catalogue match, including a small size and TSX. |
| 11 | Animating a supplied drawing into one self-contained HTML file. |
| 12 | Critique. `upload-card.svg` has eight planted faults, listed below; none may be fixed. |
| Briefs | What they test |
| ------ | ------------------------------------------------------------------------------------------------------ |
| 01–03 | README briefs. Each describes a catalogue drawing, so they mostly test retrieval. |
| 04–05 | Open briefs. The agent should stop and offer three options. |
| 06–10 | Plain-language subjects, including a small size and TSX. |
| 11 | Animating a supplied drawing into one self-contained HTML file. |
| 12 | Critique. `upload-card.svg` has eight planted faults, listed below; none may be fixed. |
| 13–16 | Small placements and feature subjects. No pictogram as the main form; a compact version, not a redraw. |
| 17 | “Draw a magnifying glass.” The object is the brief, so a large constructed magnifier is correct here. |

Planted faults in `attachments/upload-card.svg`: a gradient and drop shadow on the card; a skewed icon; hatching that leaves its region; a 240-unit span labelled 200; a dashed arrowhead on an arrow used for alignment; a heavy unexplained grid with every stroke at full weight; a letter-spaced bold title with straight quotes and a hyphen; a rule through the title.

Expand Down
1 change: 1 addition & 0 deletions evals/briefs/13-empty-notifications-small.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Empty state for the notifications panel when there is nothing new. It shows at 200px wide. SVG.
1 change: 1 addition & 0 deletions evals/briefs/14-empty-payment-small.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Small illustration for a “no payment methods yet” card, about 240px wide. SVG.
1 change: 1 addition & 0 deletions evals/briefs/15-404-card-small.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
404 illustration for a 320px-wide card. SVG.
1 change: 1 addition & 0 deletions evals/briefs/16-search-hero.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Illustration for our search feature page hero.
1 change: 1 addition & 0 deletions evals/briefs/17-object-magnifier.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Draw a magnifying glass.
Binary file modified public/plotter/downloads/plotter.zip
Binary file not shown.
19 changes: 19 additions & 0 deletions scripts/check-plotter.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,25 @@ if (fontCopies[0] !== fontCopies[1]) {
throw new Error("The skill's bundled Cal Sans differs from the website's.");
}
statSync(resolve(skillRoot, "assets/fonts/OFL.txt"));
// The drawing checker must accept every current catalogue and grammar drawing.
const checked = Bun.spawnSync([
"python3",
resolve(skillRoot, "scripts/check.py"),
...["references/catalogue", "references/grammar"].flatMap((folder) =>
readdirSync(resolve(skillRoot, folder))
.filter((file) => file.endsWith(".svg"))
.map((file) => resolve(skillRoot, folder, file)),
),
]);
if (checked.exitCode !== 0) {
throw new Error(
`scripts/check.py rejects a bundled drawing:\n${checked.stdout
.toString()
.split("\n")
.filter((line) => line.includes(": error"))
.join("\n")}`,
);
}
const bundled = readdirSync(catalogueRoot).filter((file) =>
file.endsWith(".svg"),
);
Expand Down
1 change: 1 addition & 0 deletions skills/plotter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Seven bundled SVG anchors support construction-reference selection, and the [cat
| Static registration, using the shared arrow/dimension helpers | `node assets/examples/registration.mjs > registration.svg` |
| Resolved static SVG with editable labels | `python3 scripts/export-svg.py registration.svg registration-export.svg --id-prefix registration` |
| PNG preview for inspection, light and dark | `python3 scripts/render.py registration-export.svg --theme both` |
| Rule check: text, strokes, canvas, and sparseness | `python3 scripts/check.py registration-export.svg` |
| Animation and static fallback, with shared role CSS | Open `assets/examples/assembly-motion.html` in a modern browser; keep `assets/foundation/roles.css` in place. |

Node.js is needed for the authoring example; Python 3 is needed for the static exporter and the preview renderer. The renderer uses an installed Chromium-based browser such as Chrome, Edge, or Brave, and falls back to `rsvg-convert`, `resvg`, Inkscape, ImageMagick, or macOS Quick Look. Recipients opening a resolved SVG need neither. The motion example uses browser SVG animation and a small player without a build or server. Keep its local stylesheet alongside it, or inline that generated stylesheet when delivering one HTML file. Cal Sans is bundled under the SIL Open Font License at `assets/fonts/`: previews render with it, and `export-svg.py --embed-font` carries it inside a standalone SVG. Without it on the host, labels fall back to sans-serif.
Expand Down
67 changes: 64 additions & 3 deletions skills/plotter/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,49 @@
---
name: plotter
description: Create, critique, refine, or animate editable flat monochrome blueprint illustrations. Use for construction studies, conceptual diagrams, technical heroes, and empty states in this visual language, including requests to animate an existing Plotter drawing. Not general interface animation or engineering certification.
description: Draw, critique, refine, or animate flat monochrome blueprint illustrations as editable SVG — thin technical line drawings that explain an idea through one construction relationship. Use when the user wants an illustration, hero image, spot illustration, empty-state or 404 image, or an explanatory drawing for docs, a landing page, a feature page, or a README in a blueprint, technical-drawing, schematic, or line-art style; when they name Plotter or a catalogue code such as TIM-05; or when they ask to animate or review a Plotter drawing. Not for data charts, flowcharts in Mermaid or similar tools, icon sets, photorealistic or isometric art, general interface animation, or engineering certification.
---

# Plotter

Make one construction relationship carry the idea: alignment, proportion, assembly, routing, tangency, or intersection. Deliver editable vectors; animation adds behavior to a readable static composition.

## Hard rules

These hold for every drawing, option sheet, and animation frame. The references explain them; they do not relax them.

1. **One relationship, named before drawing.** State it in a sentence: what aligns, fits, overlaps, or is missing. A subject such as “agents” is not yet a composition, and marks added to a subject without a relationship are decoration.
2. **An object is never a sign for an idea.** A magnifier for search, a bell for notifications, a gear for settings: a conventional icon names the concept and explains nothing, with or without drafting marks around it. For a concept, draw the structure it works on and what happens to that structure, such as an ordered index with one position unfilled. Draw an object as the main form only when the brief is that object and the drawing shows how its shape is built. A glyph may sit inside a UI fragment at its real size, as a magnifier does inside a search field.
3. **A small size never changes the canvas or the language.** Compose at `560 × 440` whatever the display size, then derive a [compact version](references/drawing.md#small-placements) from the same geometry. Redrawing the idea on a small canvas produces an icon.
4. **Flat only.** Plan, elevation, or a conceptual plane. Never perspective, isometric depth, skew, gradients, shadows, or lighting: depth cues turn a construction into a rendering.
5. **Transparent forms.** Shapes are `fill="none"`. The one exception is a translucent highlight on a named selection, intersection, or result, painted once. A drawing has to read on any page color, and an opaque patch hides what crosses it.
6. **One ink, one weight.** Draw in `currentColor` with 1-unit strokes. Opacity sets the hierarchy and a dash pattern carries a meaning; never thicken a line for emphasis.
7. **Main form first.** The main form reads first, construction second, sparse dimensions and labels third. The drawing must still read with every supporting mark removed.
8. **Every mark earns its place.** Name the relationship each guide, arrow, hatch, grid, or dimension explains. If removing it leaves that relationship equally clear, remove it.
9. **Dimensions tell the truth.** Derive a label and its witnesses from the same geometry. A label that disagrees with the span it measures is an error.
10. **Arrows mean change.** Use one only for movement or direction, with a solid head even on a dashed shaft. Alignment and equal size use projections or dimensions.
11. **Every label looks the same: small, regular, and quiet.** Editable `<text>` in `Cal Sans, sans-serif` at weight 400 and 10 to 12 units, at 0.72 ink for names and 0.5 for values and notes, with `stroke="none"`: text inherits the drawing’s stroke unless you turn it off, and stroked letters read as bold. No label is ever bold, larger, full ink, all caps, letter-spaced, italic, or upside down, whatever it names. Use typeset punctuation (’ – − “ ”). No title block or sheet number inside the drawing: the host page supplies those.
12. **One owner per edge, hatch inside its region.** Draw each coincident segment once, and clip hatching to the bounded region it identifies.
13. **Check and look before delivering.** Run `python3 scripts/check.py drawing.svg` and fix every error it reports. Then render, inspect, and do both again after the last edit. Without a render, say the visual review is pending.

## Numbers

Lengths are SVG units on a `560 × 440` canvas.

<!-- BEGIN GENERATED: numbers -->
- Every stroke is **1** unit wide.
- Opacity: **1** primary form, section cut; **0.32** secondary form, dimension, leader, transfer, hidden, absent, or proposed outline; **0.18** hatch; **0.14** reference guide, centerline; **0.06** grid.
- Region highlight: `fill-opacity` **0.055**.
- Dashes: `8 3 1 3` centerline; `3 5` hidden, absent, or proposed; `4 6` movement or transfer. Everything else is continuous.
- Arrowhead: two solid **6**-unit legs at **45°**, meeting the shaft’s last dash at the tip.
- Dimension: **8**-unit slashes; at least **3** units clear around every label’s glyphs.
- Hatch: **12**-unit pitch along an edge, at −45°.
<!-- END GENERATED: numbers -->

- Text is **10–12** units at weight **400**, filled and unstroked, at **0.72** ink for names and **0.5** for values and notes, as in every catalogue drawing.
- A guide that does not connect to a contour stops **8** units short of it.

These are the defaults behind the role tokens. In the editable source, apply them with `data-plotter-role` and the generated stylesheet, as the [foundation](references/foundation.md) describes, so the user can retheme the drawing; literal values belong in the resolved export.

## Choose the workflow

Resolve this skill’s installed directory first. All links below are relative to it. The complete folder includes visual references, helper implementation, examples, and render and export tools; standalone work needs no website checkout or prior conversation.
Expand All @@ -23,7 +60,7 @@ Resolve this skill’s installed directory first. All links below are relative t

For drawing, critique, or animation:

1. Read [current direction](references/direction.md) and the [approved reference index](references/approved-references.md). Select and inspect the closest **bundled SVG** by its construction relationship. When the brief names a catalogue code such as `TIM-06`, also open that drawing from the [catalogue](references/catalogue/index.md); it is an example of a relationship, not a style reference.
1. Read [current direction](references/direction.md) and the [approved reference index](references/approved-references.md). Select and inspect the closest **bundled SVG** by its construction relationship. Then search the [catalogue index](references/catalogue/index.md), which gives each of its drawings one line, for the brief’s subject: search, schedule, upload, 404, and so on. When a catalogue drawing already covers the subject, or the brief names a code such as `TIM-06`, open that SVG and start from its relationship. It shows how this subject has been solved, not a layout to copy.
2. Read the [visual grammar](references/visual-grammar.md) to choose meaningful marks. Inspect the linked teaching SVG for each mark you add or revise. Existing unchanged marks do not require loading every teaching example.
3. Read the [drafting standard](references/drafting-standard.md): scope, stroke palette, and geometry/dimensions; include hatch grammar when hatching is involved and symbols/topology when making connectivity or product-behavior claims.

Expand All @@ -36,8 +73,32 @@ Load additional material only for its branch:
| Writing role-based SVG, using arrow/dimension/hatch helpers, overriding tokens, or exporting | [Portable foundation](references/foundation.md), including its supported cases and examples |
| Explicitly asked for technical verification | [Verification prompt](references/verification-prompt.md), supplied with current source and renders |

## Faults to catch

Each of these appeared in drawings made from this skill. Check the render for them before delivering.

- A dimension, guide, or leader running through a label, including the dimension’s own value. Split the line around the text or move the label.
- Labels touching each other or a contour.
- A dimension on every part. Keep the two or three that explain the construction; a full chain of measurements buries the relationship.
- An object standing in for a concept, such as a magnifier for search or a bell for notifications, however carefully it is constructed.
- A small display size answered with a new small canvas, thick strokes, and icon shapes instead of the compact version.
- A subject the catalogue already covers, drawn without opening that drawing.
- The composition pushed against one edge of the canvas, or the focal form off-center without a reason.
- Text that inherits the drawing’s stroke and reads bold, or any label that is bold, oversized, full ink, all caps, or upside down.
- A title block or a sheet number.
- A shape or object study that is only an outline and a dimension, with none of the geometry that builds it.
- One highlight painted on two shapes, so the overlap reads twice.
- An edit made after the last render.

## Finish the requested artifact

Use the selected workflow's completion criteria. Save deliverables where the user is working, not in a temporary folder, and give their paths. Deliver the editable source, the requested preview/export, and a concise account of the relationship, relevant limitations, and what was actually inspected. If rendering or interaction was unavailable, identify that gap instead of claiming visual or motion verification. Honor the requested verification scope; automated checks and tests are not prerequisites when the user excludes them.

Write that account for someone who has not seen this package. Name a borrowed drawing by its title and what you took from it; a bare catalogue code or the word “approved” tells them nothing.
Write the report for someone who has not seen this package, in this order, and keep it under about 150 words. A critique may run longer.

1. **Files:** each deliverable’s path.
2. **What it shows:** the relationship in one or two sentences. Name a borrowed drawing by its title and what you took from it; a bare catalogue code or the word “approved” tells the reader nothing.
3. **Checked:** what you rendered and looked at, with sizes and themes.
4. **Not checked:** what remains unverified, and any assumption the reader should confirm.

When offering options, list them after the files and end with the question. For a critique, give the verdict first, then the faults ranked by how much they hurt, each with where it is and the fix.
Loading
Loading