# cookicons — Canonical Icon Design Rules & Specification

`cookicons` is the custom SVG icon library for **trycook.ai** and **Cook4** (`app.trycook.ai`). Every icon in the library (72 icons across 3 coordinated styles = 216 SVGs) obeys the 10 hard rules below. Any new icon added to `cookicons` must pass all 10 rules and `node validate-cookicons.mjs` before shipping.

---

## 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 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 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`:
  ```js
  // 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.
