# AGENTS.md — Berlin Bytes Style Guide

Instructions for AI coding agents (Cursor, GitHub Copilot, Cline, Windsurf, Claude
Code, etc.) working in or consuming this repository. This is the brand & design
system for **Berlin Bytes**.

## What this repo is

A platform-agnostic design system: design tokens, brand guidelines, brand "context
packs" for closed tools, fonts, assets, and a React component kit. The goal is that any
agent or service can produce artifacts that follow the Berlin Bytes brand.

## Structure of the repo
All publishable content lives in `public/` and is directly reachable via `index.html`.
Build sources and generators live in `src/`. The infrastructure for hosting is in
`infrastructure/`.

## Read this first

1. **[public/brand/BRAND.md](public/brand/BRAND.md)** — the self-contained brand brief. Read it before generating anything.
2. **[public/brand/guidelines/design-system.md](public/brand/guidelines/design-system.md)** — full token + component reference.
3. **[public/brand/guidelines/voice-and-tone.md](public/brand/guidelines/voice-and-tone.md)** — for any copywriting.
4. **[public/skill/design-review-panel/SKILL.md](public/skill/design-review-panel/SKILL.md)** — optional review workflow for UI polish/redesign tasks.

## Design review workflow (UI polish/redesign)

For UI redesign, polish, modal/dialog/screen quality work, you can run the
`design-review-panel` workflow when you want a scored review loop.

- Reference docs/script:
  - `public/skill/design-review-panel/SKILL.md`
  - `public/skill/design-review-panel/panel_workflow.js`
- Process is optional and best used when you want a grounded design review:
  1. Capture reproducible baseline screenshots first (same paths each round).
  2. Run design-expert panel baseline scoring before edits.
  3. Implement highest-leverage fixes with design-system tokens only.
  4. Re-capture the exact same screenshots and re-rate.
  5. Repeat until panel averages clear target (default `>= 8`).
- Grounding is non-negotiable:
  - reviewers must `Read` each screenshot path before making visual claims;
  - no invented numeric measurements;
  - every issue must cite evidence (screenshot name or `file:line`).
- If reviewers conflict, use `AskUserQuestion` for tradeoff decisions instead of
  silently choosing a side.
- After convergence: complete normal hardening (tests/docs/changelog/PR hygiene).

## Source of truth & build

- **`src/tokens/tokens.json`** is the single source of truth (W3C DTCG format). **Edit tokens only here.**
- Run **`npm run build --prefix src`** to regenerate `public/dist/tokens.css`, `public/dist/tokens.ts`, and `public/dist/tailwind.preset.js`, plus `public/tokens/tokens.json` and `public/artifacts.json`.
- Never hand-edit generated files in `public/dist/`, `public/tokens/tokens.json`, or `public/artifacts.json`.
- Content files in `public/` (for example markdown in `public/brand/`) are edited directly.

## Source of truth matrix

- Publishable content (brand docs, assets, CSS, UI kit, templates, examples, entry files): edit in `public/` only.
- Token source: edit in `src/tokens/tokens.json` only.
- Generated token artifacts (`public/dist/*`, `public/tokens/tokens.json`, `public/artifacts.json`): generated via `npm run build --prefix src`; never hand-edit.
- Build/generator code: edit in `src/build/`.

## How to build artifacts

- **Web / HTML / React:** import `public/css/berlin-bytes.css` (or `public/dist/tokens.css` for tokens only). Use CSS variables like `var(--bb-mustard-400)`, `var(--radius-leaf-md)`. Reuse components in `public/ui/react/`.
- **Tailwind:** `module.exports = { presets: [require('./dist/tailwind.preset.js')] }`.
- **TypeScript:** `import { tokens, cssVar } from './dist/tokens.ts'`.
- **Slides / marketing:** start from templates in `public/templates/slides/`.
- **Image / video generation:** use `public/brand/VISUAL-PROMPT-PACK.md`.

## Hard rules (do not violate)

- Use only colors from the official ramps. Never invent hex values. **Two colors per surface, max.** Mustard `#FBCB12` is the only primary.
- Never use raw hex or raw px in component code — use design tokens via `var(--…)`.
- Fonts: Space Grotesk (display), Inter (body), Space Mono (numerics). No other fonts.
- Leaf radius: top-left + bottom-right rounded; **top-right + bottom-left always 0**. No circles, ever (not even avatars).
- Brand symbols are large graphic accents only — never small UI icons (use **Material Symbols / Material Icons** for UI icons).
- Don't pair Bearnie with the wordmark in the same composition.
- Logo placement: default top-left; follow-up slides (non-opener) bottom-left; social media visuals (e.g. LinkedIn) always place Berlin Bytes bottom-right.
- Logo sits directly on the surface — never in a separate background shape/box.
- Sentence case for headlines/body; the eyebrow is the only ALL-CAPS element.

## Trademark

Logo and Bearnie are Berlin Bytes intellectual property. Use only for Berlin Bytes work.