# בלון asset style guide

One library of hand-drawn SVG for everything בלון ships: the app, the hub, the demos' footers, the partner page, posts. Icons, balloon poses, spot illustrations, stickers and pattern tiles all follow this file. Read it fully before drawing. Gallery: `index.html`. Manifest: `assets.json`. Checker and PNG export: `_make/export.mjs`.

The 12 anchor assets (`icon-*`, `balloon-*`, `spot-*`, `pattern-paper-balloons`) are the reference. When in doubt, open them and match.

## 1. The idea in one line

Ink line work on paper, and **every coral pixel is our balloon.** Nothing else is ever coral: not confetti, not buttons, not dots, not text. When you see coral, it is the brand.

## 2. Palette

Three brand colours, four tints derived from them, one muted tone. Nothing else, ever. Hex only, uppercase, inside the file (no CSS, no `currentColor`, no opacity).

| Token | Hex | Use |
|---|---|---|
| Ink · דיו | `#26213A` | Every stroke, every solid shape, text |
| Lift · בלון | `#F25C3B` | The balloon only, always flat |
| Paper · נייר | `#FBF4EA` | Light background, paper fills (cards, bubbles, screens) |
| Paper-2 | `#F2E7D6` | Blocks and cards sitting on paper |
| Paper-3 | `#E6D8C3` | **The shadow tone on paper**: card shadows, ground shadows, the light confetti, quiet dots |
| Ink-2 | `#322C4A` | Blocks and cards sitting on ink |
| Ink-3 | `#453E61` | **The shadow tone on ink**, and secondary text on ink |
| Mist | `#8E86A6` | Muted placeholder lines, disabled, "text" bars inside mock screens. Works on both surfaces |

Derivation: Paper-2 and Paper-3 are Paper pulled toward Ink (about 6% and 12%). Ink-2 and Ink-3 are Ink pulled toward Paper (about 6% and 14%). Mist is the midpoint of Ink and Paper, kept on Ink's violet hue rather than grey. Same values as the social kit's `kit.css`.

**Inverting for ink backgrounds.** Assets are drawn once, for paper. On ink the gallery and `export.mjs` swap colours with this map; Lift and Mist stay:

```
#26213A <-> #FBF4EA     #F2E7D6 <-> #322C4A     #E6D8C3 <-> #453E61
```

So draw with the swap in mind: anything Ink becomes Paper on dark, anything Paper-3 becomes Ink-3. Never draw an asset that only works on one surface.

## 3. Grids, sizes, strokes

| Type | viewBox | Stroke | Live area | Balloon height | Corner radius |
|---|---|---|---|---|---|
| Icon 24 | `0 0 24 24` | 2 | 2..22 (20×20) | 7 or 8 | 2.5 (boxes), 2 (small) |
| Icon 48 | `0 0 48 48` | 3 (strings 2) | 3..45 | 14 to 16 | 5 |
| Balloon pose / sticker | `0 0 512 512` | 8 (strings), 6 to 9 (props) | 24..488 | 280 to 300 | 10+ |
| Spot illustration | `0 0 400 300` | 4 (3 for inner detail, 2.5 for tiny) | 16 in from every edge | 100 to 110 | 10 to 14 on cards, 18 on bubbles |
| Pattern tile | square, `0 0 160 160` default | none (dots only) | keep 8 from the edges or wrap exactly | 14 | - |

- Caps and joins are **always round** (`stroke-linecap="round" stroke-linejoin="round"`). Put them on a `<g>` once, not on every path.
- Strokes are centred on whole or half coordinates so 24-grid icons are crisp at 1x: a 2px stroke on y=16 covers 15..17. Avoid quarter pixels in icons; two decimals are fine in spots and poses (the checker rejects three).
- Nothing finer than the table. No hairlines, no 1px strokes anywhere.
- Icons: outline only, `fill="none"`, exactly one balloon (filled Lift, no outline), **no strings in 24**, a 2px string is allowed in 48 if it carries the idea (see `icon-leads-48`).
- A 48 variant exists when the 24 is a compromise. Same idea, same proportions, one extra detail at most (a window, a string, a second latitude line). Not a different drawing.
- Dots in icons are zero-length round-capped strokes (`M7.5 14v0`), so they are exactly stroke-wide.

## 4. The balloon

Use **only** the shape from `balon-mark.svg`. Never redraw it, never a generic teardrop, never a heart or a party balloon with a tail curl. Normalised, the balloon is a 64 × 75.2 box: body 64 × 68.8, knot 14 wide × 10.2 tall, knot tip at the bottom centre.

Ready-made paths (box top-left at 0,0; move with `transform="translate(x y)"` or regenerate with `balloonD()` from `_make/build.mjs`):

| h | w | path |
|---|---|---|
| 7 | 5.96 | `M2.98 0C4.64 0 5.96 1.73 5.96 3.52C5.96 5.27 4.35 6.4 2.98 6.4C1.61 6.4 0 5.27 0 3.52C0 1.73 1.31 0 2.98 0ZM2.98 6.05L3.63 7H2.33Z` |
| 8 | 6.81 | `M3.4 0C5.31 0 6.81 1.98 6.81 4.02C6.81 6.02 4.97 7.32 3.4 7.32C1.84 7.32 0 6.02 0 4.02C0 1.98 1.5 0 3.4 0ZM3.4 6.91L4.15 8H2.66Z` |
| 14 | 11.91 | `M5.96 0C9.29 0 11.91 3.46 11.91 7.04C11.91 10.54 8.69 12.81 5.96 12.81C3.22 12.81 0 10.54 0 7.04C0 3.46 2.63 0 5.96 0ZM5.96 12.1L7.26 14H4.65Z` |
| 16 | 13.62 | `M6.81 0C10.62 0 13.62 3.96 13.62 8.04C13.62 12.04 9.94 14.64 6.81 14.64C3.68 14.64 0 12.04 0 8.04C0 3.96 3 0 6.81 0ZM6.81 13.83L8.3 16H5.32Z` |
| 100 | 85.11 | `M42.55 0C66.36 0 85.11 24.73 85.11 50.27C85.11 75.27 62.1 91.49 42.55 91.49C23.01 91.49 0 75.27 0 50.27C0 24.73 18.75 0 42.55 0ZM42.55 86.44L51.86 100H33.24Z` |
| 110 | 93.62 | `M46.81 0C72.99 0 93.62 27.21 93.62 55.29C93.62 82.79 68.31 100.64 46.81 100.64C25.31 100.64 0 82.79 0 55.29C0 27.21 20.62 0 46.81 0ZM46.81 95.08L57.05 110H36.57Z` |
| 280 | 238.3 | `M119.15 0C185.8 0 238.3 69.26 238.3 140.74C238.3 210.74 173.88 256.17 119.15 256.17C64.41 256.17 0 210.74 0 140.74C0 69.26 52.5 0 119.15 0ZM119.15 242.02L145.21 280H93.09Z` |
| 300 | 255.32 | `M127.66 0C199.07 0 255.32 74.2 255.32 150.8C255.32 225.8 186.3 274.47 127.66 274.47C69.02 274.47 0 225.8 0 150.8C0 74.2 56.25 0 127.66 0ZM127.66 259.31L155.59 300H99.73Z` |

Other heights: `node -e` with `import { balloonD, knot } from "./_make/build.mjs"`, or scale by `h/75.2`.

Rules:
- **Flat Lift, no outline, no highlight, no gradient, no shading, no face.** The balloon is a colour, not a character. Emotion comes from pose, tilt, string and props (see the three poses).
- **Always in front.** Draw it last. Ink strokes may pass behind it and get covered (the roof peak in `icon-home`, the photo corner in `icon-post-photo`, the globe in `icon-site`). Strokes never cross over it.
- **Tilt between -15° and +15°** for floating; up to 72° only when it is resting (`balloon-sleeping`). Rotate around the body centre (`rotate(a cx cy)`, cx = x + 32s, cy = y + 37.8s).
- **One per icon.** Place it where the holam sits in the logo: on top of or rising from the object (home, gift, inbox), or replacing the one detail that would otherwise be the accent (the sun in a photo, the marked day in a calendar). It must change what the icon means, not decorate it.
- **The string is Ink, round caps, and draws a line.** It ties at the knot tip and does one thing: hangs straight (calm), waves (motion), coils into a spiral (waiting), lies on the floor (asleep), connects to the thing the balloon lifts (spots). It never loops around the balloon and never forks.
- **Multiplying:** pattern tiles and crowds use the same shape at h 14, each tilted differently, never scaled unevenly.
- Minimum height 7 in icons. Below that use a plain dot, in Ink, not coral.

## 5. Shading and depth

Flat. There is exactly one depth device: **the one-tone shadow.**

- A card, screen or bubble on paper gets a copy of itself in Paper-3 offset `+6, +8` behind it (spot scale) and nothing else. No blur, no opacity, no second shadow.
- Grounded things cast a Paper-3 ellipse on the floor (`balloon-sleeping`).
- Fills: cards Paper-2 with an Ink outline, screens inside cards Paper, light props Paper-3. On ink the swap handles it.
- The balloon itself never casts a shadow and never receives one.
- No gradients, no transparency, no filters, no blend modes, no masks.

## 6. Props and "mock content"

Mock screens and cards show content as bars: heading bar Ink (height 8 to 12, full radius), body lines Mist (height 5 to 7), button pill Ink. Right-aligned inside the frame, because our UI is RTL. Confetti is Ink rounded sticks (12 × 28, rotated) plus Ink dots, rings (stroke 6) and Paper-3 pieces. Motion lines are two short Ink strokes beside the balloon, never more.

Keep every prop in the same hand: round caps, radius proportional to stroke (about 3× the stroke), no sharp corners anywhere except the balloon knot.

## 7. Text

Fredoka, and almost never. An asset carries its message with shapes. Allowed: a single short Hebrew word in Fredoka 600 as a `<path>` (convert to outlines, we do not embed fonts in assets), or nothing. Never `<text>` elements, never Latin in a Hebrew asset, never numbers as decoration. Letters like the sleeping "zzz" are drawn as strokes, not type.

## 8. Files

- Name: `<type>-<name>.svg`, lowercase ASCII, hyphens. Types: `icon`, `balloon` (poses), `spot`, `sticker`, `pattern`. A 48 icon is `icon-<name>-48.svg`.
- Root: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="…" role="img"><title>Hebrew name</title>…</svg>`. No width/height on the root, no `id`s, no `<defs>` unless reused inside the same file, no comments, no editor metadata, no `style=`, no `<style>`, no `<image>`, no `data:`.
- Size: icons under 4 KB, poses and spots under 24 KB, tiles under 12 KB. If you are over, you drew too much.
- Numbers: at most two decimals. Prefer relative commands and `h`/`v` where a path is hand-written.
- Every file is one entry in `assets.json`: `{ "file", "type", "name_he", "tags" }`. `name_he` is what the gallery shows. Tags are English, lowercase, 3 to 5, for search.
- PNGs are generated, never hand-exported: icons at 96 and 192, poses and spots at 1200 wide, tiles at 640, all transparent (tiles keep their paper fill). Run `node brand/assets/_make/export.mjs` from `_lab`. It also validates every rule above and refuses the asset if a rule breaks. `_make/sheet.mjs` renders every icon on a pixel grid at 8× plus 1× for checking crispness.

## 9. Do / don't

| Do | Don't |
|---|---|
| Our balloon from the table above, flat Lift, drawn last | Any other balloon shape, outlined balloon, gradient, highlight gleam |
| One balloon per icon, where the holam would sit | A balloon in every corner, or a balloon that is just a dot of colour |
| Ink strokes 2/3/4/8 with round caps, radius about 3× the stroke | Mixed stroke weights in one asset, square caps, sharp corners |
| One Paper-3 shadow copy, offset, no blur | Drop shadows, blurs, opacity, two-tone shading, outlines on fills |
| Props in Ink, Paper-2, Paper-3, Mist | Coral confetti, coral buttons, coral text, any new colour |
| Emotion through pose and string (tilt, spiral, lying down) | Faces, eyes, arms, speech from the balloon |
| RTL composition: the "you" side on the right, content right-aligned | Mirrored copies of LTR illustrations |
| Hebrew `<title>`, English tags | Latin letters inside the drawing |
| Assets that read on both paper and ink after the swap | Ink details that vanish on a dark card |

Reference pairs: `icon-gift` (balloon as the bow) vs a gift with a ribbon bow and a balloon beside it (don't). `balloon-waiting` (string spirals) vs a balloon with a spinner ring around it (don't). `spot-site-live` (balloon literally lifts the browser) vs a browser window with a balloon in the corner (don't).

## 10. Before you hand over

1. `node brand/assets/_make/export.mjs` says `no issues`.
2. Open `index.html` and look at your asset on both tiles. It must read at the small size in the corner of the icon tile.
3. For icons, `node brand/assets/_make/sheet.mjs` and check the pixel grid: strokes on whole or half coordinates, no blurry edges at 1×.
4. One critique pass, one fix batch, stop.

## Founder feedback, round 1 (25.10)
- **Loved:** the illustrations, balloon poses, stickers, patterns and decorations. Make more of these.
- **The balloon must belong, not decorate.** Good: it *replaces* or *becomes* part of the thing (the account and team heads, the camera lens, the story ring). Bad: a balloon floating randomly on top of or next to an object. If the balloon can't be part of the object, leave it out. Not every asset needs a balloon: a library where every piece has one feels like balloons everywhere.
- **No more icons** for now.