Spotkit
Turn a feature description into a quiet, abstract illustration that looks like a
product interface reduced to its most recognizable primitives.
The governing principle:
Abstract the interface, not the idea.
Someone should look at the result and think "I understand what this feature
does" — not "that's a screenshot of the product."
Output format
Default to SVG. This style is pure geometry — hairline borders, exact radii,
repeated placeholder bars, one stroke weight. Writing it directly gives exact,
repeatable output and makes every illustration in a set provably identical in
treatment. Image models fail at precisely these things, and fail hardest at
consistency across a set.
Use references/image-prompt.md only when the user explicitly wants a prompt for
an external image model.
Workflow
Read SPEC.md first. It holds every number, the SVG template, the building
blocks and a complete example — enough to draw from. The references below are
for the decisions; open one only when a step needs it.
- Interpret the feature. One sentence: what does it actually do?
→
references/metaphor.md
- Choose the metaphor. What relationship is this feature about — grouping,
connecting, gating, packaging, reviewing, sequencing?
- Pick 2–5 primitives that carry that relationship. Not more.
- Pick one of the twelve layouts — then adapt it, don't invent.
→
SPEC.md §7. Choose by the relationship, then by how many elements the
idea needs, then by what its neighbour already uses.
- Start from that layout's example file (
SPEC.md §7 names it) and keep
its geometry: panel, backdrop, float, card sizes and positions. Change only
the content — the icon, what sits inside the cards, how many rows within the
layout's limit. Icon paths come from references/icons.md. If you can run
Python here, copy the layout's function in build.py and edit its content.
- Check it. Run
python3 check.py your.svg if you can, then the list in
SPEC.md §9. Simplify what they flag.
If the concept is genuinely ambiguous, offer 2–3 conceptual directions before
drawing — different metaphors, never different styling.
The standing rule: adapt, don't invent
Composition is where models drift. Given the same brief, one run that adapted
the Split layout produced something that sat in the family at a glance; another
that invented a new arrangement produced a busier, off-centre piece that didn't —
and the same brief in a different tool drifted further still. The twelve
layouts have been balanced against each other; a fresh composition has not.
So, every time, in every tool:
- Adapt the nearest layout. Its geometry is fixed; its content is yours.
Invent a new composition only when none of the twelve can carry the
relationship — and say so in the delivery note, naming the rule that forced it.
- Centred and square. Weight on x=80, filling the 160 square. A landscape
strip with empty space above and below is not a spot illustration.
- Few, large elements. Nothing that carries meaning is smaller than 9 units
— that is 9 pixels at display size. If an idea needs more detail than that, it
needs fewer elements, not smaller ones.
- Show change as states. A flow reads fastest as before → after: two cards
and an arrow (L12), or one rail (L11). Not a rail and cards and a badge.
- Never improvise a value. Every number, colour and snippet comes from
SPEC.md. If a value you need is not there, reuse the nearest one that is.
What is fixed and what is yours
The skill separates the method from the look.
Fixed — these hold for any illustration in this genre:
- Abstract the interface, not the idea
- Text-independence — it must read with every label removed
- One dominant visual idea per illustration
- ~20–40% of real UI fidelity
- Legible depth hierarchy, however it is achieved
- Whitespace as structure, not leftover space
- Restraint: few icons, few colors, one interaction cue
- Internal consistency across a set
Yours — set once per project, then inherited by the whole family:
elevation model · edge treatment · overhang · corner language · stroke weight ·
icon style · palette · accent · density
A coherent combination of those is a style spec. One ships today — soft
shadow, fade-out edge, overhanging float, generous radii, hairline strokes,
monoline icons, warm grayscale, optional single accent, sparse density — and it
is what assets/ and examples/ implement. Additional directions are additive;
nothing in the method changes when one is added.
Invariants of the shipped spec
- One base panel, sized to its content. Not a fixed box — a timeline gets a
narrow frame, a table of rows a wide one. Its edge either fades (open bottom:
there is more) or is contained (closed: this is all of it). Choose by
meaning.
- One thing carries the shadow. Usually a floating element breaking past
the panel's edges; sometimes a raised row or the middle card of a fan. (The
corner-chip layout's diagonal pair counts as one.)
- The elevation goes on the record being acted on, not on a decorative circle
above it. When a medallion sits over a prominent first row, the row floats and
the medallion stays flat.
- Placeholder bars, never words, always short-over-long, never equal widths.
- A backdrop is optional and varied — none, a plate, an offset sheet, or a
twin stack. The same plate behind every illustration is what makes a set look
mechanical.
- One stroke width and one stroke colour, everywhere. Width 0.5,
--il-line.
Hierarchy comes from fills, opacity and elevation — never line weight.
Separators are filled hairlines, not strokes.
- Equal top and bottom padding inside every card, bottom never zero. This
fails silently more than anything else here — verify it by arithmetic.
- The panel sits above its backdrop, and no two sheets share a top edge.
- Nothing overlaps what it sits between. A glyph in a gap fits inside it
with clearance; a rail is capped by its first node.
build.py has guards
(fits, rail, padded) that raise rather than ship these — use them.
- One icon family, one radius language, one shadow across the entire set.
- Every card carries a hairline, not just a shadow — at 160px there is no text
to hold the hierarchy, so the surfaces have to, and a shadow alone does not
separate white on near-white.
- The last content block sits inside the fade and half-dissolves. That
half-visible row says "and more" without adding anything. Equally: nothing
important may land below
y=112, or it dissolves mid-content.
- Vary the layout, never the language. Monotony is the failure mode of this
style — a set where every piece is "header card, then rows" reads as one image
twelve times. See
archetypes.md.
Two things that will bite you
- Icons are Phosphor
regular, filled, on a 256 grid. Set fill, never
stroke. Bold reads heavy against 0.5-unit structural strokes. Paste the
paths from references/icons.md; never draw a glyph yourself.
- CSS custom properties do not cross into
<img> or <object>. An SVG
loaded that way shows fallback colors forever and will not follow dark mode.
Inline the markup to theme it — and suffix every id when you do, or masks
and filters cross-apply between illustrations.
Reference files
Read the one you need; don't load them all.
| File | Read it when |
|---|
SPEC.md | Always, first. Every number, the template, one full example. |
references/examples.md | You picked a layout — its finished SVG, to adapt. |
references/icons.md | You need an icon — paste-ready Phosphor paths. |
references/metaphor.md | Translating a feature into a concept. Catalog of ~24 common SaaS features. |
references/archetypes.md | Choosing a layout. Twelve compositions and the four choices that generate them. |
references/primitives.md | You need the reasoning behind a building block. |
references/theme.md | Colors, tokens, light/dark, accent rules, deriving your own palette. |
references/scaling.md | Any canvas that is not a ~160px square. |
references/screenshots.md | The user supplied a screenshot of the real UI. |
references/sets.md | Producing or extending a family. |
references/checklist.md | Before delivering. Always. |
references/image-prompt.md | The user explicitly wants an image-model prompt. |
Delivering
The minimum useful answer is a short concept note plus the SVG:
Feature interpretation — one line.
Metaphor — one line.
Primitives — the 2–5 used.
The SVG.
Don't pad it with explanation the user didn't ask for.
Assets
assets/illustration.css — token definitions, light and dark. Drop into a site.examples/ — twelve exemplars, one per layout.
Open examples/gallery.html for the contact sheet in both themes.icons.py — embedded Phosphor geometry (regular is what the system uses;
bold is kept for anyone who wants a heavier variant).check.py — lints an SVG against the rules that fail silently
(python3 check.py file.svg), and the docs against build.py (--docs).build.py — the generator that produced them. Every constant in one place;
change one and the whole family moves together. Worth copying for any set
larger than about eight.