# SGT Design System

> The design system of Sergeant AG (sergeant.agency), a Swiss branding agency. Framework-free CSS with custom properties, driving every brand asset that renders as HTML: websites, Reveal.js presentations, emails, PDFs and print templates. Design tokens are authored as DTCG JSON and compiled to CSS; consumers just link two or three stylesheets, no build step.

Architecture in one paragraph: `tokens/` (DTCG JSON, three tiers) is the source of truth and is compiled by Style Dictionary v5 into `tokens.css`, which is never hand-edited. `tokens.css` exposes two APIs at once — a frozen legacy layer (`--sgt-*`, `--text-*`, `--sp-*`, …) that every shipped deck and site already consumes, and an additive modern layer (`--sgt-`-prefixed fluid `clamp()` scales, semantic `light-dark()` colours, component tokens). Components live in `sgt-ds-core.css` (DOM-agnostic, works anywhere) and `sgt-ds-slides.css` (presentation-only). Colours are authored in OKLCH; dark mode is opt-in and never changes how existing pages render.

Brand rules that override generic design defaults: hierarchy comes from size and never from weight (400 everywhere, 500 only for small labels, never 700 for headlines); letter-spacing is always `0.01em` and never negative; nothing renders below 18px in a presentation.

## Docs

- [AGENTS.md](https://brand.sergeant.agency/AGENTS.md): The contract for coding agents — hard rules, where to change what, consumption snippets, cascade layers, build and verify commands. Read this first before changing anything.
- [Token reference](https://brand.sergeant.agency/docs/tokens.md): Every CSS custom property, grouped by tier, with values, OKLCH sources and light/dark pairs. Generated from `tokens/`.
- [Token map (JSON)](https://brand.sergeant.agency/docs/tokens.json): Flat machine-readable map `{"--css-var": {value, type, tier, api, path}}`. Prefer this over parsing CSS.
- [Living documentation](https://brand.sergeant.agency/): Rendered showcase of all tokens and components.
- [CLAUDE.md](https://brand.sergeant.agency/CLAUDE.md): Full reference including the complete slide component catalogue with HTML snippets, Reveal.js configuration and migration notes.

## Stylesheets

- [tokens.css](https://brand.sergeant.agency/tokens.css): Generated custom properties. Load first. Declares the cascade layer order.
- [fonts.css](https://brand.sergeant.agency/fonts.css): Self-hosted DM Sans (weights 300/400/400i/500). Required — the core stylesheet does not load fonts from a CDN.
- [sgt-ds-core.css](https://brand.sergeant.agency/sgt-ds-core.css): Core components — typography, buttons, cards, tags and pills, tables, dividers, pull quote, forms, layout helpers. All classes prefixed `sgt-`, all opt-in, no global element selectors.
- [sgt-ds-slides.css](https://brand.sergeant.agency/sgt-ds-slides.css): Presentation components — glass cards, bento grids, phases, steps, architecture boxes, donut and bar charts, verdict badges, callouts, gradients.
- [sgt-presentation-v4.css](https://brand.sergeant.agency/sgt-presentation-v4.css): Reveal.js v4 stylesheet, preferred for new decks.

## Optional

- [sgt-presentation.css](https://brand.sergeant.agency/sgt-presentation.css): Reveal.js v3 stylesheet. Frozen legacy — serves already-shipped decks only, uses the older naming scheme, must not be loaded alongside `sgt-ds-core.css`.
- [sgt-marp.css](https://brand.sergeant.agency/sgt-marp.css): Marp CLI theme. Standalone by design, since Marp cannot import shared CSS at render time.
- [template-v4.html](https://brand.sergeant.agency/template-v4.html): Copy-paste starter for a new v4 deck, ten slide types.
- [showcase-v3.html](https://brand.sergeant.agency/showcase-v3.html): Living reference of the v3 slide components, including the animation JavaScript.
- [ds-skeleton-architecture.md](https://brand.sergeant.agency/ds-skeleton-architecture.md): The client-agnostic skeleton this system is the first tenant of.