# Chromatic Design System > A universal, vibrational design system rooted in Edwin Babbitt's *Principles of Light and Color* (1878) and Besant & Leadbeater's *Thought-Forms* (1901). Twenty intention-mapped themes, eight chromatic-gray ramps, and Geist typography — calibrated so every interface feels coherent, calm, and intentional. Chromatic is not a brand for one company; it's a portable design substrate that any agent or product team can adopt. It pairs with three companion skill sets in this project — `tailwind-responsive`, `web-interface-guidelines`, and the shader skills — to produce production-grade frontends with consistent quality. --- ## What lives in this project | Path | What it is | |---|---| | `colors_and_type.css` | Single-file CSS source of truth: fonts, type scale, color ramps, semantic tokens, 6 theme presets, base element styles. Drop into any HTML and you have the system. | | `assets/chromatic.css` | Full Tailwind 4 build with **all 20** intention themes (use when working in Tailwind/Next.js). | | `assets/chromatic-tokens.ts` · `theme-presets.ts` · `universal-design-system.ts` · `use-chromatic-theme.tsx` · `chromatic-index.ts` | Original TS package (palette objects, intention-to-token generators, React provider/hook, theme switcher). | | `references/chromatic-design.md` | Color science: forces, intentions, palette tables, harmony laws. | | `references/chromatic-agent-knowledge.md` | Agent-facing build instructions, decision trees, theme-selection logic. | | `fonts/` | Geist + Geist Mono (variable + static weights) and Geist Pixel — uploaded from the user. | | `preview/` | One small HTML card per token cluster — these power the Design System tab. | | `ui_kits/chromatic-app/` | Hi-fi click-thru recreation of a Chromatic-themed dashboard / SaaS surface, with theme + dark-mode switching. | | `slides/` | *(empty — no slide template was provided.)* | | `SKILL.md` | Agent-Skill manifest so this folder works as a standalone Claude Code skill. | --- ## Sources The system was assembled from these inputs (mounted read-only at design-system creation time; reattach if you need to regenerate): - `chromatic-design/` — primary source. SKILL + references + assets. The Chromatic vibrational color system itself. - `tailwind-responsive/` — companion skill, mobile-first responsive patterns and iPhone/Safari safety rules. - `web-interface-guidelines/` — companion skill, accessibility / interaction / form / animation quality standards. - `shader-foundations/` + `weird-shaders/` — optional companions for shader-driven backgrounds and 3D motion. - `components/` — Aceternity-style Tailwind component zoo (3D marquees, beams, sparkles, etc.) — pulled in as motion/background reference, not core. - `ts-default/` — ReactBits-style component / animation / background / text-animation library — pulled in as motion reference. No Figma was attached. No slide deck was attached. No company brand was provided — Chromatic *is* the brand. The system is intentionally generic so it can be re-skinned per-app via the `[data-theme]` switch. --- ## CONTENT FUNDAMENTALS Chromatic copy supports the **golden rule** of the system: *interfaces should support human sovereignty, not undermine it.* That principle quietly determines tone everywhere. **Voice.** Direct, calm, slightly clinical. Short sentences. Plain English. Reads more like a well-edited engineering doc than marketing copy. The system descends from a 19th-century book on color science, and the prose still carries some of that quiet, taxonomic confidence — but never floral. **Person.** Mostly second-person ("you build", "your interface") for instructions, third-person/declarative for system descriptions ("Chromatic is…"). First-person plural is rare and reserved for moments of opinion ("we never use pure black"). **Casing.** Sentence case for everything except short labels and pills. ALL-CAPS only for `eyebrow` text and pill tags (`SUCCESS`, `BETA`, `IDLE`) — and only at very small sizes (`--text-2xs`). Never mid-paragraph. **Punctuation.** Em-dashes are welcome — they slow the reader down and add rhythm. Oxford commas always. Code, file paths, and tokens always wrapped in backticks. **Specifics over hype.** Replace every "powerful" / "seamless" / "intuitive" with the actual mechanism: *"Theme tokens compose by hue family, never by hex."* Numbers beat adjectives: *"8–20% saturation"*, not *"subtle colors"*. **Emoji.** No. Chromatic does not use emoji in product copy, slide decks, or marketing. Iconography is geometric (Lucide-style 1.5–2px stroke icons) and that's the only "emotional" visual language. The single exception: ✨ may appear in playful skill READMEs by other authors, but **never inside a Chromatic-themed product**. **Examples of the voice in this codebase** > "Quality of thought determines colour. Nature of thought determines form. Definiteness of thought determines clearness of outline." > — Besant & Leadbeater, *Thought-Forms* (1901) > "Build interfaces that support human sovereignty, not undermine it." > "CHROMATIC ≠ saturated. CHROMATIC = gradation with hue-tinted grays." > "Never make jarring leaps in lightness or saturation. Always use adjacent steps." > "Status dot: a 6-px circle with a same-color 4-px shadow." Notice: no exclamation marks. No "stunning." No "delightful." No emoji. Definitions and constraints stated as facts. --- ## VISUAL FOUNDATIONS A condensed Q-and-A on every visual decision in the system. When in doubt, follow these literally. ### Color - **Saturation ceiling.** Backgrounds 8–12%, surfaces 10–14%, borders 12–16%, interactive 14–18%, focus 16–20%. **Never above 25%.** - **No pure black, no pure white.** Use `*-50` (`hsl(0 0% 98%)`) and `*-950` (`hsl(0 0% 4%)`) instead. - **One hue family per view.** Don't mix theme hues. Bridge with achromatic if you absolutely must combine families. - **Gradation law.** Move *one* shade-step at a time across nested surfaces (`950 → 900 → 800`). Skipping steps reads as a jarring leap. - **Semantic states are constant.** `--success` (green-gray 120°), `--warning` (yellow-gray 48°), `--destructive` (red-gray 8°), `--info` (blue-gray 210°) — same across every theme so users don't relearn. ### Type - **Geist** (sans) for everything: UI, headings, body. **Geist Mono** for code, pills, numeric data, eyebrow text, status messages. **Geist Pixel** for accents only — reserved for hero moments. - Modular scale, ratio 1.25, 16-px base. Display sizes get `letter-spacing: -0.02em`. Body stays at `-0.01em`. - Headings use **600 (semibold)** by default. Reserve 700+ for hero moments. Body is **400**. - Numbers in tables / data: `font-variant-numeric: tabular-nums`. - Code keeps `letter-spacing: -0.01em` to match Geist Mono's natural width. ### Spacing & layout - **4-px grid.** Use the spacing scale (`4 8 12 16 24 32 48 64 96`). No off-grid values. - **Card padding** = `24px`. **Section gap** = `32px`. **Page gutter** = `16–32px` responsive. - **Touch targets** ≥ 44 px on mobile, ≥ 24 px visual on desktop. - **Use flex/grid + `gap`**, never sibling margins, for any row of like elements. ### Backgrounds - The default page is **flat tinted-gray** (the theme's `--background`). - Allowed background treatments: subtle **dot grid** (Aceternity-style), thin **noise** texture (3–5% opacity), single **radial fade** from a tinted color to the bg, animated **gradient orbs** with heavy blur. **No** photo backgrounds. **No** illustrations. **No** stock imagery. - Full-bleed shader backgrounds (`Aurora`, `Beams`, `Plasma`, `Silk`, `LiquidEther` from `ts-default/Backgrounds`) are reserved for hero / landing / login surfaces only — never under content. - Gradients are always two adjacent shades of the same hue (e.g. `--card → --secondary`), never rainbow. ### Borders & shadows - **Borders** are 1 px, color `--border`. On colored surfaces, tint the border toward the surface hue (use `--border` from the same theme). - **Shadows** are layered (ambient + direct). Never a single huge shadow. - `--shadow-sm`: cards, buttons. - `--shadow-md`: hovered cards, dropdowns. - `--shadow-lg`: modals, popovers. - `--shadow-xl`: major dialogs. - **Inner glow** (`--shadow-glow`) marks focused / "alive" elements: a 1-px ring at 35% ring color + an 18-px outer glow at 20%. - **No drop-shadow on text.** Use a contrasted background instead. ### Corner radii - `--radius-sm: 2px` — pills, tiny tags. - `--radius-md: 6px` — buttons, inputs. - `--radius-lg: 12px` — cards (default). - `--radius-xl: 20px` — modals, large surfaces. - `--radius-full: 9999px` — avatars, capsule buttons. - **Nest concentrically.** A child's radius is always **smaller** than its parent's (12 → 6, 6 → 2). Equal radii feel cheap; bigger-than-parent looks broken. ### Cards A canonical Chromatic card is: `--card` background, `1px solid --border`, `--radius-lg`, `--shadow-sm`, `padding: 24px`. Hovered cards bump to `--shadow-md` + a 1-px line at the top in `--primary` (the "card glow" pattern in the original SKILL). ### Animation - **Easing.** `cubic-bezier(0.4, 0, 0.2, 1)` (out) for entry, `cubic-bezier(0.4, 0, 1, 1)` (in) for exit, `cubic-bezier(0.2, 0.6, 0, 1)` for emphasized motion. **No bounces.** No springs that overshoot more than 5%. - **Duration.** 120 ms (instant feedback), 200 ms (default UI), 320 ms (emphasized / page-level). - **Property allowlist.** Animate only `transform` and `opacity`. Never `transition: all`. Never `width`/`height`/`top`/`left`. - **Interruptible.** All transitions must be reversible mid-flight. - **Reduced motion.** Honored globally — `colors_and_type.css` collapses durations to `0.01ms` under `prefers-reduced-motion: reduce`. ### Hover, press, focus - **Hover.** *Increase contrast.* Buttons go from `--primary` → `--primary` with `+2% lightness` + `--shadow-md`. Cards lift via shadow only. Links underline (don't color-shift). - **Press / `:active`.** `transform: translateY(0.5px) scale(0.99)`; no color change. Snap, don't bounce. - **Focus.** Always a visible 2-px `--ring` outline with 2-px offset. Never `outline: none`. - **Disabled.** `opacity: 0.5`, `cursor: not-allowed`. No color change. ### Transparency & blur - Used **sparingly.** Only for: modal scrims (`bg-background/70 backdrop-blur-sm`), toolbars over content, tooltip cards, and the noise overlay on hero shaders. - Never on body content. Never on cards (it muddles the gradation law). ### Imagery (when used) - **Cool, mid-contrast, slight grain.** Avoid warm sunset palettes unless on the `warmth` / `energy` themes. - **Black-and-white** photography is the safest fallback for product moments — it never clashes with a chromatic theme. - Always run a 4–6% grain overlay; it ties photography to the chromatic-gray system. ### Layout fixed elements - **Top app bar** sticks: 56 px tall on desktop, 48 px on mobile. Backdrop-blur + 70% opacity over `--background`. - **Side nav** 240 px collapsed → 64 px icon-only. Never a third state. - **Footer** is unstyled and minimal: muted text, single border-top. ### Protection gradients vs capsules - When text overlaps imagery, use a **vertical protection gradient** (bottom `--background` → top transparent, ~120 px tall) — never a capsule. Capsules feel like marketing; protection gradients let the image breathe. --- ## ICONOGRAPHY - **Library.** [Lucide](https://lucide.dev) is the canonical icon family — its 1.5-px round-cap stroke matches Geist's geometry exactly. Use Lucide for **every** glyph in product UI. - **Delivery.** SVG only. No icon font. No PNG. Either inline `` (preferred for color/size control) or ``. - **Sizes.** 14 px (inline with body), 16 px (default UI), 20 px (toolbar / list rows), 24 px (heroes / empty states). - **Stroke.** Always `1.5–2px`. Never solid-fill icons in product chrome — solid icons read as "branding" and break Chromatic's geometric calm. - **Color.** Inherits `currentColor`. In a button, set `color: var(--primary-foreground)` and the icon follows. In a list, `color: var(--muted-foreground)`. - **No emoji** in UI (see CONTENT FUNDAMENTALS). The only Unicode characters allowed as icons are the keyboard symbols (`⌘ ⌥ ⇧ ⌃ ⏎ ⌫ ↵`) inside ``. **This project ships a small starter set of Lucide SVGs in `assets/icons/`** — just enough to populate the UI kit. Reach for the full set [via CDN](https://unpkg.com/lucide-static@latest/icons/) when prototyping; copy the specific files you need into `assets/icons/` for production builds. > **Substitution flag.** No bespoke logo or icon set was provided. Lucide is a substitution — it matches Geist's geometry better than any alternative — but if your brand has a custom mark, drop it in `assets/logo/` and update the UI kit's `` component. --- ## Index / manifest (root contents) ``` . ├── README.md ← you are here ├── SKILL.md ← Agent-Skill manifest ├── colors_and_type.css ← single-file token + theme source ├── assets/ │ ├── chromatic.css ← Tailwind 4, all 20 themes │ ├── chromatic-tokens.ts ← palette ramps as TS │ ├── theme-presets.ts ← intention → tokens │ ├── universal-design-system.ts ← CSS generator helpers │ ├── use-chromatic-theme.tsx ← React provider + switcher │ ├── chromatic-index.ts ← package barrel │ ├── icons/ ← Lucide SVG starter set │ └── logo/ ← Chromatic mark (SVG) ├── fonts/ ← Geist · Geist Mono · Geist Pixel (.ttf) ├── references/ │ ├── chromatic-design.md ← color science (full) │ └── chromatic-agent-knowledge.md ← agent build playbook ├── preview/ ← Design System tab cards (one HTML per token cluster) └── ui_kits/ └── chromatic-app/ ← hi-fi SaaS dashboard recreation ├── README.md ├── index.html └── *.jsx ← per-component ``` --- ## Quickstart for an agent 1. Pick an intention. Match the user's request to one of the 20 themes (`trust`, `energy`, `harmony`, `spirit`, `urgency`, …). Default to `neutral`. 2. Set `` (or omit `class="dark"` for light mode). 3. Use semantic tokens only: `var(--background)`, `var(--foreground)`, `var(--primary)`, `var(--card)`, `var(--border)`, `var(--ring)`. **Never hex/rgb.** 4. Use Geist for type, the 4-px grid for spacing, the 1.25 modular scale for sizes, Lucide for icons. 5. Honor every rule in **VISUAL FOUNDATIONS** above. The 20-theme switch only works because the rules are consistent. If you only read one section, read VISUAL FOUNDATIONS. --- *Quality of thought determines colour. Nature of thought determines form. Definiteness of thought determines clearness of outline.*