Bounded Systems — Brand

Identity assets and design tokens for Bounded Systems. Bounded authority for AI agents — drawn at the door, not the process or container.

The mark is the capability model made physical: a room (the boundary), a door (the gap — one sanctioned unit of authority), and an agent (the guest, sitting low near the door).

brand/
├── tokens/
│   ├── tokens.json        ← SOURCE OF TRUTH (W3C design tokens)
│   ├── tokens.css         ← generated CSS variables + text styles (do not hand-edit)
│   └── build-tokens.mjs   ← generator; `--check` fails CI on drift
├── css/                   ← ready-to-link stylesheets for web consumers
│   ├── fonts.css          ← @font-face Space Grotesk + IBM Plex Mono (self-hosted)
│   ├── fonts/             ← the woff2 files (OFL, latin subset) — no external CDN
│   └── base.css           ← resets + element defaults on the tokens
├── mark/                  ← logo only, transparent
│   ├── mark-white.svg     ← on forest / dark
│   ├── mark-forest.svg    ← on light
│   └── *-1024.png
├── avatar/                ← square masters (surfaces mask to rounded/circle)
│   ├── avatar-forest.svg  ← recommended
│   ├── avatar-light.svg
│   └── avatar-{forest,light}-{200,280,420,460,1024}.png
├── lockup/                ← wide link-card lockup (OG 1.91:1, 1200×630)
│   ├── lockup-forest.svg  ← repo social preview
│   └── lockup-light.svg
├── favicon-32.png
├── style-dictionary.config.mjs  ← native / Figma outputs → dist/ (gitignored)
└── package.json           ← build:css · check · build:sd

Tokens

tokens.json is the only file you edit. Everything else is generated.

node tokens/build-tokens.mjs          # regenerate tokens.css
node tokens/build-tokens.mjs --check  # exit 1 if tokens.css is stale (CI)

Wire the check into the pipeline so the CSS can never drift from the JSON:

# .github/workflows/tokens.yml (sketch)
- run: node brand/tokens/build-tokens.mjs --check

Layers

| Layer | What | Example | | --- | --- | --- | | Primitive token | one named value | color.forest = #0C5A42 | | Text style (composite) | a recipe bundling primitives | text.label → mono + 11px + 0.14em + uppercase | | Component | the mark, built from tokens | mark/*.svg |

The slug / eyebrow ("AVATAR SYSTEM · v1") is the text.label style — not a single token, but a composite that references font.mono, size.text-label, etc. Consume it as the .bs-text-label class or read its parts from JSON.

Consuming

CSS / web — import the generated variables and styles:

@import "brand/tokens/tokens.css";
.eyebrow { } /* or just add class="bs-text-label" */
h1        { color: var(--bs-color-ink); }

Anything that can't read CSS (native iOS/Android, email, Figma, print) reads tokens.json directly, or builds a platform output from it via Style Dictionary:

npm install
npm run build:sd   # → dist/{tokens.scss,tokens.js,tokens.flat.json,Tokens.swift,tokens.xml}

tokens.css stays the curated web artifact (it carries the composite .bs-text-* classes); Style Dictionary covers everything else. dist/ is gitignored — it's generated, never committed. JSON is the source; every CSS, SCSS, JS, Swift, and XML file is a derived artifact.

As a package — depend on @bounded-systems/brand (npm) and import by path:

import tokens from "@bounded-systems/brand/tokens.json" with { type: "json" };

@import "@bounded-systems/brand/tokens.css";

Deployed token bundle (a contract, not a dump)

npm run tokens:dist assembles dist/tokens-site/ and deploy-tokens.yml publishes it to a stable URL on every release. The bundle is a versioned, content-addressed contract:

tokens-site/
├── manifest.json     ← the contract — validates against tokens/manifest.schema.json
├── tokens.json       ← canonical DTCG source  (application/design-tokens+json)
├── tokens.css        ← CSS variables           (text/css)
├── tokens.scss · tokens.js · tokens.flat.json · Tokens.swift · tokens.xml

manifest.json declares every projection with its IANA media type and SHA-256, plus the package version and (in CI) the source commit. A consumer fetches the manifest, picks a format, and verifies the bytes by hash — integrity over freshness. node tools/build-tokens-dist.mjs --check gates DTCG conformance and the contract shape in CI, so the deployed surface can't drift from the spec.

Fonts: Space Grotesk + IBM Plex Mono (Google Fonts).

Palette

| Token | Hex | Use | | --- | --- | --- | | forest | #0C5A42 | primary fill, mark on light | | forest-deep | #073D2C | pressed / deep | | forest-tint | #E2EBE6 | subtle tinted surface | | forest-soft | #D2E0D8 | fills / borders on tinted surfaces | | paper | #EDEAE1 | app background, warm | | card | #FFFFFF | card surface (aliases white) | | card-alt | #F4F1EA | light avatar fill | | ink | #16221C | primary text | | ink-soft | #5C6B63 | secondary text | | ink-mono | #5E6B62 | mono label / slug text (WCAG-AA on paper) | | line | #E4E0D4 | hairline borders | | white | #FFFFFF | mark on forest | | clay | #A6432F | accent / negative | | clay-tint | #F2DED8 | negative surface | | amber | #B5762A | caution / highlight | | amber-tint | #F3E8D6 | caution surface |

Grade colors

Status colors for graded claims (Enforced · Partial · Aspirational). Only the base is authored in tokens.json; build-tokens.mjs derives the -bg (light surface), -fg (readable text), and -on-dark ramps deterministically, so consumers get the full set as --bs-grade-* variables.

| Token | Hex | Use | | --- | --- | --- | | grade-enforced | #3FB984 | proven / enforced in running code | | grade-partial | #C8902F | partially enforced | | grade-aspirational | #7E8C83 | aspirational / not yet enforced |

Token accessibility

Token-level accessibility is a gated contract, not a vibe. The brand vendors the Token Accessibility suite from bounded-systems/conformance-kit (hash-pinned in vendor/conformance-kit/, PR #25), and one config — tokens/token-a11y.json — drives every member over the generated tokens.css:

| Member | Checks | WCAG | | --- | --- | --- | | palette | CVD-safe contrast (deutan/protan/tritan), APCA, non-text | 1.4.3 / 1.4.11 | | pairing | derives fg×bg pairings from the brand CSS ∪ declared set (report-only superset) | — | | typography | body line-height ≥1.5, overridable spacing, min size, weight×size | 1.4.12 / 1.4.4 / 1.4.8 | | target-size | interactive-target tokens ≥24×24; ≥44 status | 2.5.8 AA / 2.5.5 AAA | | opacity | EFFECTIVE composited contrast of any translucent foreground | 1.4.3 / 1.4.11 | | likeness | near-duplicate hygiene + categorical distinctness (normal + CVD) | 1.4.1 |

npm run token-a11y         # verify the vendor hash-pin, then run the whole suite
npm run token-a11y:check   # rebuild tokens.css first, then run (the CI entrypoint)
npm run token-a11y:verify  # only verify the vendored suite against its hash-pin

Fail-closed (exit 1) on any gated-member failure. No exemptions — hairlines, dividers, and separators are declared ui and must clear 3:1; accessible for everyone. CI: .github/workflows/token-a11y.yml.

Interactive-target (control) tokens

So every surface has an accessible pointer-target token to reach for (WCAG 2.5.8):

| Token | Value | Use | | --- | --- | --- | | control-min-tap-target | 24px | SC 2.5.8 (AA) floor — apply as min-width/min-height on any control | | control-sm | 36px | compact control (chips, dense toolbars) | | control-md | 44px | default control — also meets 2.5.5 (AAA, 44px) | | control-lg | 52px | prominent / primary control |

Avatar usage

• Upload avatar/avatar-forest-460.png as the GitHub org avatar (or the SVG master). GitHub masks to rounded-square / circle itself — the mark sits inside a ~16% safe area so the door never clips.
• Forest is the hero treatment. Light is for placing on dark/photographic backgrounds.
• Don't recolor the mark, rotate it, add effects, or close the door gap.
• Below 20px, prefer favicon-32.png.

Link cards / social preview

The square avatar center-crops badly on wide (~1.91:1) social/link cards and clips the door. Use the dedicated wide lockup instead:

• Set lockup/lockup-forest-1200.png as the repo's social preview (Settings → Social preview). lockup-light-* is for light/photographic contexts.
• 1200×630 (OG), mark + wordmark + slug + tagline, with safe margins.
• SVG masters carry live text; the *-1200.png rasters (Space Grotesk + IBM Plex Mono baked in) are what social/link cards should point at — most platforms (Slack, X, iMessage) won't render an SVG OG image.