# stoke — Brand & Landing Design

> _The operator's hand on the forge._

A complete brand identity and marketing landing page for **stoke**, the CLI for the
Heavy Duty Forgejo forge. Designed from the codebase itself — every command group,
install path, and principle on the page maps to something the tool actually does.

## 🔗 Figma

**[stoke — Brand & Landing (Figma)](https://www.figma.com/design/q6bYh7pRChTbg0diKAVrcS/stoke-Brand-Landing)**

The file has four pages:

| Page | Contents |
| --- | --- |
| `01 · Brand System` | Logo lockup + ember spark mark, 14-token color palette, type scale, voice & principles |
| `02 · Landing — Desktop` | Full 1440px landing: nav, hero, ecosystem strip, command showcase, philosophy split, install, CTA, footer |
| `03 · Landing — Mobile` | 390px responsive landing |
| `04 · Assets & Components` | Command-group icon set (24px line) + generated-asset gallery |

> Renders live in the [Figma file](https://www.figma.com/design/q6bYh7pRChTbg0diKAVrcS/stoke-Brand-Landing) — see "Why the raster assets are not committed here" below.

## Concept

`stoke` is named after the act of feeding and tending a fire. The identity takes that
literally: a working **forge** — controlled heat, hot steel, precision — rendered as
hot ember on near-black anthracite. Industrial craft meets modern dev tool. The product
principle from the README ("every real operation performed against Forgejo becomes a new
CLI command") is the spine of the page.

### Color — ember on anthracite

| Token | Hex | Use |
| --- | --- | --- |
| `bg/base` | `#0C0A09` | Anthracite canvas |
| `bg/raised` | `#1A1614` | Raised surfaces |
| `bg/inset` | `#14100E` | Wells / code blocks |
| `border/subtle` | `#2A2320` | Hairlines |
| `border/ember` | `#3A2A1E` | Warm edges |
| `ember/red` | `#E2452B` | Deep heat |
| `ember/orange` | `#FF6A2C` | **Primary** · CTAs |
| `ember/amber` | `#FFB347` | Bright heat · command text |
| `hot/white` | `#FFF3E6` | White-hot highlight |
| `steel/blue` | `#3B6EA5` | Quench accent · links / URLs |
| `text/primary` | `#F5EDE6` | Primary text |
| `text/secondary` | `#A89A8E` | Secondary text |
| `text/muted` | `#6B5F56` | Meta / muted |
| `text/onEmber` | `#1A0E06` | Text on ember fills |

### Type

- **Archivo** (Black / SemiBold) — geometric-industrial display & headings, tight tracking
- **Inter** (Regular / Medium) — body copy
- **JetBrains Mono** — everything command-flavored (it's a CLI): prompts, flags, install snippets

### Logo

An **ember spark** mark — a four-point spark that reads as both a flame and a striker
feeding the forge — set over a warm glow, locked up with a heavy lowercase `stoke`
wordmark. Vector source in [`assets/logo-mark.svg`](../assets/logo-mark.svg).

## Page structure (desktop)

1. **Nav** — logo, section links, `Get started`
2. **Hero** — forge backdrop, `Every operation becomes a command.`, copy-able `apt-get install stoke`, CTAs
3. **Ecosystem strip** — the six repos the forge manages: `box · rig · cast · infra · handbook · incubator`
4. **Command showcase** — a live, syntax-colored `stoke` terminal session + cards for all 7 command groups (auth, repo, pr, issue, branch, org, user) with real example commands and command counts
5. **Philosophy split** — "Built for the hand on the forge" with the operator image + feature checklist (apt-native, 0600 tokens, batch import, dogfooded)
6. **Install** — apt (recommended) and from-source code cards, with the Node ≥ 22.12 note
7. **CTA band** — `Feed the forge.` over ember texture
8. **Footer** — logo, link columns, forge URL, version

## Assets

All imagery generated with **Artlist** (Seedream 5.0 Pro for stills, Kling 1.6 for the
ambient loop) and embedded in the Figma file.

| Asset | Where it lives |
| --- | --- |
| `assets/logo-mark.svg` | **In this repo** — ember spark logo mark, vector, 1.4 kB |
| Hero backdrop · 2048×878 21:9 — glowing coals, hot steel, sparks | Figma, page 04 |
| Operator's hand stoking coals · 3:2 (philosophy section) | Figma, page 04 |
| Molten ember bed · 21:9 (CTA / section backdrops) | Figma, page 04 |
| 5s ambient ember loop (motion) | Figma, page 04 |
| Desktop landing render · brand system render | Figma, pages 02 / 01 |

### Why the raster assets are not committed here

The first version of this change committed all of them — **23 MB of PNG and MP4
into a CLI repo.** That was a mistake, and it was mine. Two concrete costs:

- `stoke`'s `.git` is ~23 MB; the assets would have **doubled it**, permanently.
  Git history is forever, so a marketing render committed today is still being
  cloned by every contributor in five years.
- `package.json` had no `files` whitelist, so `npm pack` shipped the working
  directory. Measured: **the tarball went from ~100 kB to 23.7 MB** — a 200×
  bloat delivered to every user of a command-line tool, for images none of them
  will ever look at.

Binaries that exist to be *looked at* belong where people look at them: the Figma
file, which is linked at the top and is the source of truth anyway. The vector
logo stays because it is 1.4 kB of text, diffs cleanly, and is the one asset the
project itself might need to render.

This change also adds the missing `files` whitelist to `package.json`, so the
published tarball now contains only `src/` and the docs a user needs — a
pre-existing packaging bug that shipping the test suite had been hiding.

## Notes

- This PR was opened with `stoke pr create` — the tool designing its own storefront.
- Nothing here changes the CLI. It adds a `docs/` design record, one vector
  asset, and a packaging fix.