diff --git a/assets/logo-mark.svg b/assets/logo-mark.svg new file mode 100644 index 0000000..26eb481 --- /dev/null +++ b/assets/logo-mark.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..37f122b --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,114 @@ +# 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. diff --git a/package.json b/package.json index 5992e54..b360052 100644 --- a/package.json +++ b/package.json @@ -28,5 +28,12 @@ }, "bin": { "stoke": "src/cli.js" - } + }, + "files": [ + "src/", + "README.md", + "LICENSE", + "docs/DESIGN.md", + "assets/logo-mark.svg" + ] }