spotkit
Spotkit — a Claude Code skill that turns a feature description into minimal, abstract SVG product illustrations that all belong to one design system.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/devesh-shirsath--spotkit)HTML
<a href="/listings/devesh-shirsath--spotkit"><img src="/api/listings/devesh-shirsath--spotkit/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**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`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 190 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- 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.
- | 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.
README.md · README · 286 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <h1 align="center">Spotkit</h1>
- <p align="center">
- A Claude Code skill that turns a feature description into a clean, abstract
- product illustration — as real SVG, not a picture of one.
- </p>
- <p align="center">
- <img src="examples/contact-light.svg" alt="Twelve illustrations in light mode: teams, categories, workspace access, documentation, connectors, contributors, notifications, API gateway, roles and access, audit log, app approval, invoices">
- </p>
- <p align="center">
- <img src="examples/contact-dark.svg" alt="The same twelve illustrations rendered in dark mode">
- </p>
- <p align="center">
- <sub>Twelve features, twelve layouts, one set of rules —<br>
- and the same twelve files in both themes, from twelve CSS variables.</sub>
- </p>
- ---
- ## 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**
- ```bash
- 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**
- ```bash
- 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:
- ```text
- 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`](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.
- | Layout | Reads as |
- |---|---|
- | Header + rows | many of one thing |
- | Cascade | a group, receding |
- | Tab bar | one option chosen from several |
- | Toolbar | tools and the people using them |
- | Corner chips | a thing with parts attached |
- | Window | a real surface, more off-screen |
- | Fanned | a set with one chosen |
- | Notifications | events arriving |
- | Constellation | systems converging |
- | Matrix | who can do what |
- | Timeline | sequence, newest first |
- | Split | moving through stages |
- 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.
- ```css
- :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/`](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/`](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
- ```bash
- 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
- ```bash
- 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 draw twenty
- of them by hand.
- ## Author
- Spotkit was built by **[Devesh Shirsath](https://deveshshirsath.com)**, a product
- designer working on developer tools and API documentation.
- [Portfolio](https://deveshshirsath.com) ·
- [LinkedIn](https://www.linkedin.com/in/devesh-shirsath-644625172/) ·
- [GitHub](https://github.com/Devesh-Shirsath) ·
- [Instagram](https://www.instagram.com/devesh.vs/)
- ## Credits
- Icons are [Phosphor](https://phosphoricons.com) (MIT), regular weight — filled
- paths on a 256 grid, so `fill` them rather than stroking.
- The shipped style was derived by measuring a real production illustration family,
- rebuilding it from first principles, and verifying by rendering and comparison.
- Aesthetic direction was informed by contemporary bento-grid layouts. Your own
- direction can differ on every visual dial — the method is what transfers.
- MIT licensed. Contributions welcome, especially new layouts and new style presets.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.