# BUILD.md — Volt brand gallery

The shared build and deploy doc for this gallery. Every agent (T's and Josh's) reads it before working, and adds a dated entry to the CHANGELOG at the bottom after working.

## What this is
Volt is Sprint Dept's brand guidelines gallery. It is one web page with nine sections, in this order: Logo, Color palette, Typography, Photography, Iconography, Layout, Grids, ASCII patterns, Best practices. Every section has its own download buttons (Section MD, Section JSON, Full MD, Full JSON) so people and agents can grab the rules as files.

## File map
| File | What it is |
| --- | --- |
| `brand.source.json` | **The only file you edit for content.** All colours, fonts, logos, rules, copy. |
| `build.py` | Turns the source into the output files below. |
| `brand.md`, `brand.json` | Full brand file (all sections). Generated. |
| `logo.md` … `best-practices.json` | One md + one json per section (copies also in `sections/`). Generated. |
| `index.html` | The page. Reads `brand.json` in the browser. Layout and styles live here. |
| `assets/` | Logos (SVG), photos (WebP), icons, fonts (Special Gothic, Geist, Geist Mono). |
| `_headers` | Makes md/json files download instead of opening. |
| `wrangler.jsonc` | Cloudflare settings. No tokens in here, ever. |
| `HANDOFF.md` | Running notes from past jobs. |
| `BUILD.md` | This file. |

## How a build works
1. Edit `brand.source.json`.
2. Run `python3 build.py`.
3. It writes `brand.md`, `brand.json` and every section md/json.
4. Open `index.html` through a local server (`python3 -m http.server 8830`) and check it.

Never hand-edit the generated md/json files; your change will be lost on the next build.

## Adding or changing an item
- Find the section's list in `brand.source.json` (for example `colors`, `typeScale`, `logos`).
- Copy an existing item, change the values, keep the same keys.
- Every item needs a `source` tag:
  - `From Figma` when you measured or copied it from a Figma file (add the node id in a note if you can).
  - `Inferred (extrapolated)` when you filled a gap yourself.
- Keep old values when you rename things (for example colours keep `figmaName` and `previousEntries`).
- New section? Add it to `sections` in the source, add a `build_…` function in `build.py`, and a render branch in `index.html`.

## ASCII patterns (section 8)
- Three rotating 3D shapes (Diamond, Light bulb, Plus) drawn as digits with SD bolts on the brightest cells. Source: T's saved page (renderer and interaction ported, nothing else).
- Code: `assets/ascii.js` (one renderer, shape picked by `morph` 0 / 1 / 2). Data: `asciiPatterns` in `brand.source.json` (names, descriptions, settings, how to rebuild), output to `ascii-patterns.md` / `.json`.
- Dark mode only. In light mode the section shows a short note and a "Switch to dark mode" button.
- Interaction: drag (mouse spins and tilts, touch spins only so the page still scrolls), arrow keys, slow idle spin, momentum. Pauses off screen. Reduced motion turns off idle spin and momentum.
- To add a shape: write a distance function in `assets/ascii.js`, give it a new `morph` number in `sdf()`, add an item to `asciiPatterns.items`, run `python3 build.py`, then `python3 tests/test_ascii.py`.

## Fonts
Only our fonts: Special Gothic (display), Geist (body and UI), Geist Mono (micro labels, sparingly). The one font swap point is the `@font-face` block at the top of `index.html` plus `font` in the source. Do not add fonts from other files or other companies.

## Light and dark
- Both modes are built in from the start. The toggle sits top right and remembers the choice.
- Colours come from CSS variables in `:root` (dark) and `html.light` (light). Use the variables, not raw hex, in the page.
- SD Orange `#FF5100` is for the main CTA only (hover `#FF6A26`, pressed `#E04700`). Download buttons stay neutral and only turn orange on hover or focus.
- Logo cards: 3:2 tiles, light `#FAFAFA` + dark `#0A0A0A` pair for every logo.

## Testing (do this before you report)
- `python3 tests/test_ascii.py`: ASCII patterns render in dark at 390/1280/1920, rotate on drag (screenshots before/after), and are hidden in light mode.
- `python3 tests/test_v5.py` (set `BASE` to the URL you are testing). Runs Playwright at 390 (touch), 1280 and 1920 wide, in light and dark.
- It checks: the hero copy is exact, all 8 sections render, 0 console errors, no sideways scroll, every image loads, every tap target is at least 44px, colour groups are in order with copy buttons, and the Full MD button is not orange by default.
- Check downloads with curl: `curl -sI <link>/brand.md` must show `Content-Disposition: attachment`.
- Say what you tested and give real numbers if anything was only partly covered.

## Deploying
- The gallery is link-only: an unguessable path, `noindex`, no KV writes, files embedded in the Worker.
- Option A: Cloudflare Builds connected to the repo with root directory `core-assets`.
- Option B: `wrangler deploy` from this folder, signed in through wrangler's own login.
- Never put tokens, keys or passwords in any file in this repo.
- No production deploys without T's OK. Never touch other Workers, KV namespaces or Pages projects.

## Rules
- Never delete or overwrite: make a new copy (zip or `-vN` file) before big changes.
- Sprint Dept only: no client names, client copy or client fonts anywhere.
- Plain beginner wording in labels and notes.
- Don't push to git unless T asks; T uploads.

## CHANGELOG
Add newest at the bottom: date, who, what changed, what was tested.

- **2026-11-05 · Glom (executor)** · Applied WIP brand kit from Figma (node 78:893): greys, SD Orange, fonts, logos, buttons. Tested: Playwright 390/1280/1920 light+dark.
- **2026-11-05 · Glom (executor)** · Logo fix: uniform 3:2 light/dark tile pairs. Tested: Playwright, light and dark.
- **2026-11-05 · Glom (executor)** · Imagery: 11 photos (node 79:1078), 3:4 grid. Per-section md/json downloads with attachment headers. Tested: curl headers.
- **2026-11-05 · Glom (executor)** · Grids section from Design System node 316:161833; top-level buttons removed. Tested: Playwright.
- **2026-11-05 · Glom (executor)** · Layout v2 (long scroll, sticky numbered nav, big hero "Welcome to Volt", scroll reveal with reduced-motion respected). Colours renamed to SD Orange, Black, Grey 1–12 with grouped cards and a details table. Typography rules from Design System node 245:2110 mapped onto our fonts. Full MD button neutral until hover. Corpus renamed to Volt. Tested: tests/test_v5.py all 6 runs pass; curl download headers.
- **2026-11-05 · Glom (executor)** · Added section 8 ASCII patterns (Diamond, Light bulb, Plus) ported from T's saved page; dark mode only; md/json downloads. Tested: tests/test_ascii.py 6/6 pass (rotation by drag, frames drawn, light-mode note), tests/test_v5.py.