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

Canonical logos, marks, and icons from @brandos/ui/assets.

brandLogosbrandFaviconssocialAssetsiconsiconsRaw<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

SVG as <img>

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

Use<Icon name="cog" />

Per-app vector-graphics

Neversrc/vector-graphics/logo.svg

Useimport { brandLogos } from '@brandos/ui/assets'

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 come from @brandos/ui/assets - never re-add per-app vector-graphics folders.
- Never load SVGs as <img src="*.svg"> - inline the SVG content so it inherits currentColor (use <Icon name="..." /> or Fragment set:html).
- 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

Four layers, from doc conventions to CI rules, 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 (planned)

ESLint + Stylelint rules

Auto-flags hex literals and forbidden patterns in CI.