Design
Icon rules
The ten construction rules every cookicon passes, so icons stay sharp at 14 to 16px and match across stroke, duotone and solid.
cookicons is the custom SVG icon library for trycook.ai and the Cook app: 72 icons in 3 coordinated styles, 216 SVGs. Every icon obeys the 10 rules below. A new icon must pass all 10, and node validate-cookicons.mjs, before it ships. The rules as a file: ICON_DESIGN_RULES.md.
The three styles, side by side
Authored by hand, never converted. The duotone puts a 14% currentColor chamber under the full 1.8 stroke; the solid is a filled silhouette with evenodd cutouts and 1.5px moats.
cook-toqueSingle 3-puff contour and seammorning-briefCard, horizon dome and 3 raysapproval-gateShield and 90° check capsulesub-accounts1.5px moat between stacked cardscustom-domainFlush, non-crossing meridian bands1. Canvas, Grid & Safe Zone (24 × 24)
- ViewBox: Strictly
0 0 24 24(width="24" height="24"default in standalone.svgfiles;size={16}default in React). - Safe Zone (
2..22): Stroke centers stay insidex, y ∈ [2.5, 21.5]([2.0, 22.0]maximum for wide horizontal/circular elements). - Hard Clipping Guard (
1.0px): Including half ofstroke-width="2.0", no painted pixel may fall outside[1.2, 22.8]. Strokes placed atx = 1orx = 23clip when rendered at fractional DPRs and fail QA. - Coordinate Precision: Snap primary anchors to
0.5pxor0.2pxsteps; round computed arc/bezier coordinates to at most 2 decimal places (fmt(n)).
2. Optical Keylines & Center of Gravity
Match visual weight across square, circular, portrait, and landscape icons so a vertical rail or toolbar reads at one uniform density:
| Keyline Shape | Coordinates (24 × 24) | Corner / Radius | Example Icons |
|---|---|---|---|
| Square Card | x=3, y=3, w=18, h=18 | rx = 3.6–4.0 (k=0.62) | activity-feed, reports-chart |
| Circle | cx=12, cy=12 | r = 8.8–9.0 | check-circle, custom-domain, leads-target |
| Portrait Frame | x=4.5, y=3, w=15, h=18 (or 5.5, 2.8, 13, 18.4) | rx = 3.2–3.5 | docs, playbook, reel-vertical, mobile-phone |
| Landscape Frame | x=3, y=4, w=18, h=16 (or 3, 5, 18, 14) | rx = 3.4–3.6 | side-panel, sequences-mail, video-clapper, mcp-terminal |
- Optical Centering: Asymmetric shapes inside containers shift toward their narrower tip so the center of mass aligns with
(12, 12). For example, right-pointing play triangles insidevideo-clapper(x = 10.2..15.6) shift+0.4pxright of geometric center.
3. Cook Squircle Corner Geometry (k = 0.62)
- Cook’s brand mark (
<CookMark />,rx=14on44×44) and UI tokens (rounded-10,rounded-xl) use warm squircle proportions rather than sharp circular arcs. - Primary containers (
>= 10px): Draw with cubic-bezier corners using handle tensionc = 0.62 × rx(versus0.552for a standard circle) andrx = 3.4–4.0:// Top-right corner of squircleRect(x, y, w, h, rx) with c = rx * 0.62: `H${x2 - rx} C${x2 - rx + c} ${y} ${x2} ${y + rx - c} ${x2} ${y + rx}` - Medium sub-elements (
6–9px):rx = 1.8–2.4(e.g.,skills-puzzletiles). - Small internal details (
< 6px):rx = 1.2–1.6(e.g.,levels-pathbars,call-notesearpads). - Never leave 90° exterior container corners unrounded.
4. Calibrated for 16px at strokeWidth={1.8}
Cook’s product app (DESIGN.html Section 7) renders icons at 16px (primary: buttons, sidebar rows, menus) and 14px (inline labels/badges) with strokeWidth={1.8}.
- Caps & Joins: Always
stroke-linecap="round"andstroke-linejoin="round". - Minimum Counter Clearance (
>= 2.2pxopen gap):- Parallel
1.8pxstrokes must sit>= 4.0pxapart center-to-center (leaving>= 2.2pxof white space between ink edges). - Interior details must inset
>= 3.2pxfrom outer container walls unless intentionally bisecting the frame (likeside-panelorsheetsdividers).
- Parallel
- Simplicity Budget: Cap every icon at
2–5visual elements. If a concept requires tiny dense lines that blur together at14px, simplify the silhouette.
5. True SVG Curves Only (Zero Polygonal Approximations)
- Draw circles, domes, waves, and rounded bends with genuine
<circle>,A(elliptical arc), orC(cubic bezier) commands. - BANNED: Approximating arcs or curves with multi-segment
Lpolylines (arcPts), which look visibly faceted at24px+and bloat SVG size.
6. Pure Visual Metaphors (Zero Stick-Letter Text)
- Every icon must communicate through an instant-read silhouette that passes a
50msglance test at16px. - BANNED: Drawing multi-letter stick text inside a
24×24icon ("PF","CSV","API","AB","CC"). Stick text collapses into illegible blobs at14–16pxand breaks localization.- Use a grid (
sheets) instead of"CSV". - Use
>_(mcp-terminal) instead of"API"/"CLI". - Use a ribbon bookmark (
playbook) or text lines (docs) instead of"PDF".
- Use a grid (
- Cook Brand Boundaries:
- Use
cook-toque(never genericSparkles) when representing Cook itself in toolbars, switchers, or empty states (<CookMark mono />). Reserveai-sparkstrictly for generic AI prompt/generation actions. - Never draw an icon to represent one of Cook’s 8 departments (
Chief of Staff,Research,Marketing,Sales,Client Success,Systems,Support,Content). Departments are always represented by their illustrated round teammate avatars.
- Use
7. Three Bespoke Variants (stroke, duotone, solid)
Never rely on blind procedural stroke-to-fill conversion. Author all three variants explicitly so each reads cleanly on its own terms:
stroke(Default Outline):- Root:
fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round". - Children inherit stroke attributes from
<svg>so runtimestrokeWidthprops (1.5,1.8,2.0) scale every line uniformly.
- Root:
duotone(14% Tinted Chamber + Crisp Outline):- Adds a dedicated closed chamber path with
fill="currentColor" fill-opacity="0.14" stroke="none"first (underneath the1.8stroke paths). - Only fill enclosed semantic chambers (card bodies, domes, shields, folder pockets). For pure standalone linear glyphs (
plus,close,check,arrow-right,chevron-down), use a consistentr=9soft circle or18×18squircle backdrop induotoneonly when part of the core control set.
- Adds a dedicated closed chamber path with
solid(Filled Silhouette + Negative-Space Cutouts):- Root:
fill="currentColor"(nostrokeattributes). - Closed containers become solid
currentColorshapes with interior details carved out viafill-rule="evenodd" clip-rule="evenodd"capsule subpaths (r = 0.85–0.95, giving a1.7–1.9pxtransparent cutout that matches1.8pxstroke weight optically). - Standalone linear icons (
plus,close,check,arrow-right,channels,audio-wave) use exact closed capsule/union contours (r = 1.05–1.2) sosolidmode is 100% pure<path fill="currentColor">with zerostrokedependency.
- Root:
8. Disjoint evenodd Cutouts & Moat Separation
Two geometric traps ruin solid icons if not prevented:
- Never cross two cutout subpaths inside the same
evenodd<path>:- Under
fill-rule="evenodd", where two interior cutout loops overlap, the winding count becomes odd (1 outer + 1 cutoutA + 1 cutoutB = 3) and fills back in with a solid dot at the intersection! - Fix: Either construct a single non-self-intersecting union contour (
plusUnion,xUnion), split secondary cutouts into flush non-overlapping bands (custom-domainmeridians stopping0.04pxoutside latitude bars), or use a continuous non-crossing spine (spend-cap).
- Under
- Maintain a
1.5–1.8pxnegative-space moat between overlapping solid bodies:- When a secondary card, flap, or badge sits behind or over a primary body (
sub-accounts,funnel-clone,copy,trashlid), step the secondary shape back by1.5–1.8pxso the two solid shapes never merge into one lump. - Never draw a raw
strokehairline on top of a black solid body expecting a crease or page fold to show — it paints black-on-black and vanishes.
- When a secondary card, flap, or badge sits behind or over a primary body (
9. Token-Safe currentColor & Zero DOM IDs
- Zero Raw Hexes: Never put
#000,#fff,#335cff, orrgb(...)inside anycookiconsfile. Every stroke, fill, and0.14duotone tint usescurrentColorso icons inherit Cook semantic text tokens (text-text-soft-400,text-text-strong-950,text-primary-base) and passpnpm -C web check:design. - Zero
<defs>/idAttributes: Never use<mask id="...">,<clipPath id="...">, or<linearGradient id="...">inside an icon. Rendering two instances of the same icon inline on a page creates duplicate DOM IDs and breaks visibility when one instance is hidden.
10. Multi-Scale & Programmatic QA Gate
Before adding or editing any icon:
- Run
node validate-cookicons.mjs— verifies 0 duplicate slugs, valid AST tuples acrossstroke/duotone/solid, zero raw hex colors, zeroid/mask/clipPathattributes, and coordinate bounds within[1.2, 22.8]. - Visually inspect the icon at
14px,16px,24px, and32pxin both Light (#ffffff) and Dark (#000000) themes alongsidecook-toque,morning-brief,approval-gate, anddocsto confirm matching optical volume.
Do and don’t
Do: a pure visual metaphor. An instant-read silhouette of four elements at most: grid cells for sheets, >_ for CLI and MCP, a ribbon for playbooks.
Don't: stick-letter text inside 24px. Multi-letter labels (CSV, API, PF, AB, CC) turn into mush at 14 to 16px.
Do: disjoint evenodd cutouts. Keep cutout loops strictly apart (flush bands or one continuous S-spine) so intersections stay open.
Don't: crossing evenodd cutouts. Two crossing cutout paths in one evenodd shape fill back in as a dot right at the intersection.
Do: a 1.5px moat and stepped flaps. Leave 1.5 to 1.8px of negative space between stacked solid shapes so front and back cards stay distinct.
Don't: black-on-black strokes. A stroke crease painted on a solid black body vanishes: page folds and cylinder tiers become a lump.
Do: cook-toque and round faces. Use cook-toque for Cook brand chrome, and the round illustrated faces for the 8 departments.
Don't: generic sparkles or department icons. Never use sparkles as the Cook mark, and never replace a department's face with an icon tile.
Specification thresholds
| Rule | Value | Detail |
|---|---|---|
| Canvas | 24 × 24, viewBox="0 0 24 24" | 2px safe zone (2..22); a 1px hard outer guard so strokeWidth={2} never clips. |
| Stroke | 1.8 | Round caps and joins. 2.0 at 13 to 14px, 1.5 at 28px and up. |
| Clearance | ≥ 2.2px gap, 4.0px pitch | The smallest open gap between parallel 1.8px strokes, so 14 to 16px stays crisp. |
| Corner radius | k = 0.62 cubic, rx = 3.6 | Primary frames 3.4 to 4.0; medium tiles 1.8 to 2.4; micro bars 1.2 to 1.6. |
| Colour and IDs | currentColor, 0 IDs | No raw hexes; no <defs>, <mask>, <clipPath> or id attributes. |
Run the gate
# The mechanical cookicons rule gate, before shipping any new icon:
node cookicons/validate-cookicons.mjs
# Checks: kebab-case slugs, valid stroke/duotone/solid tuples, true A/C curves
# (no long L polylines), the 0.14 duotone layer, pure-fill solids, zero raw
# hexes, zero <mask>/<defs>/id collisions, coordinates inside [1.2, 22.8].
The validator ships with the library: validate-cookicons.mjs.