lucide-style-icons

# 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 ```tsx 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.