agentleFS
argos-ciargos-ci/argos/.agents/skills/lucide-style-icons/SKILL.md

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.

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
  1. Very specific:

    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 …

    line 14
  2. Very specific:

    Spacing: keep ≥2px of clearance between separate elements so they don't fuse at small sizes.

    line 34
  3. Distinctive:

    When several icons sit in the same button group, they are one drawing in several states, not several drawings.

    line 47
  4. Very specific:

    Every element needs a unique key (they render as a React list).

    line 93
  5. Very specific:

    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 …

    line 100
  6. Very specific:

    Run Storybook (pnpm run --filter @argos/frontend storybook) and check:

    line 103

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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. createLucideIcon applies all of this — never restate it.
  • Corners: 2px radius. rx="2" on rects; mid-path either the arc a2 2 0 0 1 -2 2 or the cubic c-1 0-2-1-2-2 official 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/.9 in 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 the lucide-<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 into Button like any Lucide icon.

Document and validate

  1. 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 Lucide icons it will sit beside in the real toolbar.
  2. 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.
  3. pnpm run static-checks before finishing, like any change.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.