How to use

Every way to apply a brand, palette, or font from brand-atoms.com to a real project. Not installed yet? Install the CLI or read the direct HTTP fetch pattern.

For AI agents

Render in-brand output every time. Brand Atoms gives you a deterministic contract — pick the format that matches your runtime.

Resolve a brand. Address by <slug>@<version>. At build time the encyclopedia emits nine formats per brand under /dist/brands/<slug>/<version>/.
Pick a format. JSON for agents and scripts; W3C tokens for Figma / Style Dictionary; CSS for direct drop-in; Swift / Kotlin for native.
Read the rules. Iterate brand.rules and treat each typed constraint as a check. severity: error rules MUST hold; severity: recommendation rules SHOULD hold — explain any deviation.
Pin versions. Reference by exact version ([email protected]) for reproducibility, or by major (convergent-systems@1) to ride non-breaking updates.

fetch a brand · JSON

curl https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/json/brand.json

prompt pattern · system instruction

The user's brand is "[email protected]". Fetch
https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/json/brand.json
before generating. Honor every roles.colors mapping verbatim,
respect every rules entry, and use references.fonts for type.

For humans

Three paths, depending on what you want to do.

I want to learn a brand.

Go to /brands. Each brand has a live preview (components rendered in the brand's actual palette and fonts), a downloadable spec, and a full role + rule breakdown.

I want to reuse an atom.

Browse /palettes or /fonts. Filter by hex, classification, license, or mode coverage. Reference by slug@version.

I want to build a new brand.

Go to /builder. Pick a palette and three fonts; preview live in both modes; download the brand.yaml or the full nine-format zip. All client-side.

Recipes

Concrete worked examples for each consumer. Substitute [email protected] with the brand you want.

Tailwind project — one command

Inject a brandatom color block into theme.extend.colors. brandatom detects tailwind.config.* and writes in place.

shell

cd my-tailwind-app
brandatom brand [email protected] apply --dry-run    # preview the diff
brandatom brand [email protected] apply              # commit the change

Then use bg-brand-primary, text-brand-on-identity, bg-swatch-clay, font-heading, etc. in your markup.

Next.js / React — manual import

Drop the CSS into your root layout. The custom-property tokens flow through any component that reads var(--color-primary).

app/layout.tsx

import './brand.css';

export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>;
}

app/brand.css

@import url("https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/css/tokens.css");

Or bundle the file locally for offline / production: curl -o app/brand.css \ https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/css/tokens.css

Vanilla HTML / CSS site

Add one <link> to <head> and reference the custom properties from any stylesheet.

index.html

<link rel="stylesheet"
      href="https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/css/tokens.css">

site.css

body {
  background: var(--color-background);
  color: var(--color-text-primary);
  font-family: var(--font-body);
}
.cta { background: var(--color-primary); color: var(--color-background); }
h1 { font-family: var(--font-heading); }
code { font-family: var(--font-mono); }

Need the full role set including on-identity, mark, and dark-mode-specific roles? Use the Tailwind or SCSS emitter — the CSS emitter resolves to the active mode only.

iOS — Swift

Inside an *.xcodeproj directory, the CLI emits a Brand.swift with UIColor extensions next to the project.

shell

cd MyApp
brandatom brand [email protected] apply --format swift

Or fetch directly: curl -o Brand.swift https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/swift/BrandTokens.swift

Android — Kotlin / XML

Detects app/src/main/AndroidManifest.xml and writes app/src/main/res/values/brand-atoms.xml.

shell

cd MyAndroidApp
brandatom brand [email protected] apply --format android

Reference in Kotlin via R.color.bra_primary after a Gradle sync. Pure Kotlin tokens also available at /dist/brands/convergent-systems/1.0.0/kotlin/BrandTokens.kt.

Figma — via Tokens Studio / W3C Design Tokens

Brand Atoms emits DTCG-spec tokens. Import the file into the Tokens Studio plugin and Figma variables sync.

shell

curl -o brand.tokens.json \
  https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/w3c/tokens.json

In Tokens Studio: Tools → Load from file → pick brand.tokens.json. Light and dark modes are split into tokens.light.json and tokens.dark.json in the same folder.

Style Dictionary — multi-platform pipeline

Treat the W3C tokens file as a source and let Style Dictionary fan out to iOS / Android / web / whatever.

config.json

{
  "source": ["tokens/*.json"],
  "platforms": {
    "web":    { "transformGroup": "css",     "buildPath": "build/web/" },
    "ios":    { "transformGroup": "ios",     "buildPath": "build/ios/" },
    "android":{ "transformGroup": "android", "buildPath": "build/and/" }
  }
}

Drop the fetched tokens.json into tokens/ and run style-dictionary build.

Tailwind — manual (no CLI)

Fetch the pre-built tailwind.config.cjs snippet and merge it into yours by hand. Useful in CI where you can't run the binary.

shell

curl https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/tailwind/tailwind.config.cjs

SCSS pipeline

SCSS variables for projects that haven't migrated to custom properties.

_brand.scss

@import url("https://brand-atoms.com/dist/brands/convergent-systems/1.0.0/scss/_tokens.scss");

.card { background: $brand-surface; color: $brand-text-primary; }

Apply a palette only — no brand

Sometimes you want the colors without the brand's role mappings and rules. Palettes ship the same way, under /dist/palettes/.

shell

curl https://brand-atoms.com/dist/palettes/catppuccin-mocha/1.0.0/json/palette.json
curl https://brand-atoms.com/dist/palettes/tailwind-v3/1.0.0/css/tokens.css

Apply a font — discover the CDN URL

Fonts ship with resolved CDN URLs. Read the atom, drop the URL into a <link> or @font-face block.

shell

curl https://brand-atoms.com/dist/fonts/inter/1.0.0/json/font.json | jq .cdnUrl

Or browse /fonts and copy the URL from the detail page.

Browse from the terminal

Quick discovery without leaving the shell.

shell

brandatom brands list                         # all brands with primary swatches
brandatom palettes list                       # all palettes with swatch previews
brandatom fonts list                          # all fonts with specimen line
brandatom brand [email protected] show          # streams resolved JSON to stdout
brandatom brands list --json | jq '.[].slug' # machine-readable

Compose a new brand in the browser

/builder is a client-side composer. Pick a palette and three fonts; toggle light / dark; preview a card, a button, a heading; download brand.yaml or the full nine-format zip.

Nothing uploaded, no account. To publish to the encyclopedia, open a PR or use /request-brand.

Output formats

Nine emitters per brand. Pick the one that matches your toolchain.

Format	File	Best for
YAML	`yaml/brand.yaml`	Source-of-truth; human-editable; same as the repo.
JSON	`json/brand.json`	AI agents, scripts, anything that parses JSON natively.
W3C Design Tokens	`w3c/tokens.json` + light / dark	Figma, Style Dictionary, Tokens Studio, anything DTCG.
CSS variables	`css/tokens.css`	Direct drop-in for any web project with `prefers-color-scheme`.
Tailwind	`tailwind/tailwind.config.cjs`	Tailwind projects that want brand colors as utility classes.
SCSS	`scss/_tokens.scss`	SCSS pipelines that need `$brand-primary`-style vars.
Figma tokens	`figma/tokens.json`	Direct Figma variable import (separate dialect from W3C).
Swift	`swift/BrandTokens.swift`	Native iOS; emits `UIColor` extensions.
Kotlin	`kotlin/BrandTokens.kt`	Native Android; emits typed color constants.
Markdown	`markdown/brand-guide.md`	Human-readable brand guide; pastes into Notion / Confluence.

Every emitter resolves the brand fully — palette references, font CDN URLs, asset paths, role overrides. You're never re-resolving in your runtime.

Extending the catalog

Brand Atoms is open source. Adding an atom or brand is a typed YAML diff in git.

Pick a kind. New palette → palettes/<slug>/<semver>/atom.yaml. New font → fonts/<slug>/<semver>/atom.yaml. New brand → brands/<slug>/<semver>/brand.yaml.
Match the schema. Schemas live in tools/schemas/. Zod validates every file at build time; a missing required field fails the deploy.
Cite a source. Every atom carries a provenance block (source URL, license, attribution, import date). No fabricated colors, no ghost fonts.
Open a PR. CI runs pnpm validate on every push; merge to main triggers a deploy.

Repo: github.com/convergent-systems-co/branding-library.

Don't want to open a PR yourself? Request a brand — provide a public webpage and a maintainer triages by hand.