Skip to content
Cook
Documentation Browse

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.

IconStrokeDuotone (14% chamber)Solid (cutouts)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 bands

1. Canvas, Grid & Safe Zone (24 × 24)

  • ViewBox: Strictly 0 0 24 24 (width="24" height="24" default in standalone .svg files; size={16} default in React).
  • Safe Zone (2..22): Stroke centers stay inside x, y ∈ [2.5, 21.5] ([2.0, 22.0] maximum for wide horizontal/circular elements).
  • Hard Clipping Guard (1.0px): Including half of stroke-width="2.0", no painted pixel may fall outside [1.2, 22.8]. Strokes placed at x = 1 or x = 23 clip when rendered at fractional DPRs and fail QA.
  • Coordinate Precision: Snap primary anchors to 0.5px or 0.2px steps; 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 ShapeCoordinates (24 × 24)Corner / RadiusExample Icons
Square Cardx=3, y=3, w=18, h=18rx = 3.6–4.0 (k=0.62)activity-feed, reports-chart
Circlecx=12, cy=12r = 8.8–9.0check-circle, custom-domain, leads-target
Portrait Framex=4.5, y=3, w=15, h=18 (or 5.5, 2.8, 13, 18.4)rx = 3.2–3.5docs, playbook, reel-vertical, mobile-phone
Landscape Framex=3, y=4, w=18, h=16 (or 3, 5, 18, 14)rx = 3.4–3.6side-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 inside video-clapper (x = 10.2..15.6) shift +0.4px right of geometric center.

3. Cook Squircle Corner Geometry (k = 0.62)

  • Cook’s brand mark (<CookMark />, rx=14 on 44×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 tension c = 0.62 × rx (versus 0.552 for a standard circle) and rx = 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-puzzle tiles).
  • Small internal details (< 6px): rx = 1.2–1.6 (e.g., levels-path bars, call-notes earpads).
  • 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" and stroke-linejoin="round".
  • Minimum Counter Clearance (>= 2.2px open gap):
    • Parallel 1.8px strokes must sit >= 4.0px apart center-to-center (leaving >= 2.2px of white space between ink edges).
    • Interior details must inset >= 3.2px from outer container walls unless intentionally bisecting the frame (like side-panel or sheets dividers).
  • Simplicity Budget: Cap every icon at 2–5 visual elements. If a concept requires tiny dense lines that blur together at 14px, simplify the silhouette.

5. True SVG Curves Only (Zero Polygonal Approximations)

  • Draw circles, domes, waves, and rounded bends with genuine <circle>, A (elliptical arc), or C (cubic bezier) commands.
  • BANNED: Approximating arcs or curves with multi-segment L polylines (arcPts), which look visibly faceted at 24px+ and bloat SVG size.

6. Pure Visual Metaphors (Zero Stick-Letter Text)

  • Every icon must communicate through an instant-read silhouette that passes a 50ms glance test at 16px.
  • BANNED: Drawing multi-letter stick text inside a 24×24 icon ("PF", "CSV", "API", "AB", "CC"). Stick text collapses into illegible blobs at 14–16px and 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".
  • Cook Brand Boundaries:
    • Use cook-toque (never generic Sparkles) when representing Cook itself in toolbars, switchers, or empty states (<CookMark mono />). Reserve ai-spark strictly 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.

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:

  1. 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 runtime strokeWidth props (1.5, 1.8, 2.0) scale every line uniformly.
  2. duotone (14% Tinted Chamber + Crisp Outline):
    • Adds a dedicated closed chamber path with fill="currentColor" fill-opacity="0.14" stroke="none" first (underneath the 1.8 stroke 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 consistent r=9 soft circle or 18×18 squircle backdrop in duotone only when part of the core control set.
  3. solid (Filled Silhouette + Negative-Space Cutouts):
    • Root: fill="currentColor" (no stroke attributes).
    • Closed containers become solid currentColor shapes with interior details carved out via fill-rule="evenodd" clip-rule="evenodd" capsule subpaths (r = 0.85–0.95, giving a 1.7–1.9px transparent cutout that matches 1.8px stroke weight optically).
    • Standalone linear icons (plus, close, check, arrow-right, channels, audio-wave) use exact closed capsule/union contours (r = 1.05–1.2) so solid mode is 100% pure <path fill="currentColor"> with zero stroke dependency.

8. Disjoint evenodd Cutouts & Moat Separation

Two geometric traps ruin solid icons if not prevented:

  1. 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-domain meridians stopping 0.04px outside latitude bars), or use a continuous non-crossing spine (spend-cap).
  2. Maintain a 1.5–1.8px negative-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, trash lid), step the secondary shape back by 1.5–1.8px so the two solid shapes never merge into one lump.
    • Never draw a raw stroke hairline on top of a black solid body expecting a crease or page fold to show — it paints black-on-black and vanishes.

9. Token-Safe currentColor & Zero DOM IDs

  • Zero Raw Hexes: Never put #000, #fff, #335cff, or rgb(...) inside any cookicons file. Every stroke, fill, and 0.14 duotone tint uses currentColor so icons inherit Cook semantic text tokens (text-text-soft-400, text-text-strong-950, text-primary-base) and pass pnpm -C web check:design.
  • Zero <defs> / id Attributes: 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:

  1. Run node validate-cookicons.mjs — verifies 0 duplicate slugs, valid AST tuples across stroke / duotone / solid, zero raw hex colors, zero id/mask/clipPath attributes, and coordinate bounds within [1.2, 22.8].
  2. Visually inspect the icon at 14px, 16px, 24px, and 32px in both Light (#ffffff) and Dark (#000000) themes alongside cook-toque, morning-brief, approval-gate, and docs to 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

RuleValueDetail
Canvas24 × 24, viewBox="0 0 24 24"2px safe zone (2..22); a 1px hard outer guard so strokeWidth={2} never clips.
Stroke1.8Round caps and joins. 2.0 at 13 to 14px, 1.5 at 28px and up.
Clearance≥ 2.2px gap, 4.0px pitchThe smallest open gap between parallel 1.8px strokes, so 14 to 16px stays crisp.
Corner radiusk = 0.62 cubic, rx = 3.6Primary frames 3.4 to 4.0; medium tiles 1.8 to 2.4; micro bars 1.2 to 1.6.
Colour and IDscurrentColor, 0 IDsNo 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.