Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/devesh-shirsath--spotkit/badge.svg)](/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

i

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)

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

  1. <h1 align="center">Spotkit</h1>
  2. <p align="center">
  3. A Claude Code skill that turns a feature description into a clean, abstract
  4. product illustration — as real SVG, not a picture of one.
  5. </p>
  6. <p align="center">
  7. <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">
  8. </p>
  9. <p align="center">
  10. <img src="examples/contact-dark.svg" alt="The same twelve illustrations rendered in dark mode">
  11. </p>
  12. <p align="center">
  13. <sub>Twelve features, twelve layouts, one set of rules —<br>
  14. and the same twelve files in both themes, from twelve CSS variables.</sub>
  15. </p>
  16. ---
  17. ## What it does
  18. You say:
  19. > Create an illustration for API version management.
  20. You get a concept, a metaphor, and a production-ready SVG that looks like it
  21. belongs to everything else you've made.
  22. These aren't marketing illustrations. They're abstractions of an **interface** —
  23. what a feature looks like if you keep its most recognisable parts and throw away
  24. the other 90%.
  25. > **Abstract the interface, not the idea.**
  26. A good one makes someone think *"I understand what this feature does."* Never
  27. *"that's a screenshot of the product."*
  28. ## Install
  29. **Claude Code**
  30. ```bash
  31. git clone https://github.com/Devesh-Shirsath/spotkit.git \
  32. ~/.claude/skills/spotkit
  33. ```
  34. Restart Claude Code and just ask. The skill picks itself up whenever you mention
  35. feature illustrations, spot illustrations, empty states, or an illustration set
  36. for a product.
  37. **Codex**
  38. ```bash
  39. git clone https://github.com/Devesh-Shirsath/spotkit.git \
  40. ~/.agents/skills/spotkit
  41. ```
  42. Restart Codex, then ask — or call it by name: `$spotkit an illustration for audit logs`.
  43. **Any other agent** — clone the repo into your project and ask it to follow
  44. `SKILL.md`. `AGENTS.md` tells it what to read and what to skip.
  45. **Claude.ai** — Settings → Capabilities → Skills → upload a zip of this repo.
  46. Re-upload it whenever the repo changes; an old upload keeps the old rules.
  47. **ChatGPT, or any chat tool** — make a Project (or a custom GPT), upload
  48. `SPEC.md`, `references/icons.md` and `references/examples.md` to it, and paste
  49. the standing instructions below into its instructions. Uploaded files beat
  50. links: a chat tool may skim a link, or not open it at all.
  51. ### Standing instructions
  52. The same rules for every tool, so they all draw the same family:
  53. ```text
  54. You make Spotkit illustrations: minimal, abstract SVG product illustrations
  55. that follow SPEC.md exactly.
  56. 1. Write SVG code by hand. Never use image generation.
  57. 2. Adapt, don't invent. Pick the nearest of the twelve layouts in SPEC.md §7,
  58. start from its example file, keep its geometry (panel, backdrop, float,
  59. card sizes and positions) and change only the content: the icon, what sits
  60. inside the cards, how many rows. Invent a new composition only if none of
  61. the twelve fits, and say so.
  62. 3. Never improvise a value. Every number, colour and snippet comes from
  63. SPEC.md: one stroke width (0.5), one stroke colour (var(--il-line)), one
  64. shadow, the fade mask, var(--il-*) colours.
  65. 4. Centred on x=80 and square. Few, large elements: nothing that carries
  66. meaning is smaller than 9 units.
  67. 5. Icons are filled Phosphor paths from icons.md. Never draw or stroke a glyph.
  68. 6. Before answering, go through SPEC.md §9 and fix whatever fails.
  69. Reply with: feature interpretation, metaphor, which layout it adapts,
  70. primitives, then the SVG.
  71. ```
  72. **No dependencies.** Python 3 only — to regenerate, or to run `check.py`.
  73. ## Try it without installing
  74. Open [`examples/gallery.html`](examples/gallery.html) in a browser — twelve
  75. illustrations, light and dark, from the same twelve files.
  76. ## Why SVG and not an image model
  77. This style is pure geometry: hairline strokes, exact radii, repeated placeholder
  78. bars, one icon family. Diffusion models are weak at all of it, and weakest at the
  79. thing that matters most — **twenty illustrations that look like one family.**
  80. The model writes the SVG directly instead. The output is exact, themeable, editable,
  81. diffable, and identical in treatment across a whole set. A prompt-based fallback
  82. is included if you want it anyway.
  83. ## How it works
  84. ```
  85. your feature description
  86. ↓
  87. what does it actually do?
  88. ↓
  89. what relationship is it about? grouping · connecting · gating
  90. ↓ packaging · reviewing · sequencing
  91. 2–5 UI primitives that carry it
  92. ↓
  93. a layout — chosen from the prompt, not from habit
  94. ↓
  95. SVG, themed by CSS custom properties
  96. ↓
  97. a quality checklist
  98. ```
  99. ### Twelve layouts
  100. Picked by **meaning** and by how many elements the idea needs — never by rotation.
  101. | Layout | Reads as |
  102. |---|---|
  103. | Header + rows | many of one thing |
  104. | Cascade | a group, receding |
  105. | Tab bar | one option chosen from several |
  106. | Toolbar | tools and the people using them |
  107. | Corner chips | a thing with parts attached |
  108. | Window | a real surface, more off-screen |
  109. | Fanned | a set with one chosen |
  110. | Notifications | events arriving |
  111. | Constellation | systems converging |
  112. | Matrix | who can do what |
  113. | Timeline | sequence, newest first |
  114. | Split | moving through stages |
  115. They come from independent choices — where the floating element sits, what it is,
  116. how content is arranged, how the panel is framed — so the real space is much
  117. larger than twelve.
  118. **Monotony is the failure mode of this style.** A set where every piece is
  119. "header card, then rows" reads as one image twelve times, however clean each one
  120. is. The skill budgets layout reuse, caps full-width headers at two per twelve,
  121. and checks each illustration against its neighbours.
  122. ## Theming
  123. Twelve CSS custom properties. **One file serves light and dark** — never ship two.
  124. ```css
  125. :root {
  126. --il-canvas: #EDEAE6; --il-ghost: #EAE7E2; --il-panel: #F7F5F2;
  127. --il-surface: #FFFFFF; --il-line: #B9B1A4; /* every stroke, width 0.5 */
  128. --il-stroke: #35322D; --il-fill: #DCD6CE; --il-accent: #3E9077;
  129. }
  130. ```
  131. Change three values, rerun `build.py`, the whole set rethemes.
  132. > **Inline the SVG to theme it.** CSS custom properties don't cross into
  133. > `<img src="…">` or `<object>` — those show the fallback palette forever and
  134. > never follow dark mode. If you must use `<img>`, use the pre-flattened files in
  135. > [`examples/flat/`](examples/flat).
  136. If several illustrations share a page, suffix every `id` in each
  137. (`fade-teams` → `fade-teams-1`) or their masks and filters cross-apply.
  138. ## Using these in Figma
  139. Copy the contents of any file in [`examples/flat/light/`](examples/flat/light)
  140. and paste onto a Figma canvas — you get editable vector layers. Use the flat
  141. files, not the themed ones; Figma doesn't run CSS either, so a themed file pastes
  142. as black shapes.
  143. Figma discards SVG filters on import, so the drop shadow won't come across —
  144. re-apply it as a Figma effect on the one floating layer.
  145. ## Check an illustration
  146. ```bash
  147. python3 check.py my-feature.svg
  148. ```
  149. Catches the defects that fail silently: a second stroke width or colour, more
  150. than one shadow, a background rect, text, unsuffixed ids, a moved fade line.
  151. Works on output from any model.
  152. ## Regenerate
  153. ```bash
  154. python3 build.py # rewrites examples/, the gallery and references/icons.md
  155. python3 flatten.py # rewrites the flat exports and contact sheets
  156. python3 check.py --docs # fails if any doc disagrees with build.py
  157. ```
  158. Every constant lives in the `GEO` dict at the top of `build.py`. Change one and
  159. all twelve move together — which is the operation you'll want most, and the one
  160. that's most error-prone by hand.
  161. ## What's in the box
  162. ```
  163. SKILL.md entry point and workflow
  164. SPEC.md every number, the template, one full example — start here
  165. AGENTS.md what an AI agent should read, and skip
  166. references/
  167. icons.md paste-ready Phosphor paths (generated)
  168. examples.md the twelve layouts as SVG templates, one file (generated)
  169. metaphor.md feature → concept, ~24 worked SaaS examples
  170. archetypes.md the twelve layouts and the choices behind them
  171. primitives.md verified geometry + copy-paste SVG library
  172. theme.md tokens, light/dark, accent rules
  173. scaling.md 96px icon through 720px hero
  174. screenshots.md abstracting a real product screenshot
  175. sets.md producing and extending a family
  176. checklist.md pre-delivery quality gate
  177. image-prompt.md fallback path for image models
  178. assets/illustration.css drop-in token definitions
  179. examples/ twelve illustrations, flat exports, contact sheet
  180. build.py · flatten.py generators — every constant in one place
  181. check.py linter for illustrations and for the docs
  182. icons.py embedded Phosphor geometry
  183. ```
  184. ## Known limitations
  185. Worth stating rather than having you discover:
  186. - **The metaphor test isn't enforced.** The checklist says *cover the icon — can
  187. a stranger still describe the relationship?* Nothing forces a run to apply it.
  188. In testing, two prompts in ten produced illustrations that lean on their icon
  189. to be legible.
  190. - **One style preset.** The dial system — elevation, edge treatment, overhang,
  191. corner language, stroke weight, icon style, palette, density — is documented,
  192. but only one combination ships. A second is additive; nothing in the method
  193. changes.
  194. - **The 0.5 stroke has a floor.** Below roughly 96px display width it drops under
  195. half a device pixel and antialiases away. At those sizes, drop the hairlines
  196. and let fills carry the composition.
  197. - **Figma import loses shadows.** See above.
  198. ## Who it's for
  199. Product and UX designers, frontend developers, SaaS founders, design system and
  200. docs teams — anyone who needs feature illustrations, empty-state graphics or a
  201. coherent illustration family for a whole product, and doesn't want to draw twenty
  202. of them by hand.
  203. ## Author
  204. Spotkit was built by **[Devesh Shirsath](https://deveshshirsath.com)**, a product
  205. designer working on developer tools and API documentation.
  206. [Portfolio](https://deveshshirsath.com) ·
  207. [LinkedIn](https://www.linkedin.com/in/devesh-shirsath-644625172/) ·
  208. [GitHub](https://github.com/Devesh-Shirsath) ·
  209. [Instagram](https://www.instagram.com/devesh.vs/)
  210. ## Credits
  211. Icons are [Phosphor](https://phosphoricons.com) (MIT), regular weight — filled
  212. paths on a 256 grid, so `fill` them rather than stroking.
  213. The shipped style was derived by measuring a real production illustration family,
  214. rebuilding it from first principles, and verifying by rendering and comparison.
  215. Aesthetic direction was informed by contemporary bento-grid layouts. Your own
  216. direction can differ on every visual dial — the method is what transfers.
  217. MIT licensed. Contributions welcome, especially new layouts and new style presets.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.