AI Guardrails · Snyder brandOS

Manifesto

“The AI can ship a thousand UIs an hour. The brand only survives ifevery single one of them reaches for the token before the literal.”

Tokens inLiterals outReuse over rebuild

01 · Allowed

What AI may reach for

These are the only inputs AI-generated UI is allowed to touch.

Colors

DaisyUI semantic classes & brandOS CSS variables.

bg-base-100bg-primarytext-base-contenttext-primaryborder-base-300text-successtext-error

Scales

Raw brand scales via CSS variables only.

--brandOS-primary-*--brandOS-gray-*

Typography

Sizes, weights, families, and leading tokens.

--brandOS-text-*--brandOS-font-*--brandOS-leading-*

Spacing

15-step rhythm scale. No ad-hoc px values.

--brandOS-space-{0…24}

Radius

Seven slots from sm to full.

--brandOS-radius-smdefaultmdlgxl2xlfull

Shadow

Five elevation steps authored in OKLCH.

--brandOS-shadow-sm → xl

Motion

Durations and easings from the token set.

--brandOS-duration-*--brandOS-ease-*

Components

Reuse brandOS/ui before touching primitives.

<brand-button><brand-card>…

SVG assets

Registered, optimized SVGs through exact canonical subpath imports.

<file>.svg?react<file>.svg?raw<Icon name="…" />

02 · Forbidden

What AI must never emit

Every row shows the anti-pattern on the left and its token-backed fix on the right.

Hex literals

Never#2aa5ea

Usevar(--brandOS-primary-500)

RGB / HSL literals

Neverrgb(42, 165, 234)

Usevar(--color-primary)

Inline style="" visuals

Neverstyle="color: red"

Useclass="bos:text-error"

Emoji in UI

Never✅ Saved

Use<Icon name="check" />

Custom alias vars

Never--app-text-primary: …

UseUse semantic tokens directly.

Tailwind dark: variants

Neverdark:bg-gray-900

Usedata-theme on <html> wins.

Default Tailwind palette

Neverbg-blue-500

Usebg-primary or --brandOS-primary-*

Arbitrary color values

Neverbg-[#2aa5ea]

Usebg-primary-500

Local SVG as <img>

Never<img src="cog.svg" />

Use<Icon name="cog" /> · or a pinned brand.snyder.tech/cdn URL for fixed-color brand logos

Per-app vector-graphics

Neversrc/vector-graphics/logo.svg

Useimport from '@brandos/ui/assets/...svg?raw' or load from the versioned CDN

Aggregate asset barrel

Neverimport { logo } from '@brandos/ui/assets'

UseImport the exact '@brandos/ui/assets/<category>/<file>.svg?react' path

Unregistered SVG assets

Neversrc/assets/new-logo.svg

UseRegister ownership in brandOS/registry, then run brandos-svg-check

Mismatched logo frames

NeverLight and dark variants use different viewBoxes

UseNormalize every variant to one shared viewBox without stretching artwork

Unclassified inline SVG

Never<svg> without accessible semantics

UseAdd informative role + name, or decorative aria-hidden + focusable=false

03 · Reuse ladder

Three rungs, in order

AI climbs this ladder in order. Only fall off the top rung when 01 and 02 genuinely don’t fit.

Reuse

Search brandOS/ui/src/components/ for an existing match.

Wrap

Wrap a Shoelace or DaisyUI primitive and apply brand tokens to it.

Compose

Compose a new component only if 01 & 02 fail. Open a PR to promote it.

04 · Prompts

Copy these into your AI session

Prompt fragments that pin Claude Code, Cursor, or Copilot to the rules on this page.

Base prompt fragment

When generating UI in this repo:
- Reach for semantic tokens first: brandOS CSS variables (--brandOS-*, --semantic-*, --color-*). Use whichever utility layer the host app ships (DaisyUI, bos: Tailwind, MUI sx, etc.) - never the raw token name in markup.
- No hex, rgb, rgba, hsl literals. No inline style for colors, backgrounds, typography, spacing, or shadows. Dynamic, data-driven values (per-row swatch backgrounds, etc.) are the only exception.
- No emoji in UI - use Lucide, Heroicons, or inline SVG.
- Brand logos, marks, and icons use exact @brandos/ui/assets/<category>/<file>.svg?raw imports (or a pinned versioned brand.snyder.tech/cdn URL for fixed-color logos/wordmarks) - never the aggregate barrel or per-app vector-graphics folders.
- Prefer the currentColor <brand>-logo-ink.svg variant inline so it inherits the theme; use fixed-color -light/-dark only where currentColor cannot apply (e.g. an <img> tag).
- Every light, dark, and ink logo variant must share one normalized viewBox. Preserve artwork proportions; never stretch a mark to fill its frame.
- Reusable SVGs must be registry-owned, match the repository multipass SVGO output, and pass just brandos-svg-check --report.
- Informative inline SVGs require role="img" and an accessible name. Decorative inline SVGs require aria-hidden="true" and focusable="false". SVG <img> consumers require alt text, including alt="" for decorative images.
- Never load a LOCAL SVG as <img src="*.svg"> - inline it so it inherits currentColor (use <Icon name="..." /> or Fragment set:html). Fixed-color brand logos/wordmarks may load via <img> from the pinned, immutable, versioned brandOS CDN.
- Prefer an existing brandOS/ui component, then a host primitive (Shoelace / MUI / DaisyUI), before composing anything new.
- Theme switching is driven by the data-theme attribute on <html> - do not add Tailwind dark: variants or fork CSS per mode.
- If a required token does not exist, stop and ask rather than inventing one.

Component request fragment

Produce the component using only tokens listed on the AI Guardrails page. If the component already exists under brandOS/ui, import it instead of recreating it.

05 · Enforcement

How we keep AI honest

Five layers, from agent instructions to source and asset verification, work together.

Agent config

CLAUDE.md + AGENTS.md

Every AI session auto-loads the rules on this page.

Machine-readable

llms.txt · llms-full.txt

External AI clients can discover and pin the contract.

Code review

PR approval gate

Reviewers reject any forbidden pattern. First offense coached.

Lint

Oxlint brand guardrails

Rejects forbidden literals, asset barrels, inaccessible SVG consumers, and new reusable inline SVG markup.

Asset verification

brandos-svg-check

Rejects unsafe, unregistered, unoptimized, malformed, or geometrically inconsistent SVG assets.