lucide-style-icons
Skill661 starsChanged 8 days agoMITView on GitHub
Design original SVG icons that match the Lucide icon set used across the Argos frontend — grid, stroke and corner conventions, createLucideIcon wiring, Storybook documentation, 16px verification. Use when a concept has no fitting Lucide icon and needs a custom one, or when reviewing/adjusting the existing custom icons.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- argos-cliSkill
- argos-pr-reviewSkill
- argos-uploadSkill
- frontend-designSkill
- security-auditSkill
- upgrade-depsSkill
- vercel-react-best-practicesSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Search https://lucide.dev/icons/ (or grep the export list in node_modules/lucide-react/dist/lucide-react.d.ts) for the concept and its …
- Very specific: line 34
Spacing: keep ≥2px of clearance between separate elements so they don't fuse at small sizes.
- Distinctive: line 47
When several icons sit in the same button group, they are one drawing in several states, not several drawings.
- Very specific: line 93
Every element needs a unique key (they render as a React list).
- Very specific: line 100
Add the icon to Icons.stories.tsx: at 24px with its name, at 16px, and inside a secondary iconOnly Button (with aria-label) next to the …
- Very specific: line 103
Run Storybook (pnpm run --filter @argos/frontend storybook) and check:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Lucide-style custom icons
Custom icons live in apps/frontend/src/ui/Icons.tsx and are documented in
apps/frontend/src/ui/Icons.stories.tsx. Read both before adding one — new
icons should extend the metaphors already there, not invent parallel ones.
First: prove Lucide doesn't have it
Search https://lucide.dev/icons/ (or grep the export list in
node_modules/lucide-react/dist/lucide-react.d.ts) for the concept and its
synonyms. Only draw a custom icon when nothing fits, and say in the icon's
JSDoc which Lucide icons it borrows from. A custom icon that duplicates a
Lucide drawing is a bug: it will drift from upstream refinements.
Lucide's design language
- Grid: 24×24 viewBox. Keep strokes inside the 20×20 live area (coordinates 2–22); primary square shapes usually sit in 3–21. Center the composition optically — the bounding box of all strokes should be roughly centered.
- Stroke only: 2px stroke, round caps and joins, no fill. Color is
currentColor.createLucideIconapplies all of this — never restate it. - Corners: 2px radius.
rx="2"on rects; mid-path either the arca2 2 0 0 1 -2 2or the cubicc-1 0-2-1-2-2official icons use — both draw the same corner. - Coordinates: snap to whole pixels. Sub-pixel values only when optical
centering demands it (official icons use
.1/.9in cubics, nothing finer). - Spacing: keep ≥2px of clearance between separate elements so they don't
fuse at small sizes. Strokes may touch or cross only when the drawing
means it (a handle sitting on its line, two layers blending — see
Lucide's
blend). - Density: at most ~5 elements. The app renders icons at 16px inside
buttons (
*:size-4); a detail thinner than ~2px of gap disappears there. - Metaphor before geometry: decide what the icon says first, reusing
Lucide's vocabulary — a rounded rect is a document/image, stacked offset
frames are layers (front = bottom-right, back = top-left, as in
copy), a dashed stroke is a ghost/absence.
Icons that belong to one control
When several icons sit in the same button group, they are one drawing in
several states, not several drawings. Build them from shared geometry
constants and change only the ink — the set then reads as a single control,
and the eye compares the difference instead of re-reading each icon. The
comparison set in Icons.tsx does this: the same two panels every time, solid
for the side on screen and ghosted for the side held back.
Ghosting a shape
To say "this part is not here", dash its outline with strokeDasharray rather
than drawing dash segments by hand. Lucide's own *-dashed icons place each
dash as its own path, which suits a full-size square but leaves a small shape
looking like scattered ticks with open corners.
Round caps eat the gaps: with the standard 2px stroke, a dash of d renders as
d + 2 of ink and a gap of g as g - 2 of space, so "2 4" reads as 4 units
of ink and 2 of gap. Pick the pattern at 16px, not at 24px — too fine a dash
closes up at button size and the ghosted shape becomes indistinguishable from a
solid one, which is the whole distinction the icon exists to make. Render the
candidates side by side at 48/24/16px and choose from that, rather than from the
numbers.
Reusing official fragments
The fastest way to stay on-style is to build from official path data. Each
icon's source is readable at
node_modules/lucide-react/dist/esm/icons/<kebab-name>.mjs — copy fragments
from there (a half-frame from square-split-horizontal, the corner peek from
copy, the handle-on-line from git-commit-vertical, …) and recombine them.
Implementation
import { createLucideIcon } from "lucide-react";
/** What the drawing says, and which Lucide icons it borrows from. */
export const MyThingIcon = createLucideIcon("my-thing", [
["rect", { x: "3", y: "3", width: "12", height: "12", rx: "2", key: "back" }],
["path", { d: "M21 12v7a2 2 0 0 1-2 2h-7", key: "front-peek" }],
]);- Name the icon after the app concept (
baseline-view), kebab-case. The name becomes thelucide-<name>class on the<svg>— that class is how Playwright locates icon-only buttons (see CLAUDE.md), so treat it as API and don't rename casually. - Every element needs a unique
key(they render as a React list). - The component accepts all Lucide props (
size,strokeWidth,className, aria attributes) — no wrapper needed, it drops intoButtonlike any Lucide icon.
Document and validate
- Add the icon to
Icons.stories.tsx: at 24px with its name, at 16px, and inside a secondaryiconOnlyButton(witharia-label) next to the Lucide icons it will sit beside in the real toolbar. - Run Storybook (
pnpm run --filter @argos/frontend storybook) and check:- legibility at 16px — squint test: is it still distinct from its neighbors in the set?
- stroke weight looks identical to the adjacent Lucide originals;
- nothing clips the viewBox edge; the icon doesn't look off-center;
- both light and dark color schemes.
pnpm run static-checksbefore finishing, like any change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

