name: spotkit description: Generate minimal, abstract, UI-inspired illustrations for software product features — as deterministic SVG. Use when asked for a feature illustration, product illustration, spot illustration, empty-state graphic, feature-card artwork, docs or developer-portal illustration, or a consistent illustration set/family for a product. Also use to turn a feature description or a product screenshot into an abstract UI illustration, to add a new illustration to an existing family, or to retheme an existing set.

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.

1. Interpret the feature. One sentence: what does it actually do? → references/metaphor.md
2. Choose the metaphor. What relationship is this feature about — grouping, connecting, gating, packaging, reviewing, sequencing?
3. Pick 2–5 primitives that carry that relationship. Not more.
4. 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.
5. 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.
6. 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.

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.

What it does

You say:

Create an illustration for API version management.

You get a concept, a metaphor, and a production-ready SVG that looks like it belongs to everything else you've made.

These aren't marketing illustrations. They're abstractions of an interface — what a feature looks like if you keep its most recognisable parts and throw away the other 90%.

Abstract the interface, not the idea.

A good one makes someone think "I understand what this feature does." Never "that's a screenshot of the product."

Install

Claude Code

git clone https://github.com/Devesh-Shirsath/spotkit.git \
  ~/.claude/skills/spotkit

Restart Claude Code and just ask. The skill picks itself up whenever you mention feature illustrations, spot illustrations, empty states, or an illustration set for a product.

Codex

git clone https://github.com/Devesh-Shirsath/spotkit.git \
  ~/.agents/skills/spotkit

Restart Codex, then ask — or call it by name: $spotkit an illustration for audit logs.

Any other agent — clone the repo into your project and ask it to follow SKILL.md. AGENTS.md tells it what to read and what to skip.

Claude.ai — Settings → Capabilities → Skills → upload a zip of this repo. Re-upload it whenever the repo changes; an old upload keeps the old rules.

ChatGPT, or any chat tool — make a Project (or a custom GPT), upload SPEC.md, references/icons.md and references/examples.md to it, and paste the standing instructions below into its instructions. Uploaded files beat links: a chat tool may skim a link, or not open it at all.

Standing instructions

The same rules for every tool, so they all draw the same family:

You make Spotkit illustrations: minimal, abstract SVG product illustrations
that follow SPEC.md exactly.

1. Write SVG code by hand. Never use image generation.
2. Adapt, don't invent. Pick the nearest of the twelve layouts in SPEC.md §7,
   start from its example file, keep its geometry (panel, backdrop, float,
   card sizes and positions) and change only the content: the icon, what sits
   inside the cards, how many rows. Invent a new composition only if none of
   the twelve fits, and say so.
3. Never improvise a value. Every number, colour and snippet comes from
   SPEC.md: one stroke width (0.5), one stroke colour (var(--il-line)), one
   shadow, the fade mask, var(--il-*) colours.
4. Centred on x=80 and square. Few, large elements: nothing that carries
   meaning is smaller than 9 units.
5. Icons are filled Phosphor paths from icons.md. Never draw or stroke a glyph.
6. Before answering, go through SPEC.md §9 and fix whatever fails.

Reply with: feature interpretation, metaphor, which layout it adapts,
primitives, then the SVG.

No dependencies. Python 3 only — to regenerate, or to run check.py.

Try it without installing

Open examples/gallery.html in a browser — twelve illustrations, light and dark, from the same twelve files.

Why SVG and not an image model

This style is pure geometry: hairline strokes, exact radii, repeated placeholder bars, one icon family. Diffusion models are weak at all of it, and weakest at the thing that matters most — twenty illustrations that look like one family.

The model writes the SVG directly instead. The output is exact, themeable, editable, diffable, and identical in treatment across a whole set. A prompt-based fallback is included if you want it anyway.

How it works

your feature description
      ↓
what does it actually do?
      ↓
what relationship is it about?      grouping · connecting · gating
      ↓                             packaging · reviewing · sequencing
2–5 UI primitives that carry it
      ↓
a layout — chosen from the prompt, not from habit
      ↓
SVG, themed by CSS custom properties
      ↓
a quality checklist

Twelve layouts

Picked by meaning and by how many elements the idea needs — never by rotation.

They come from independent choices — where the floating element sits, what it is, how content is arranged, how the panel is framed — so the real space is much larger than twelve.

Monotony is the failure mode of this style. A set where every piece is "header card, then rows" reads as one image twelve times, however clean each one is. The skill budgets layout reuse, caps full-width headers at two per twelve, and checks each illustration against its neighbours.

Theming

Twelve CSS custom properties. One file serves light and dark — never ship two.

:root {
  --il-canvas:  #EDEAE6;   --il-ghost:   #EAE7E2;   --il-panel: #F7F5F2;
  --il-surface: #FFFFFF;   --il-line:    #B9B1A4;   /* every stroke, width 0.5 */
  --il-stroke:  #35322D;   --il-fill:    #DCD6CE;   --il-accent: #3E9077;
}

Change three values, rerun build.py, the whole set rethemes.

Inline the SVG to theme it. CSS custom properties don't cross into <img src="…"> or <object> — those show the fallback palette forever and never follow dark mode. If you must use <img>, use the pre-flattened files in examples/flat/.

If several illustrations share a page, suffix every id in each (fade-teams → fade-teams-1) or their masks and filters cross-apply.

Using these in Figma

Copy the contents of any file in examples/flat/light/ and paste onto a Figma canvas — you get editable vector layers. Use the flat files, not the themed ones; Figma doesn't run CSS either, so a themed file pastes as black shapes.

Figma discards SVG filters on import, so the drop shadow won't come across — re-apply it as a Figma effect on the one floating layer.

Check an illustration

python3 check.py my-feature.svg

Catches the defects that fail silently: a second stroke width or colour, more than one shadow, a background rect, text, unsuffixed ids, a moved fade line. Works on output from any model.

Regenerate

python3 build.py         # rewrites examples/, the gallery and references/icons.md
python3 flatten.py       # rewrites the flat exports and contact sheets
python3 check.py --docs  # fails if any doc disagrees with build.py

Every constant lives in the GEO dict at the top of build.py. Change one and all twelve move together — which is the operation you'll want most, and the one that's most error-prone by hand.

What's in the box

SKILL.md                  entry point and workflow
SPEC.md                   every number, the template, one full example — start here
AGENTS.md                 what an AI agent should read, and skip
references/
  icons.md                paste-ready Phosphor paths (generated)
  examples.md             the twelve layouts as SVG templates, one file (generated)
  metaphor.md             feature → concept, ~24 worked SaaS examples
  archetypes.md           the twelve layouts and the choices behind them
  primitives.md           verified geometry + copy-paste SVG library
  theme.md                tokens, light/dark, accent rules
  scaling.md              96px icon through 720px hero
  screenshots.md          abstracting a real product screenshot
  sets.md                 producing and extending a family
  checklist.md            pre-delivery quality gate
  image-prompt.md         fallback path for image models
assets/illustration.css   drop-in token definitions
examples/                 twelve illustrations, flat exports, contact sheet
build.py · flatten.py     generators — every constant in one place
check.py                  linter for illustrations and for the docs
icons.py                  embedded Phosphor geometry

Known limitations

Worth stating rather than having you discover:

• The metaphor test isn't enforced. The checklist says cover the icon — can a stranger still describe the relationship? Nothing forces a run to apply it. In testing, two prompts in ten produced illustrations that lean on their icon to be legible.
• One style preset. The dial system — elevation, edge treatment, overhang, corner language, stroke weight, icon style, palette, density — is documented, but only one combination ships. A second is additive; nothing in the method changes.
• The 0.5 stroke has a floor. Below roughly 96px display width it drops under half a device pixel and antialiases away. At those sizes, drop the hairlines and let fills carry the composition.
• Figma import loses shadows. See above.

Who it's for

Product and UX designers, frontend developers, SaaS founders, design system and docs teams — anyone who needs feature illustrations, empty-state graphics or a coherent illustration family for a whole product, and doesn't want to dra