# 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. `plugin/skills/gritmind-brand/` - the Claude skill; its `assets/`, `guidelines/` and `decisions/` 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 plugin/ the gritmind-brand Claude Code plugin (decision 0008) .claude-plugin/ plugin.json - version equals the newest CHANGELOG.md heading skills/gritmind-brand/ Claude skill: SKILL.md, references/, generated assets/, guidelines/ and decisions/ skill/gritmind-brand symlink to plugin/skills/gritmind-brand, until the next major marketplace/ marketplace.json and README of the GitHub marketplace repo, which is published from here (build-marketplace.mjs) decisions/ brand decision records, NNNN-short-title.md scripts/ build, export and check scripts .azuredevops/ build-and-deploy.yml - checks every PR; releases on merge to main CHANGELOG.md every released change, grouped by version ``` ## Commands and generated files ```bash node scripts/build-skill.mjs # rebuild the skill's assets/, guidelines/ and decisions/ node scripts/build-reference.mjs # rebuild reference/data.js and the page copies (index.html, /) 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 node scripts/check-plugin.mjs # the plugin and writing checks CI runs on every PR node scripts/build-marketplace.mjs # build the GitHub marketplace repo's content in tmp/marketplace node scripts/release.mjs check # the next version, from the Unreleased headings ``` Run `build-skill.mjs` after any change to `tokens/`, `guidelines/`, `decisions/` or `assets/`, and commit the result in the same PR; CI fails a PR whose generated files are stale. Never hand-edit the skill's `assets/`, `guidelines/` or `decisions/`, or `reference/data.js`. A release is a merged PR from `master` into `main` (steps in `CONTRIBUTING.md`). The pipeline then works out the version and writes it into `CHANGELOG.md`, `plugin.json` and `reference/data.js` (`release.mjs stamp`); never type a version number into any of them by hand. `reference/index.html` is the browsable inventory, one page per topic at its own path (`/colour/`). Its values come from the tokens, and its Releases page from the released `CHANGELOG.md` headings, through `data.js`; its prose summarises the guidelines and the skill by hand, so a PR that changes a rule updates the matching page of the reference too. `build-reference.mjs` copies it to `index.html` at the repo root and `/index.html` for each page; the copies are git-ignored and built by Netlify on deploy, so never edit or commit them. A new page needs its folder added to `.gitignore` (the script says so), and its id must not match a repo folder such as `decisions/`. `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 squash-merged pull requests from `master`. After each merge the pipeline adds its own "Release X.Y.Z" commit (the only direct push), tags `vX.Y.Z` and merges `main` back into `master`. - `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 `plugin/skills/gritmind-brand/` is what Claude loads when producing branded work in any repo, installed as part of the `gritmind-brand` plugin. 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. - A skill only has what is inside its own folder once installed. Never cite a repo file the skill does not ship (`CHECKLIST.md`, `scripts/`, a template). Do instead: copy it in through `build-skill.mjs`, or state the rule in the skill. Files the build copies in have repo-only citations turned into links to the brand repo (`scripts/skill-paths.mjs`). `check-plugin.mjs` fails on a cited `assets/`, `references/`, `guidelines/` or `decisions/` path or a decision number that is not in the skill, and on an unlinked repo-only path, in every Markdown file the skill ships. - New brand skills go in `plugin/skills//`, in the same plugin. A separate plugin only for a different audience, heavy tooling or its own release schedule (decision `0008`). - 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", below `### Breaking`, `### Added` or `### Fixed` for its change class, written short: a bold title and a one-line description, then one-line sub-bullets (format at the top of the changelog). Never add a version heading: the pipeline stamps it after the release PR from `master` into `main` merges. 4. A breaking change has a decision record and lists the consumers to update.