@notambourine/brand-kit 1.2.1 → 1.4.0

package/README.md

@@ -1,18 +1,18 @@
 # brand-kit
 
-The NoTambourine brand's golden set: `tokens.css`, `components.css`, `deck.css`, the
-font binaries, the logo in `logo/`, and `SKILL.md`, which is the written system behind
-them - color, type, spacing, component recipes, and voice.
+NoTambourine brand assets and guidance for design, decks, and copy. Use the
+stylesheets, fonts, and logo together. Read `SKILL.md` for the relevant
+guidance.
 
 Correct a brand value here. Every other copy is downstream.
 
-| Link this | To get |
-|---|---|
-| `tokens.css` | The whole system: the faces, every value, and styled bare HTML. |
-| `vars.css` | The values alone, for a surface with its own faces and base layer. |
+| Link this        | To get                                                             |
+| ---------------- | ------------------------------------------------------------------ |
+| `tokens.css`     | The whole system: the faces, every value, and styled bare HTML.    |
+| `vars.css`       | The values alone, for a surface with its own faces and base layer. |
 | `components.css` | `.nt-btn`, `.nt-card`, `.nt-nav`, and the rest, all `var()`-based. |
-| `deck.css` | The Marpit slide theme, 1280x720. Load `vars.css` on the page too. |
-| `logo/` | The mark, the lockup, the icons, and the rasters cut from them. |
+| `deck.css`       | The Marpit slide theme, 1280x720. Load `vars.css` on the page too. |
+| `logo/`          | The mark, the lockup, the icons, and the rasters cut from them.    |
 
 ## Logo
 
@@ -25,32 +25,30 @@ stylesheets load. Change the logo by editing that script and re-running it:
 ./scripts/build-logo.py    # needs rsvg-convert on PATH
 ```
 
-The raster half shells out to `rsvg-convert`, which ships in librsvg: `brew
-install librsvg` on macOS or Linux, the GTK runtime on Windows. The vector half
-runs without it.
+The raster half shells out to `rsvg-convert`, which ships in librsvg:
+`brew install librsvg` on macOS or Linux, the GTK runtime on Windows. The vector
+half runs without it.
 
 ### Vector
 
-| File | Use |
-|---|---|
-| `logo/lockup.svg` | Default. Mark plus wordmark, outlined, so it needs no font. |
-| `logo/lockup-white.svg` | On dark, on pink, on a photo. |
-| `logo/lockup-ink.svg` | One-color print, fax-grade output, a light background that fights pink. |
-| `logo/lockup-text.svg` | The wordmark as live `<text>` over an inlined ten-glyph Nunito subset. Open this one to edit the type; ship `lockup.svg`. |
-| `logo/monogram.svg` | Mark with `no` nested in the crescent, transparent, square. The short form: avatar, app icon, stamp. |
-| `logo/monogram-white.svg`, `logo/monogram-ink.svg` | The same two reversals. |
-| `logo/mark.svg` | Mark alone, no letters. Watermarks, a bullet, anywhere `no` would be read as a word. |
-| `logo/mark-white.svg`, `logo/mark-ink.svg` | The same two reversals. |
-| `logo/favicon.svg` | Browser tab: monogram on the dark tile, cut tight so 16px survives. |
-| `logo/icon.svg` | App tile, rounded corners, opaque. |
-| `logo/icon-square.svg` | App tile, square edges, for iOS and anything else that masks the icon itself. |
-| `logo/icon-maskable.svg` | Android maskable: full bleed, monogram inside the 80% safe circle. |
-
-The monogram is the lockup truncated to its first two letters, not a second
-drawing: same face, same size, same origin, so the `n` nests into the crescent's
-mouth exactly as it does in the full lockup. At 16px the letters go soft, which
-is the price of the monogram over a bare crescent; every browser that matters
-reads `favicon.svg` and scales it instead.
+| File                                               | Use                                                                                                                       |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `logo/lockup.svg`                                  | Default. Mark plus wordmark, outlined, so it needs no font.                                                               |
+| `logo/lockup-white.svg`                            | On dark, on pink, on a photo.                                                                                             |
+| `logo/lockup-ink.svg`                              | One-color print or light backgrounds where pink lacks contrast.                                                           |
+| `logo/lockup-text.svg`                             | The wordmark as live `<text>` over an inlined ten-glyph Nunito subset. Open this one to edit the type; ship `lockup.svg`. |
+| `logo/monogram.svg`                                | Mark with `no` nested in the crescent, transparent, square. The short form: avatar, app icon, stamp.                      |
+| `logo/monogram-white.svg`, `logo/monogram-ink.svg` | The same two reversals.                                                                                                   |
+| `logo/mark.svg`                                    | Mark alone, no letters. Watermarks, a bullet, anywhere `no` would be read as a word.                                      |
+| `logo/mark-white.svg`, `logo/mark-ink.svg`         | The same two reversals.                                                                                                   |
+| `logo/favicon.svg`                                 | Browser tab: monogram on the dark tile, cut tight so 16px survives.                                                       |
+| `logo/icon.svg`                                    | App tile, rounded corners, opaque.                                                                                        |
+| `logo/icon-square.svg`                             | App tile, square edges, for iOS and anything else that masks the icon itself.                                             |
+| `logo/icon-maskable.svg`                           | Android maskable: full bleed, monogram inside the 80% safe circle.                                                        |
+
+The monogram uses the lockup's first two letters with the same face, size, and
+position. The letters lose detail at 16px; use `favicon.svg` for browser
+scaling.
 
 `lockup-text.svg` overruns its viewBox in librsvg and resvg, which apply
 `letter-spacing` differently than a browser does. That is why the outlined
@@ -61,16 +59,16 @@ reads `favicon.svg` and scales it instead.
 Everything in `logo/export/` is cut from the SVGs above, so treat it as output:
 regenerate it, never retouch it.
 
-| File | Cut from |
-|---|---|
-| `favicon.ico` (16, 32, 48) | `favicon.svg` |
-| `favicon-16x16.png`, `favicon-32x32.png`, `favicon-48x48.png` | `favicon.svg` |
-| `apple-touch-icon.png` (180) | `icon-square.svg` |
-| `icon-192.png`, `icon-512.png` | `icon.svg` |
-| `icon-maskable-512.png` | `icon-maskable.svg` |
+| File                                                                                  | Cut from                             |
+| ------------------------------------------------------------------------------------- | ------------------------------------ |
+| `favicon.ico` (16, 32, 48)                                                            | `favicon.svg`                        |
+| `favicon-16x16.png`, `favicon-32x32.png`, `favicon-48x48.png`                         | `favicon.svg`                        |
+| `apple-touch-icon.png` (180)                                                          | `icon-square.svg`                    |
+| `icon-192.png`, `icon-512.png`                                                        | `icon.svg`                           |
+| `icon-maskable-512.png`                                                               | `icon-maskable.svg`                  |
 | `monogram-256.png`, `monogram-512.png`, `monogram-1024.png`, `monogram-white-512.png` | `monogram.svg`, `monogram-white.svg` |
-| `mark-256.png`, `mark-512.png`, `mark-1024.png`, `mark-white-512.png` | `mark.svg`, `mark-white.svg` |
-| `lockup-1024.png`, `lockup-2048.png`, `lockup-white-1024.png`, `lockup-ink-1024.png` | the three lockups |
+| `mark-256.png`, `mark-512.png`, `mark-1024.png`, `mark-white-512.png`                 | `mark.svg`, `mark-white.svg`         |
+| `lockup-1024.png`, `lockup-2048.png`, `lockup-white-1024.png`, `lockup-ink-1024.png`  | the three lockups                    |
 
 ### Wire it up
 
@@ -78,16 +76,16 @@ regenerate it, never retouch it.
 `logo/` is served as a unit.
 
 ```html
-<link rel="icon" href="/logo/favicon.svg" type="image/svg+xml">
-<link rel="icon" href="/logo/export/favicon.ico" sizes="32x32">
-<link rel="apple-touch-icon" href="/logo/export/apple-touch-icon.png">
-<link rel="manifest" href="/logo/site.webmanifest">
+<link rel="icon" href="/logo/favicon.svg" type="image/svg+xml" />
+<link rel="icon" href="/logo/export/favicon.ico" sizes="32x32" />
+<link rel="apple-touch-icon" href="/logo/export/apple-touch-icon.png" />
+<link rel="manifest" href="/logo/site.webmanifest" />
 ```
 
 ## Consume it
 
-Install it and read the bytes out of `node_modules`. Do not copy a stylesheet into a
-consumer; a copy drifts and nothing fails when it does.
+Install the package and import its stylesheets from `node_modules`. Keep copied
+assets tied to the installed version.
 
 ```bash
 npm install @notambourine/brand-kit
@@ -103,15 +101,16 @@ import "@notambourine/brand-kit/tokens.css";
 cp -R node_modules/@notambourine/brand-kit/{fonts,logo} public/
 ```
 
-`tokens.css` declares the `@font-face` rules and every `var()` the other two read, so
-load it first and serve `fonts/` beside it. The paths inside it are relative to the CSS
-file, so inlining it into a `<style>` block breaks the faces.
+`tokens.css` declares the `@font-face` rules and every `var()` the other two
+read, so load it first and serve `fonts/` beside it. The paths inside it are
+relative to the CSS file, so inlining it into a `<style>` block breaks the
+faces.
 
 ### With Tailwind or StyleX
 
 A surface with its own faces and base layer imports `vars.css` alone and writes
-`var()` against the semantic aliases. Neither system needs anything from this kit
-beyond the custom properties.
+`var()` against the semantic aliases. Neither system needs anything from this
+kit beyond the custom properties.
 
 ```js
 import "@notambourine/brand-kit/vars.css";
@@ -121,55 +120,60 @@ const styles = stylex.create({
 });
 ```
 
-Tailwind claims the `--font-*` and `--ease-*` namespaces for its own utilities, which
-is why those two groups ship a `--nt-*` primitive under the alias: a Tailwind surface
-reads the primitive. StyleX hashes the names it generates and collides with neither.
+Tailwind claims the `--font-*` and `--ease-*` namespaces for its own utilities,
+which is why those two groups ship a `--nt-*` primitive under the alias: a
+Tailwind surface reads the primitive. StyleX hashes the names it generates and
+collides with neither.
 
-Two StyleX-specific traps. Bridging through `stylex.defineVars` breaks `.theme-light`,
-because StyleX declares those properties on `:root` and a custom property resolves
-where it is declared, so a `.theme-light` subtree still inherits the dark value; a raw
-`var()` string resolves at the element and themes correctly. And StyleX outranks the
-element styles in `elements.css` only while `useCSSLayers` is off - turn layers on and
-an unlayered `h1` wins, so import into a layer StyleX orders itself against:
+Two StyleX-specific traps. Bridging through `stylex.defineVars` breaks
+`.theme-light`, because StyleX declares those properties on `:root` and a custom
+property resolves where it is declared, so a `.theme-light` subtree still
+inherits the dark value; a raw `var()` string resolves at the element and themes
+correctly. And StyleX outranks the element styles in `elements.css` only while
+`useCSSLayers` is off - turn layers on and an unlayered `h1` wins, so import
+into a layer StyleX orders itself against:
 
 ```css
 @import "@notambourine/brand-kit/tokens.css" layer(base);
 ```
 
-The package ships the stylesheets, `fonts/`, `logo/`, and `SKILL.md`. The logo build
-script and `hello-world.html` stay in the repo. Pin an exact version and bump it on
-purpose; a caret range moves the brand under a consumer with no diff to review.
+The package ships the stylesheets, `fonts/`, `logo/`, and `SKILL.md`. The logo
+build script and `hello-world.html` stay in the repo. Pin an exact version and
+bump it on purpose; a caret range moves the brand under a consumer with no diff
+to review.
 
 Consumers today:
 
-| | |
-|---|---|
-| `notambourine/claude` | Ships it as the `/nt-brand:system` skill. |
-| `notambourine/share` | Serves `tokens.css` and `deck.css` from its own origin; a self-only CSP forbids a CDN. |
-| `notambourine/notambourine.com` | The site's stylesheet. |
+|                                 |                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `notambourine/claude`           | Ships it as the `/nt-brand:system` skill.                                              |
+| `notambourine/share`            | Serves `tokens.css` and `deck.css` from its own origin; a self-only CSP forbids a CDN. |
+| `notambourine/notambourine.com` | The site's stylesheet.                                                                 |
 
 ## Gate a consumer
 
 A `var(--x)` that reads a token this repo stopped declaring falls through to its
-fallback and the page still renders, so a bump can go wrong quietly. Check three things
-in the consumer's CI: the font bytes hash against `fonts/`, every color is one this kit
-defines, and every `var()` reads a property it still declares. `notambourine/share`'s
-`npm run brand` is the reference implementation.
+fallback and the page still renders, so a bump can go wrong quietly. Check three
+things in the consumer's CI: the font bytes hash against `fonts/`, every color
+is one this kit defines, and every `var()` reads a property it still declares.
+`notambourine/share`'s `npm run brand` is the reference implementation.
 
-## Release
+## Format documents
 
-Bump `version` in `package.json`, land it, then tag the merge commit:
+Install dependencies with `npm ci`. Run `npm run format` before sharing
+documents or exporting them. Markdown and MDX are included, along with HTML and
+JSON/YAML. Review rendered output after formatting.
 
-```bash
-git tag v1.0.1 && git push origin v1.0.1
-```
+## Release
+
+Update `version` in `package.json` and the lockfile, then merge to main. The
+publish workflow releases versions that are not already on npm and tags the
+published commit. Formatting must pass before the package is packed or
+published.
 
-`.github/workflows/npm-publish.yml` publishes the tag through npm trusted publishing.
-No token lives in this repo, and npm attaches a provenance attestation tying the
-published tarball to that workflow run. The workflow fails if the tag and the manifest
-disagree.
+Publishing uses npm trusted publishing with provenance.
 
 ## License
 
-MIT for the stylesheets and `SKILL.md`. The faces in `fonts/` are SIL Open Font License;
-see `fonts/OFL.txt`.
+MIT for the stylesheets and `SKILL.md`. The faces in `fonts/` are SIL Open Font
+License; see `fonts/OFL.txt`.

package/SKILL.md

@@ -1,363 +1,44 @@
 ---
 name: system
-description: NoTambourine brand system - colors, tokens, type, spacing, components, deck theme, voice, and the audit that checks work against them. Use when building or styling anything NoTambourine-branded, when asked for the brand colors, or when checking copy before it ships.
+description:
+  Build or review NoTambourine-branded surfaces, decks, and copy. Use for brand
+  styling, color questions, positioning, and copy audits before shipping.
 ---
 
 # NoTambourine brand
 
-A boutique AI-enabled engineering agency for leaders whose technology is holding back the
-business.
-Senior operators work inside the client's org. The constraint may be a legacy commerce stack, a
-revenue-share SaaS, a roadmap nobody can staff for. **Value creation is the deliverable,
-and trust is earned by shipping.** Improve how the organization works through delivery.
-AI at the keyboard is why a small team can price this way; it is not what the client buys.
-
-Define fit by the business constraint and the responsibility we take on. Mention
-private-equity experience when relevant to the conversation. Keep the general positioning
-open to clients regardless of ownership structure.
-
-The name carries the style, not the positioning. A tambourine is what you add when there
-is nothing left to add, so **NoTambourine = no padding**. That is why the design is
-confident type, one decisive pink, lots of air, no decoration.
-
-## Referrals
-
-Help a referred reader confirm fit and explain the agency to a colleague. Keep the
-signature "Senior engineers. No tambourine." beside a concrete explanation of the work.
-Use this description for an introduction:
-
-> NoTambourine works inside your team to resolve technology constraints and leaves you
-> equipped to own the result.
-
-Give referrers recognizable reasons to call:
-
-- A commerce platform limits what the business can do.
-- Vendor dependence makes necessary changes too costly or slow.
-- An important roadmap needs capacity the team cannot staff.
-
-## Offers
-
-Use these names in copy and examples. Describe the client's outcome before staffing.
-
-- **Assessment:** Identify the technology constraint and decide what to address first.
-- **Embedded:** Work inside the client's team to lead and deliver the changes.
-
-Invite a conversation before asking the reader to choose an engagement.
-
-Fuller doctrine is published, so fetch it rather than reconstructing it. Every path below
-returns `text/plain` over plain HTTP with no auth, no signup, and no redirect - `curl` or
-`wget` one directly. This file stands alone when the machine is offline.
-
-| Fetch | For |
-|---|---|
-| `notambourine.com/llms.txt` | The index. Start here when you do not know which file you want. |
-| `notambourine.com/AGENTS.md` | What the firm does, who it serves, and the citation rules. |
-| `notambourine.com/SOUL.md` | What NoTambourine believes. The beliefs this design serves. |
-| `notambourine.com/CULTURE.md` | How the team works. Async-first, one operator per workstream. |
-
-`SOUL.md` and `CULTURE.md` are public cuts of longer internal documents, so absence from
-them is not evidence of anything. Client material is unpublished and stays that way -
-`robots.txt` disallows `/reports/` and `/pog/` for every agent.
-
-## Use the files
-
-Two stylesheets cover ~80% of any build, and a third renders a deck. Copy them next to
-your output, or inline them.
-
-| File | What it does |
-|---|---|
-| `tokens.css` | The whole system in one link: `fonts.css`, `vars.css`, `logo-vars.css`, `elements.css`. Load first and `h1`, `p`, `a`, `code`, `.eyebrow`, `.display`, `.lede` all come styled. |
-| `vars.css` | Every value as a CSS var, and nothing else. What a surface with its own faces and its own base layer imports. |
-| `logo-vars.css` | `--nt-mark-url` and `--nt-lockup-url`: the pink artwork as `data:` URIs, for a surface that can reach it only through CSS. A deck theme owns no element inside a slide, and a printed PDF has no origin to fetch from. Generated by `scripts/build-logo.py`. |
-| `fonts.css` | The six `@font-face` blocks, pointed at `./fonts/`. |
-| `elements.css` | The base element styles: bare `h1`, `p`, `a`, `code` on brand with no classes. |
-| `components.css` | `.nt-btn`, `.nt-badge`, `.nt-chip`, `.nt-input`, `.nt-card`, `.nt-nav`, `.nt-switch`/`.nt-check`/`.nt-radio`. All `var()`-based. |
-| `deck.css` | Marpit slide theme, 1280x720. Every value a `var()` off `tokens.css`. See "Decks" below for how to feed it markdown. |
-| `fonts/` | Six woff2: Nunito, Hanken Grotesk, JetBrains Mono, roman and italic each. Latin subset, variable, SIL OFL 1.1 (`fonts/OFL.txt`). Plus `nunito-wordmark-800.woff2`, a ten-glyph static subset for the lockup alone - 1.5 KB against Nunito's 39 KB, so a PDF or an offline snapshot inlines it as a data URI. |
-| `logo/` | The mark, the monogram, the three lockup colorways, the favicon and app tiles, and `export/` rasters cut from them. `scripts/build-logo.py` writes all of it. |
-| `hello-world.html` | Working page using both stylesheets. Start here for a mock; open it to eyeball the brand. |
-
-```html
-<link rel="stylesheet" href="tokens.css">
-<link rel="stylesheet" href="components.css">
-```
-
-**Copy the whole skill directory, not the stylesheets alone.** `tokens.css` pulls in
-`fonts.css`, which declares `@font-face` against `./fonts/`, so type is wired up with
-no network and no third party - a mock renders on brand from `file://` on a plane.
-Those paths resolve against the CSS file, so inlining the CSS into a `<style>` block
-instead means `fonts/` has to sit beside the HTML.
-
-A surface that already ships its own faces and its own base layer imports `vars.css`
-alone. It gets every value and none of the opinions, and there is still one copy of
-each number.
-
-Never swap that for a Google Fonts `@import`. It sends the visited URL to Google as a
-`Referer` and blocks a self-only CSP, which is why the site deleted its own. A mock is
-the artifact most likely to graduate into a real page, so it carries the same rule.
-
-### Fonts on a locked-down surface
-
-Some surfaces cannot load `./fonts/` at all: a claude.ai artifact, an email client, a
-README banner. There the faces fall back silently and the brand degrades without a
-decision. Make it a decision:
-
-- Inline the face as a data URI in the `@font-face` `src`: `base64 -i fonts/<file>.woff2`
-  emits the payload. The wordmark subset is 1.5 KB, so inline it always; a full face runs
-  30-40 KB, so inline one only when the surface is worth the bytes.
-- Where inlining is not worth it, the fallback stacks in `vars.css` are the brand's
-  degraded form: `system-ui` for display, `ui-monospace` for body. Ship them knowingly.
-  The Google Fonts rule above holds here too.
-
-## Non-negotiables
-
-These are the rules that get broken. Check your output against them.
-
-- **Dark by default.** Page is `var(--bg)` (#0B0B0C), cards `var(--bg-card)` (#141416).
-  Pure white is never a surface. `class="theme-light"` is opt-in and rare - print, a press
-  page, a one-off email.
-- **One pink.** `#E75A7C` is the only accent. One pink CTA per screen. Mint (`#58C9B9`) is
-  structural - borders, status dots, supporting icons - **never** a CTA.
-- **No gradients.** Not on sections, not on buttons, not on heroes. One radial halo behind
-  a hero lockup is the sole exception, and it must read as lighting.
-- **No stock photography, no AI imagery, no hand-drawn textures.** Imagery is flat,
-  geometric, two-color. Ask for real assets before papering over.
-- **Pill buttons** (`--r-pill`), 14px cards (`--r-md`). Never mix a sharp and a round
-  corner in one component.
-- **No colored-left-border cards.** Full borders, not stripes.
-- **Press scales to 0.97, hover does not move.** Hover darkens fill or lifts shadow. No
-  translate, no scale on hover, no parallax, no looping animation.
-- **No emoji in UI chrome, no icon fonts.** Icons are Lucide SVG, 1.75px stroke, rounded
-  caps - 20px in nav/buttons, 24px in features, 16px in inputs.
-- **Never redraw the logo; link a file out of `logo/`.** The lockup is `notambourine` set
-  in Nunito 800 beside the tambourine mark. Ship `logo/lockup.svg`, or its `-white` and
-  `-ink` reversals. Where the lockup will not fit - an avatar, an app icon, a stamp - use
-  `logo/monogram.svg`, the mark with `no` nested in the crescent; `logo/mark.svg` drops
-  the letters for a watermark or a bullet. `logo/lockup-text.svg` keeps the wordmark as
-  live `<text>` over an inlined ten-glyph Nunito subset - open that one to edit the type,
-  and re-run `scripts/build-logo.py` rather than hand-patching an outline.
-  `--font-wordmark` exists for the lockup and nothing else; a heading that reaches for it
-  is a bug.
-- **One pink word per headline**, via `<em>` - pink *and* italic. Hanken Grotesk ships a
-  drawn italic, so emphasis carries both and never a browser-faked skew.
-- **Every interactive element keeps a visible focus ring.** `tokens.css` ships it
-  (2px accent, 4px offset). Don't `outline: none` without replacing it.
-
-## Voice
-
-Concise, warm, playful - in that order.
-
-- **Register follows the artifact.** Site and marketing copy says **you** to the reader.
-  A client deliverable (deck, plan, README) says **we**, meaning the client's org with us
-  inside it. A proposal or SOW names the parties. Never "I".
-- **A client deliverable does not sell.** No logo wall, no team slide, no methodology.
-  Explain the client's own system back to them and let the restraint be the credential.
-- **Proof shows an observable change.** Use the client's own numbers where available.
-  Show what was blocked, what changed, and what their team can now own. Include reduced
-  operating burden and client independence. Without a number, describe a verifiable
-  before and after. Share client evidence only with permission.
-- **Make accountability personal.** Name who joins the engagement and who owns delivery.
-  Let warmth come through direct, helpful language about working together.
-- **Name the mess without blaming anyone for it.** The client lived every decision that
-  built it. Copy that indicts them loses the room.
-- **Express values as commitments.** Show what the client can count on:
-  direct access to the person responsible for delivery, ownership of estimating mistakes
-  within agreed scope, and work and operating knowledge that stay with their team.
-  Describe how coordination works instead of making jokes about ceremony.
-- **Four wordmark forms, and only four.** `NoTambourine` in every human-facing sentence.
-  `notambourine` is the technical slug, correct only in a path, URL, domain, GitHub org,
-  npm name, or CSS class. `NoTambourine LLC` is the legal entity and appears twice at most
-  in a contract - the signature block and one Definitions anchor - and nowhere else.
-  `Notambourine` and `No Tambourine` are not valid forms. The same rules are published for
-  outside agents at `notambourine.com/AGENTS.md`, so a disputed flag has a public citation.
-- **The signature is a sentence, not a wordmark.** In `Senior engineers. No tambourine.`,
-  `tambourine` is the instrument, lowercase, and the line stands alone - a tagline, a
-  slide, a sign-off, an email footer. Nothing else may split the wordmark across a space.
-- **Sentence case everywhere** - headlines, buttons, nav, labels. "Get started", not
-  "Get Started". The lockup renders lowercase.
-- **ALL CAPS has one job:** the pink eyebrow above a heading, tracked `+0.08em`. Never a
-  button, never body.
-- Five to twelve word sentences. No throat-clearing, no superlatives, no exclamation
-  marks in body.
-- **ASCII punctuation, with one unicode exception.** Hyphen, straight quote, straight
-  apostrophe. No em dash, no en dash, no curly quote, no single-character ellipsis. The
-  site source ships zero of each, and an em dash is the most reported AI tell in
-  marketing copy. The interpunct stays, because the brand uses it as a separator:
-  `Tom Fuertes · Principal · NoTambourine`.
-- **Yes:** "Senior engineers. No tambourine." · "Two engineers, six weeks, one shipped
-  feature." · "Tell us what you're building. We'll write back the same day."
-- **No:** "Unlock your team's full potential with our proven 7-phase framework!" ·
-  "results-driven, agile-first, AI-powered engineering studio"
-
-### Public copy carries no AI tells
-
-Read anything a stranger sees for these tells: hero, section body, email, deck,
-proposal, README. NoTambourine sells the absence of padding, so padded copy argues
-against the pitch. Four tells land hardest in consultancy copy:
-
-- Puffery adjectives. "Boutique" is specific and true; "proven", "world-class",
-  "results-driven", "battle-tested" are not. Cut the adjective and keep the number.
-- Importance-flagging. "This matters." "Speed is not a footnote." Show the consequence
-  instead.
-- The participle tail. "We ship in six weeks, ensuring your roadmap stays on track." Cut
-  at the comma.
-- Grandiose scope. "changes how you build", "the future of engineering". Scope it to a
-  claim a client could hold you to.
-
-Three brand fixtures read as tells and must survive the read:
-
-- **"Senior engineers. No tambourine."** A tailing negation plus a two-beat fragment,
-  both tells on their own. The line carries the name and the positioning, so it stays.
-- **A three-item line whose items are facts.** "Two engineers, six weeks, one shipped
-  feature" spends all three slots on numbers. A three-item line spending them on
-  adjectives is the tell.
-- **The single pink `<em>` in a headline.** Typographic emphasis, not the boldface tic.
-
-## Type and layout
-
-- **Headings** Hanken Grotesk 700, negative tracking - a serif holds a headline at 400
-  and a sans goes limp, so the weight is what reads as deliberate. 800 is the hero's, so
-  `.display` stays distinct from an ordinary `h1`. **Wordmark** Nunito 800, untracked,
-  the lockup only. **Accent** JetBrains Mono 600 for eyebrows, buttons, badges, nav.
-  **Body and mono** JetBrains Mono 400. Monospace body is the practitioner signal; it is
-  the point, not an accident. Every face is variable across its full axis, so no weight
-  here is ever synthesized.
-- **Keep the rounded lockup playful and the headings clear.** Use warm, direct language
-  throughout. Visual restraint should make the work easy to understand.
-- Body runs `1.7` leading and `+0.01em` tracking. Monospace at a sans's 1.55 reads cramped.
-- Tracking tightens as size grows: `--ls-tight` (-0.02em) is the floor, and `--ls-display`
-  (-0.03em) is what hero type above ~56px wants. Zero on body, +0.08em on ALL-CAPS eyebrows.
-- `text-wrap: balance` on headings, `pretty` on paragraphs. Always.
-- Body copy is a single column, max ~640px. Never full-viewport.
-- Card grids are 2 or 3 columns, single on mobile. Never 4.
-- 4pt grid. `--sp-16` between big blocks, `--sp-6` inside a card, `--sp-2` label-to-field.
-  When unsure, add room.
-- The nav is the only sticky element. No sticky CTAs, chat bubbles, or cookie banners.
-
-## Audit copy against all of the above
-
-Run this over anything a client or a stranger sees before it ships: deck, proposal, SOW,
-cover email, README, landing page, release note. The greps are a first pass that finds
-candidates. Every hit needs the rules above to judge it, which is why they live in one
-file with them.
-
-```bash
-# Wordmark: lowercase in prose, outside code, paths, and URLs
-grep -nE '(^|[^/.\-_a-z`])notambourine([^/.\-_a-z`]|$)' <file>
-
-# Sentence case: never a valid form
-grep -n 'Notambourine' <file>
-
-# Spaced form: never a valid form (lowercase is the instrument, in the signature line)
-grep -nE 'No[[:space:]]+Tambourine' <file>
-
-# Legal entity, 2x max (signature block + Definitions anchor)
-grep -nc 'NoTambourine LLC' <file>
-
-# Em dash, en dash, curly quotes, single-char ellipsis. Interpunct deliberately absent.
-perl -CSD -ne 'print "$.:$_" if /[\x{2014}\x{2013}\x{2018}\x{2019}\x{201C}\x{201D}\x{2026}]/' <file>
-
-# Puffery adjectives
-grep -niE '\b(proven|world-class|battle-tested|results-driven|cutting-edge|best-in-class|seamless|robust|leverage|synergy|holistic|bespoke)\b' <file>
-
-# Participle tails: cut the sentence at the comma
-grep -niE ',\s+(ensuring|enabling|allowing|helping|driving|empowering|delivering|providing)\b' <file>
-
-# Importance-flagging and throat-clearing
-grep -niE "\b(this matters|it's worth noting|it is worth noting|needless to say|at the end of the day|in today's)\b" <file>
-
-# Exclamation marks in body, and first person
-grep -nE '!(\s|$)' <file>
-grep -nE '\bI\b' <file>
-```
-
-Perl rather than `grep -P` for the punctuation pass. Stock macOS `grep` is BSD and
-rejects `-P`, so that flag only works where someone installed GNU grep. Escapes rather
-than literal characters, so this file stays ASCII and never trips its own check.
-
-Across a directory, or a staged diff so a flag lands on work in progress:
-
-```bash
-grep -rnE '(^|[^/.\-_a-z`])notambourine([^/.\-_a-z`]|$)' <dir>/ --include='*.md'
-
-git diff --cached | grep -nE '^\+.*[^/.\-_a-z`]notambourine[^/.\-_a-z`]'
-git diff --cached | perl -CSD -ne 'print if /^\+.*[\x{2014}\x{2013}\x{2018}\x{2019}\x{201C}\x{201D}\x{2026}]/'
-```
-
-Then read for the two tells no grep finds: **grandiose scope**, and a **three-item line
-spending its slots on adjectives** rather than numbers. Leave the three fixtures above
-alone - they read as tells and stay.
-
-**Ignore:** the slug in frontmatter, paths, URLs, CSS classes, npm names, GH remotes, and
-anything inside a code fence or backticks (the wordmark pattern already excludes them). A
-puffery word used literally about a thing rather than as a boast - "a robust error path".
-`I` inside a quotation, a code identifier, or a name.
-
-**Judge a hit two ways.** For the wordmark: would a client reading this expect the
-wordmark or the slug? A path, URL, or identifier is the slug, so ignore it. For
-everything else: would cutting this weaken the claim? If the sentence survives the cut,
-the words were padding.
-
-## Where truth lives
-
-**`notambourine/brand-kit` is the golden set.** `tokens.css`, `components.css`, and
-`deck.css` here are the brand's only corrected copy. Read a value from this file, correct
-a value in this file, and never sync one in. Anything that disagrees with it is downstream
-and stale, however it renders.
-
-A surface that cannot fetch at runtime pins this repo and reads the bytes out of the
-checkout - `share.notambourine.com` serves `tokens.css` and `deck.css` from its own origin,
-because a self-only CSP forbids a CDN. A pinned checkout is not a fork: the pin names one
-commit, and the consumer's CI fails when a `var()` reads a token this repo stopped
-declaring. Correct the value here and bump the pin.
-
-This skill is the complete system, so nothing has to be looked up elsewhere. It carries
-both themes: dark surfaces by default, and the light primitives behind `.theme-light`
-(`--nt-ink`, `--nt-white`, `--nt-line`, the pink and mint tints, `--nt-paper-warm`).
-A shipping surface may render dark only. That is a choice it made, not a shorter system.
-
-Every stylesheet here is native CSS with no build step, so they load into a plain HTML file,
-a Worker, an email template, or a React app unchanged. Write against the semantic layer -
-`--bg`, `--bg-card`, `--fg1`/`2`/`3`, `--fg-mute`, `--accent`, `--accent-fg`,
-`--accent-text`, `--support`, `--line`, `--sp-*`, `--r-*`, `--shadow-*`, `--ring-accent`,
-`--font-*`. It is the stable API and it
-survives a theme swap. The `--nt-*` primitives beneath it are the raw palette; reach past
-the alias to one only when no alias covers what you need, and never inline a literal
-color - `.theme-light` only works because no component hardcodes one. A `var()` fallback
-is the one place a literal is correct, and `deck.css` uses them: a renderer can receive
-that theme without `tokens.css` beside it, and the deck still comes out on brand.
-
-## Decks
-
-Grammar first: numbered eyebrow → lowercase display headline with one pink `<em>` word →
-short body → ALL-CAPS sublabel → typographic concept diagram → running footer. Every
-"image" is a diagram built from the same tokens. No photography, no icons standing in for
-a chart.
-
-`deck.css` is the theme that renders it. Markdown in, slides out, through Marpit: `---`
-splits a slide and `<!-- paginate: true -->` turns on slide numbers. Load `tokens.css` on
-the page too - `deck.css` declares no `:root`, so it reads its colors and faces from
-whatever the document root defines, and a brand correction reaches a deck with no second
-edit.
-
-The grammar above is CSS the theme ships, so a deck never writes its own `<style>` block.
-Reach for a class and never a hand-picked value: a deck is immutable once shared, so a hex
-typed into one is a brand value nothing can ever correct.
-
-| Write | Get |
-|---|---|
-| `<p class="eyebrow">01 &middot; the model</p>` | The numbered pink eyebrow. ALL CAPS is applied by the theme, so type it in sentence case. Use it again for the grammar's later sublabel. |
-| `# Headline with one *pink* word` | The display headline; `*emphasis*` in an `h1` or `h2` takes the accent and a drawn italic. |
-| `<!-- _class: lead -->` | The cover: centered, big lockup up top, no page number. One per deck. |
-| `<!-- _class: divider -->` | A turn in the story: one pink line, centered. This is the mid-deck section break, not `lead`. |
-| `<!-- _class: quote -->` | The whole slide as a pull quote, set in the display face. |
-| `<!-- _class: split -->` | The slide's bullet list in two columns, so eight short bullets fit where five did. |
-| `<!-- footer: acme &middot; august 2026 -->` | A running footer on every slide, clear of the mark and the page number. `header:` works the same at the top. |
-
-Every slide but an `![bg]` one carries the lockup bottom-left, from `--nt-lockup-url`. It
-is what identifies the deck once the PDF is an email attachment with no share link around
-it, so nothing has to be typeset: the brand name is never display type.
-
-`share.notambourine.com` runs this theme in its browser renderer and its PDF export, so a
-deck shared from there and a deck built by hand come out the same. It serves these bytes
-from a pinned checkout of this repo; correct a value here.
+Apply the brand without padding. Keep the design restrained and the work
+concrete.
+
+## Read only what the task needs
+
+- For visual design or styling, read [visual rules](references/visual.md),
+  including locked-surface font and logo traps.
+- For writing or auditing anything clients or the public see, read
+  [voice and copy audit](references/voice.md). Lead with its core framing and
+  use its supporting headline for existing systems.
+- For slide authoring or export, read [deck guidance](references/decks.md). Load
+  visual or voice guidance only when designing slides or writing/reviewing their
+  copy.
+- For a color, type, spacing, or component value, inspect the relevant CSS
+  directly. Do not load prose references for a value lookup.
+- For installation, asset selection, logo regeneration, or consumer integration,
+  read the relevant section of [README.md](README.md).
+
+## Source of truth
+
+Treat `notambourine/brand-kit` as canonical. Read values from its CSS and
+artwork from its assets. Correct brand values here, never by syncing a
+downstream copy back in. Update consumer pins after a correction; a consumer's
+limited theme support does not narrow the brand system.
+
+Use semantic CSS aliases. Reach for primitives only when no alias fits or the
+consumer integration requires it; consult README for framework exceptions. Never
+hardcode colors outside renderer `var()` fallbacks.
+
+Fetch fuller doctrine only when needed: `http://notambourine.com/llms.txt`
+indexes the public documents; `AGENTS.md` covers positioning and citation rules,
+`SOUL.md` beliefs, and `CULTURE.md` working practices. Use the local voice
+reference for current messaging. Do not infer internal policy from omissions in
+the public cuts. Keep client material unpublished; `/reports/` and `/pog/` are
+disallowed to agents.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@notambourine/brand-kit",
-  "version": "1.2.1",
-  "description": "The NoTambourine brand's golden set: tokens, element styles, deck theme, faces, and logo",
+  "version": "1.4.0",
+  "description": "NoTambourine brand assets and guidance for design, decks, and copy",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,17 +18,26 @@
   ],
   "author": "NoTambourine LLC",
   "type": "module",
+  "scripts": {
+    "format": "prettier --write \"**/*.{md,mdx,html,json,yml,yaml}\"",
+    "format:check": "prettier --check \"**/*.{md,mdx,html,json,yml,yaml}\"",
+    "prepack": "npm run format:check"
+  },
   "//": "No exports map: consumers import stylesheets and logo files by path, and their vendor scripts walk fonts/ and logo/ whole. A map would restate the tree and go stale the first time a file is added.",
   "files": [
     "*.css",
     "fonts",
     "logo",
-    "SKILL.md"
+    "SKILL.md",
+    "references"
   ],
   "publishConfig": {
     "access": "public"
   },
   "sideEffects": [
     "*.css"
-  ]
+  ],
+  "devDependencies": {
+    "prettier": "3.9.6"
+  }
 }

package/references/decks.md

@@ -0,0 +1,29 @@
+# Deck guidance
+
+Explain the client's system with typographic concept diagrams built from brand
+tokens. Do not substitute photography or icons for a chart.
+
+Use this slide grammar: numbered eyebrow, lowercase display headline with one
+emphasized word, short body, uppercase sublabel, concept diagram, running
+footer. Use `.eyebrow` for both labels and write their source in sentence case.
+Let the theme apply uppercase.
+
+Use one `lead` cover per deck. Use `divider` for later section breaks. Select
+existing theme classes for other slide shapes; inspect `deck.css` for their
+behavior. Never add a deck-local `<style>` block or hand-picked brand values.
+Shared decks are immutable artifacts, so embedded overrides cannot receive later
+brand corrections.
+
+Feed Markdown through Marpit. Separate slides with `---`, enable numbering with
+`<!-- paginate: true -->`, and select a slide variant with
+`<!-- _class: lead -->`. Use Marpit's `footer:` directive for the running
+footer.
+
+Load `tokens.css` on the containing page with `deck.css`. The theme reads the
+document root; its color fallbacks do not provide font faces or logo data. Do
+not mistake a deck that renders for one whose assets loaded.
+
+Keep the supplied lockup so an exported PDF identifies itself without the share
+page. Marpit's `![bg]` slides hide corner furniture, including that lockup;
+account for the loss when choosing that layout. Use the logo data URI variables
+for offline output, never retype the brand name in display type.

package/references/visual.md

@@ -0,0 +1,50 @@
+# Visual rules
+
+Keep confident type, one decisive pink, and enough air to make the work clear.
+Read exact values and component behavior from the CSS.
+
+- Default to dark. Use light surfaces deliberately and rarely, such as print,
+  press pages, or a one-off email. Never use pure white as a surface.
+- Use pink as the only accent, with one pink CTA per screen. Mint supports
+  structure, status, and supporting icons; never use it for a CTA.
+- Do not use gradients. One radial halo behind a hero lockup is the sole
+  exception; it must read as lighting.
+- Use flat, geometric, two-color imagery. No stock photography, AI imagery, or
+  hand-drawn textures. Ask for real assets when needed.
+- Keep corners consistent within a component. Use full card borders, never
+  colored left stripes.
+- Keep hover stationary. No parallax or looping animation. Preserve visible
+  focus rings when customizing controls.
+- Use Lucide SVG icons with rounded caps and a 1.75px stroke: 20px in
+  nav/buttons, 24px in features, 16px in inputs. No emoji in UI chrome or icon
+  fonts.
+- Use existing logo artwork; never redraw it. Follow README for asset selection
+  and regeneration. Reserve `--font-wordmark` for the lockup, never headings.
+  Monospace body is the practitioner signal; preserve it.
+- Emphasize one word per headline with `<em>`; preserve the supplied drawn
+  italic.
+- Keep body copy in one column, at most about 640px wide. Use two or three
+  columns for card grids, one on mobile, never four. Leave generous space
+  between blocks.
+- Make nav the only sticky element. No sticky CTAs, chat bubbles, or cookie
+  banners.
+
+## Locked surfaces
+
+Never substitute a Google Fonts import, including in mocks. It sends a referrer
+to a third party and violates a self-only CSP.
+
+When a surface cannot load local fonts, choose the degradation explicitly.
+Inline a supported face as a data URI when the surface warrants the bytes;
+always inline the wordmark subset when using live wordmark text. Otherwise use
+the fallback stacks from `vars.css` knowingly. Email clients and artifact hosts
+may reject font loading even when a page works locally.
+
+Inlining CSS moves relative font resolution to the HTML location. Preserve that
+relationship or embed the faces; copying styles alone is insufficient. Use
+README for normal package integration.
+
+A self-only CSP requires assets served from the consumer's origin or permitted
+embedded data, not a CDN. For a deck theme with no slide element to attach
+artwork to, use the supplied logo data URI variables. A PDF or offline snapshot
+cannot rely on an origin to retrieve artwork.

package/references/voice.md

@@ -0,0 +1,137 @@
+# Voice and copy audit
+
+Lead public-facing pages and introductions with this core framing:
+
+> Build the systems and ways of working your business needs next.
+
+For a supporting headline about existing systems, use:
+
+> Make your systems work harder for your business.
+
+Follow each headline with the work we will deliver and its business value. Write
+concisely, warmly, then playfully, in that order.
+
+## Positioning and offers
+
+Position NoTambourine as senior engineers who work inside the client's team and
+take responsibility for delivery. Lead with the client's business goal and the
+engineering work needed to reach it. Connect technical infrastructure with the
+processes it supports. Show how better systems let a team handle more work
+without adding manual steps. AI at the keyboard explains small-team economics;
+it is not the offer.
+
+Define fit by the intended result and the responsibility taken on. Mention
+private-equity experience when relevant; keep general positioning open to any
+ownership structure. The name means no padding.
+
+Help referred readers confirm fit and explain the agency to colleagues. Keep the
+signature beside a concrete explanation. Use this introduction:
+
+> Build the systems and ways of working your business needs next. NoTambourine
+> brings senior engineers into your team to lead delivery.
+
+For a meta description or short directory listing, use:
+
+> Senior engineers working inside your team to build the systems and ways of
+> working your business needs next.
+
+Give recognizable reasons to call: upgrading core systems, automating routine
+work, or connecting systems so teams can act on current information. Connect
+each to the work we can deliver. Describe infrastructure improvements through
+the change in daily work: files arrive automatically, orders move between
+systems, or a team can release updates more easily. Use examples that match the
+engagement. Support claims of growth, time saved, or reliability with client
+evidence.
+
+Keep public positioning open to ambition as well as an existing constraint. In
+discovery, ask what they want to accomplish, why now, and what successful
+delivery would change. Name constraints once the client has described them or
+the evidence establishes them. In a proposal, connect that specific constraint
+to its business consequence and the work required.
+
+Use these offer names and lead with outcomes:
+
+- **Assessment:** Decide what to build or change first. Review the technology
+  and working processes against your business priorities and choose the next
+  investment.
+- **Embedded:** Put senior engineers inside your team to lead delivery. Build
+  the systems and ways of working your business needs next.
+
+Use "Start a conversation" for the primary invitation. Ask what the reader wants
+to accomplish and when. Discuss fit before asking them to choose an engagement.
+
+## Register and evidence
+
+- Address marketing readers as "you". In client deliverables, use "we" for the
+  client's organization with us inside it. Name the parties in proposals and
+  SOWs. Never use "I" as the author's voice.
+- Do not sell in client deliverables: no logo wall, team slide, or methodology.
+  Explain their system back to them.
+- Show the client's objective, what changed, and what they can now do. Use their
+  numbers when available, otherwise a verifiable before and after. Connect
+  delivered work to commercial and operational results when supported. Share
+  client evidence only with permission.
+- Name who joins and takes responsibility for delivery. Express values as
+  commitments: direct access to the responsible person and covering our
+  estimating mistakes within agreed scope.
+- Describe constraints without blaming the people who built the system. Explain
+  coordination without jokes about ceremony.
+
+## Names and mechanics
+
+Use `NoTambourine` in human-facing sentences. Reserve `notambourine` for
+technical slugs, paths, URLs, domains, GitHub organizations, npm names, and CSS
+classes. Use `NoTambourine LLC` only in contracts, at most twice: one
+Definitions anchor and the signature block. Reject `Notambourine` and
+`No Tambourine`. Cite the public `AGENTS.md` for disputed naming flags.
+
+Preserve `Senior engineers. No tambourine.` as a standalone signature: tagline,
+slide, sign-off, or footer. The instrument is lowercase. This is the only
+permitted spaced form.
+
+Use sentence case for headlines, buttons, navigation, and labels. Reserve
+uppercase for pink eyebrows; decks also use that treatment for sublabels. Follow
+deck guidance for lowercase display headlines. Keep sentences short without
+forcing a uniform rhythm. No throat-clearing, superlatives, or exclamation marks
+in body copy.
+
+Use ASCII punctuation: hyphens and straight quotes/apostrophes. No em/en dashes,
+curly quotes, or single-character ellipses. Permit the interpunct as a
+separator, as in `Tom Fuertes · Principal · NoTambourine`.
+
+## Audit before shipping
+
+Audit anything clients or strangers see: pages, email, decks, proposals, SOWs,
+READMEs, and release notes. Search for candidates, then judge them in context:
+
+Check the opening first. It should name work the reader wants done and explain
+our responsibility. Remove assumed pain, unearned urgency, and claims that could
+describe any agency. Keep technical constraints where they explain a specific
+decision or result.
+
+```sh
+rg -n 'notambourine|Notambourine|No\s+Tambourine|NoTambourine LLC' <file>
+rg -n '[\x{2014}\x{2013}\x{2018}\x{2019}\x{201C}\x{201D}\x{2026}]' <file>
+rg -ni '\b(proven|world-class|battle-tested|results-driven|cutting-edge|best-in-class|seamless|robust|leverage|synergy|holistic|bespoke)\b' <file>
+rg -ni ',\s+(ensuring|enabling|allowing|helping|driving|empowering|delivering|providing)\b' <file>
+rg -ni "this matters|it's worth noting|it is worth noting|needless to say|at the end of the day|in today's" <file>
+rg -n '!(\s|$)|\bI\b' <file>
+```
+
+Check legal-name occurrences against the contract limit. Ignore technical slugs
+and code when judging wordmark hits; searches do not understand Markdown fences
+or backticks. Ignore literal technical uses such as "a robust error path" and
+`I` in quotations, identifiers, or names.
+
+Cut puffery and keep evidence. Replace importance-flagging with the consequence.
+Cut participle tails at the comma. Read manually for grandiose scope and
+three-item adjective lists; narrow claims to something a client can hold us to.
+If cutting words leaves the claim intact, remove them.
+
+Preserve three fixtures even when they resemble padding: the signature, factual
+three-item lines such as "Two engineers, six weeks, one shipped feature", and a
+headline's single pink `<em>`. Typographic emphasis is not a boldface tic.
+
+Format source documents with Prettier before sharing or exporting, including
+Markdown. Use the repository's pinned version and configuration. Review the
+rendered document after formatting, especially slide breaks and tables.