Install

01 · CDN bundles

Pick the right file

Production apps load exactly two files: global-tokens.css plus the one<brand>-brand.css they ship. That pairing is roughly 42 KB raw, under 7 KB gzipped. brand-all.css carries every published brand theme at 2.7 MB raw and 158 KB gzipped, so keep it to prototypes and brand-switching demos.

Every bundle is served from an immutable, exact version path such as/cdn/0.44.11/…. There is no /cdn/v1/ path; only concrete versions and the rolling latest alias resolve, and latest is not a production path.

02 · Framework snippets

Copy-paste for your stack

Every snippet produces the same runtime. Pick your stack, click copy.

<!DOCTYPE html>
<html data-brand="snyder" data-theme="light">
  <head>
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/global-tokens.css">
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/snyder-brand.css">
  </head>
  <body>
    <button class="bos:dui-btn bos:dui-btn-primary">Ship it</button>
  </body>
</html>

<!-- src/layouts/BaseLayout.astro -->
<html data-brand="snyder" data-theme="light">
  <head>
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/global-tokens.css">
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/snyder-brand.css">
    <slot name="head" />
  </head>
  <body><slot /></body>
</html>

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html data-brand="snyder" data-theme="light">
      <head>
        <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/global-tokens.css" />
        <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/snyder-brand.css" />
      </head>
      <body>{children}</body>
    </html>
  );
}

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      htmlAttrs: { 'data-brand': 'snyder', 'data-theme': 'light' },
      link: [
        { rel: 'stylesheet', href: 'https://brand.snyder.tech/cdn/0.44.11/themes/global-tokens.css' },
        { rel: 'stylesheet', href: 'https://brand.snyder.tech/cdn/0.44.11/themes/snyder-brand.css' },
      ],
    },
  },
});

<!-- index.html -->
<html data-brand="snyder" data-theme="light">
  <head>
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/global-tokens.css">
    <link rel="stylesheet" href="https://brand.snyder.tech/cdn/0.44.11/themes/snyder-brand.css">
  </head>
  <body><app-root></app-root></body>
</html>

03 · Theme activation

Drive everything from <html>

Every theme decision lives on the root element. Never re-theme per-component, flip one attribute and all tokens follow.

04 · Version pinning

Pick your update cadence

Every CDN path is pinned to an exact version and is immutable once published. Published objects are never rewritten or deleted, so a pinned URL keeps rendering the same bytes forever. You opt in to an update by editing the version in the URL.

05 · Verify

Confirm brandOS loaded

Paste into the DevTools console. You should see a real OKLCH value, not an empty string.

getComputedStyle(document.documentElement)
  .getPropertyValue('--brandOS-primary-500')
  .trim();
// → "oklch(0.72 0.1557 239.5)"

06 · Common pitfalls

When something looks off

Common integration and SVG delivery issues, with the canonical fix for each.

07 · SVG assets

Import the asset, preserve the artwork.

Reusable logos, marks, icons, illustrations, shapes, and backgrounds belong inbrandOS/ui/src/assets. Resolve the owning registry entry first, then import the exact file instead of the aggregate asset barrel.

import Logo from '@brandos/ui/assets/brand-logos/acme-logo-ink.svg?react';

export function HeaderLogo() {
  return <Logo role="img" aria-label="Acme" />;
}

• Use -logo-ink.svg inline when the artwork should inherit currentColor.
• Use registered -logo-light.svg and -logo-dark.svg files for fixed-color contexts. Both variants must share one viewBox.
• Decorative inline SVGs require aria-hidden="true" and focusable="false". Informative SVGs require role="img" and an accessible name.
• Do not add root sizing or preserveAspectRatio mechanically. Choose behavior from the asset class and test multiple viewport sizes.
• Before review, run just brandos-svg-check --report and just brandos-assets-check --report.

08 · Agent skills + Office artifacts

Connect without auth. Install with review.

The activation-ready public endpoint is https://brand.snyder.tech/mcp. It serves read-only catalog metadata, immutable URLs, byte sizes, and SHA-256 values. It remains unavailable until a public-approved artifact catalog is published.

Open the complete no-auth setup guide for Codex, Claude Code, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI, and generic Streamable HTTP clients.

MCP cannot write a Skill to your computer. Resolve an exact version, display and approve its immutable URL, byte size, SHA-256, and unsigned status; download the singleSKILL.md into a temporary directory; verify its digest; inspectSKILL.md, then copy atomically into one local skill root. Never usecurl | sh, npx, source, or server-returned install commands.

Read the complete Office Artifact Kit and safe skill-install contract.

09 · Next

Where to go from here

• AI Guardrails, the non-negotiable rules for any generated UI.
• Brand components, 26 first-party web components that drop in over the CDN link.
• Downloads, logos, fonts, raw tokens.css + tokens.js.
• Office Artifact Kits, per-brand DOCX, PPTX, XLSX, manifests, and portable Agent Skills.
• MCP Connection Guide, copyable no-auth setup for common AI harnesses.
• llms-full.txt, machine-readable contract for AI assistants.