client/plans/svg-icon-design-rules.md

SVG Icon Design Rules — App Button Icons

Analysis of all inline SVGs used in arrApps within www/index.html.

---

1. Canvas & ViewBox

All icons render inside:

<svg class="svgAppButtons" viewBox="0 0 10 10">

• ViewBox: 0 0 10 10 — a 10×10 unit coordinate space
• Usable drawing area: coordinates 2 through 8 (a 6×6 inner region), leaving a 2-unit margin on all sides
• No icon element touches 0 or 10; the outermost coordinates used are 2 and 8

---

2. Global Stroke Styling (from .svgAppButtons)

Applied via the CSS class .svgAppButtons:

Property	Value
fill	none
stroke	var(--button-color)
stroke-width	1.98
stroke-linecap	round
stroke-linejoin	round

Key implications:

• Icons are stroke-only by default — no fills (outlines, not solid shapes)
• The thick 1.98 stroke-width with round caps means even a zero-length line segment (M2,2 L2,2) renders as a visible dot/point
• round line joins create smooth corners rather than sharp miters

---

3. Coordinate Grid System

Icons use a 3-point grid within the drawing area:

     2     5     8
  2  ·     ·     ·
     
  5  ·     ·     ·
     
  8  ·     ·     ·

• Primary grid points: 2, 5, 8 (spaced 3 units apart)
• Secondary grid points: 3, 4, 6, 7 (used for finer detail)
• Center: (5, 5)

Most icons place their key vertices exclusively on the values 2, 3, 4, 5, 6, 7, 8 — always integers, never decimals (with one exception: the WS circle radius of 2.8284... which is 2√2).

---

4. Primitive Elements Used

4a. Dots (zero-length line segments)

A line from a point to itself creates a round dot due to stroke-linecap: round:

<line x1="6" y1="6" x2="6" y2="6" />
<!-- or equivalently in a path: -->
<path d="M2,2 L2,2" />

Used in: LINKS (9-dot grid), WS (accent dots), CAL (detail dots)

4b. Lines

Simple straight segments:

<line x1="2" y1="2" x2="8" y2="2" />

Used in: DB (3 horizontal lines)

4c. Circles

<circle cx="5" cy="5" r="3" />

Used in: RELAYS (4 small circles, r=1), P-FILE (single circle, r=3), WS (r≈2.83), EVENT (r=3)

4d. Paths

Open polylines for complex shapes:

<path d="M2,8 L8,2 L5,2 L8,2 L8,5" />

Used in: TOOLS, POST, FEED/VIEW, MSG, TODO, MAP, PEOPLE, EVENT (cross)

4e. Polygons

Closed shapes:

<polygon points="6,2 6,4 8,4 8,8 2,8 2,2" />

Used in: NOTE (document with folded corner), CAL (body shape)

4f. Rectangles

<rect x="2" y="2" width="6" height="6" />

Used in: BLOBS (nested rectangles), CAL (detail)

---

5. Design Patterns & Techniques

5a. Arrow/Pointer Pattern

An arrow is drawn by going to the tip, then backtracking along two short perpendicular segments to form the arrowhead:

<!-- POST: arrow pointing upper-right -->
<path d="M2,8 L8,2 L5,2 L8,2 L8,5" />

The trick: draw to the tip (8,2), go left to (5,2), return to (8,2), then go down to (8,5). The backtracking creates the arrowhead prongs without needing separate elements.

5b. Dot Grid Pattern

Use zero-length segments in a single path to create dot arrays:

<!-- LINKS: 3x3 dot grid -->
<path d="M2,2 L2,2 M2,5 L2,5 M2,8 L2,8 M5,2 L5,2 M5,5 L5,5 M5,8 L5,8 M8,2 L8,2 M8,5 L8,5 M8,8 L8,8" />

5c. Circle + Overlay Pattern

Combine a circle with crossing lines for emphasis:

<!-- EVENT: circle with X -->
<circle cx="5" cy="5" r="3" />
<path d="M2,2 L8,8 M2,8 L8,2" />

5d. Nested Shape Pattern

Concentric shapes for depth:

<!-- BLOBS: nested rectangles -->
<rect x="2" y="2" width="6" height="6" />
<rect x="4" y="4" width="2" height="2" />

5e. Continuous Path Pattern

A single unbroken path that traces the entire icon:

<!-- MAP: spiral rectangle -->
<path d="M2,8 L2,2 L8,2 L8,8 L4,8 L4,4 L6,4 L6,6" />

5f. Document/Fold Pattern

A polygon with a notch to suggest a folded corner:

<!-- NOTE: document with corner fold -->
<polygon points="6,2 6,4 8,4 8,8 2,8 2,2" />

---

6. Summary of Rules for Creating New Icons

1. ViewBox: Always 0 0 10 10
2. Drawing bounds: Keep all coordinates between 2 and 8 (inclusive)
3. Grid: Prefer integer coordinates on the 3-point grid: 2, 5, 8; use 3, 4, 6, 7 for detail
4. Stroke-only: Rely on the .svgAppButtons class — no inline fill/stroke needed (some existing icons redundantly specify stroke="black" and fill="none" but the class handles it)
5. Simplicity: Use the fewest possible elements — most icons are a single <path> or 2-3 primitives
6. Dots via zero-length segments: M x,y L x,y or <line x1 y1 x2=x1 y2=y1> for point markers
7. Arrows via backtracking: Draw to tip, extend one prong, return to tip, extend other prong
8. Semantic clarity: The icon should be recognizable at the small button size (~200×270px container) — favor bold, simple shapes over fine detail
9. No text in SVG: The label is rendered as HTML text below the SVG
10. Consistent stroke: stroke-width: 1.98, round caps and joins — do not override these

---

7. Icons Still Needing SVGs

These apps currently have empty svg strings:

App ID	Name	Suggested Icon Concept
ai	AI	Brain or neural network — e.g., circle with radiating dots
cashu	CASHU	Coin/token — e.g., circle with inner C or nut shape
didactyl	DIDACTYL	Finger/hand or teaching — e.g., pointing hand path
strudel	STRUDEL	Music/wave — e.g., sine wave or musical note

---

8. Visual Reference

graph TD
    subgraph Canvas 10x10
        subgraph Drawing Area 2-8
            A[2,2] --- B[5,2] --- C[8,2]
            A --- D[2,5] --- E[5,5 CENTER] --- F[8,5]
            D --- G[2,8] --- H[5,8] --- I[8,8]
            C --- F --- I
            B --- E --- H
        end
    end
    style A fill:#333,color:#fff
    style B fill:#333,color:#fff
    style C fill:#333,color:#fff
    style D fill:#333,color:#fff
    style E fill:#f66,color:#fff
    style F fill:#333,color:#fff
    style G fill:#333,color:#fff
    style H fill:#333,color:#fff
    style I fill:#333,color:#fff

The 9 primary grid points form the backbone of every icon. The center point (5,5) is used for circles and focal elements.