# CLAUDE.md Guidance for Claude Code sessions in this repo. This repo is the definitive source for the Gritmind brand: the mark, typefaces, colour and type tokens, design guidelines, production rules for every asset type, and the Claude brand skill that other repos and sessions load. Everything else (the website, decks, social, video) consumes from here. `README.md` is the map. `CONTRIBUTING.md` is how changes land. `CHECKLIST.md` tracks what is built and what is not. Read the relevant one before working in that area. ## Source-of-truth order When two places disagree, the higher one wins and the lower one is a bug to fix in the same PR: 1. `tokens/tokens.json` - every colour, type, spacing, motion and shadow value 2. `guidelines/` - the human-readable rules and the reasoning behind them 3. `assets/` and `templates/` - the published masters built from 1 and 2 4. `skill/gritmind-brand/` - the Claude skill; its `assets/` and `guidelines/` are generated from 1-3 Never introduce a design value (colour, type, spacing, radius, motion, shadow) in prose, a template or the skill that is not in `tokens.json`. If a new one is needed, add the token first. Medium specs - canvas sizes, safe zones, platform limits, loudness targets - belong in the production guideline for that medium. ## Layout Target layout. Folders not yet built are tracked in `CHECKLIST.md`; do not invent a parallel structure. ``` tokens/tokens.json source of truth for all design values guidelines/ foundations/ principles, voice, logo, colour, type, layout, iconography, illustration, data viz, imagery, motion production/ web, decks, documents, social, video, email, print, events assets/ logo/ SVG masters + PNG exports, one file per lockup x colourway fonts/ font files graphics/ dial, signal line and other reusable brand elements templates/ deck, one-pager, proposal, report, OG card, signature skill/gritmind-brand/ Claude skill: SKILL.md, references/, assets/ (generated parts) decisions/ brand decision records, NNNN-short-title.md scripts/ build and export scripts CHANGELOG.md every released change, grouped by version ``` ## Commands and generated files ```bash node scripts/build-skill.mjs # rebuild skill/gritmind-brand/assets/ and guidelines/ node scripts/build-reference.mjs # rebuild reference/data.js for the reference page node scripts/build-swoosh.mjs # rebuild the swoosh SVG masters in assets/graphics/ node scripts/build-favicon.mjs # rebuild favicon.ico at the repo root from the mark ``` Run it after any change to `tokens/`, `guidelines/`, `assets/logo/` or `assets/fonts/`, and commit the result in the same PR. Never hand-edit `skill/gritmind-brand/assets/`, `skill/gritmind-brand/guidelines/` or `reference/data.js`. `reference/index.html` is the browsable inventory. Its values come from the tokens through `data.js`; its prose summarises the guidelines and the skill by hand, so a PR that changes a rule updates the matching section of the page too. `SKILL.md` and `references/` are hand-written. Heavy binaries (PDF, video, Keynote, PowerPoint) go through Git LFS (`.gitattributes`). Run `git lfs install` once per machine before cloning or committing. Fonts and web images (woff2, woff, otf, ttf, png, jpg, jpeg, webp) are plain git: Netlify serves this repo as the reference site and does not download LFS files, so they would reach the browser as pointer files. ## Branches and releases - `main` - released brand. Protected by org policy; never commit or push to it. It only takes pull requests from `master`, and each merge is tagged `vX.Y.Z`. - `master` - integration. Changes arrive by PR from short-lived branches named `brand/` (for example `brand/logo-colourways`). - The remote is Azure DevOps, not GitHub - `gh` does not work here. - Versioning and what counts as a breaking change are defined in `CONTRIBUTING.md`. A PR that changes a token value, the logo geometry, a typeface or a core rule is breaking and needs a decision record and a major version bump. ## Writing rules These apply to every file in the repo, including code comments and JSON comments. - **No em dashes.** Never write "—". Use a spaced hyphen (" - ") for asides. Grep the diff for "—" and for its JSON escape (backslash, `u2014`) before committing. - **Sentence case** for every heading and title. Never Title Case. - **No exclamation marks.** - **Spelling: undecided.** Shipped website copy is US English; the existing skill prose is British. Until `decisions/` records the choice, match the file you are editing and do not mix within a file. - Guidelines state the rule, then one line of why. A rule with no reason gets argued with; a reason with no rule gets ignored. - Show concrete values (`#fb0102`, `180ms`, `120px`), never "a bit of space" or "brand red". - Every "don't" needs a "do instead". ## Files and assets - Filenames are lowercase kebab-case: `gritmind---.`, for example `gritmind-logo-full-navy-on-light.svg`. No spaces, no `final`, no `v2` or dates in filenames - git is the version history. - SVG is the master for any vector. PNG and PDF are exports, regenerated from the master by script where possible, never hand-edited. - Heavy working files (Final Cut libraries, raw footage, layered design sources) do not go in git. Store them in the shared drive and link them from the relevant guideline under a "Sources" heading. - Heavy binaries (PDF, video, Keynote, PowerPoint) go through Git LFS. If `git lfs ls-files` does not list one after you stage it, its extension is missing from `.gitattributes`. Do not add fonts or web images to LFS: the hosted reference site would serve them as pointer files. Do instead: keep them plain git, which `.gitattributes` already does for those extensions. ## Working with the skill `skill/gritmind-brand/` is what Claude loads when producing branded work in any repo. Keep `SKILL.md` short: the one rule, the invariants, voice, and a table pointing to one reference per deliverable type. Detail lives in the references. - When you change a guideline, update the matching skill reference in the same PR, or regenerate it if a build script covers it. - The skill must never contradict `guidelines/`. If you find a contradiction, fix it and note it in `CHANGELOG.md`. ## Before you open a PR 1. No em dashes, sentence-case headings, values match `tokens.json`. 2. Any new or changed asset has been checked against the pre-flight list in `CHECKLIST.md`. 3. `CHANGELOG.md` has an entry under "Unreleased". 4. A breaking change has a decision record and lists the consumers to update.