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 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 <svg> (preferred for color/size control) or <img src="/path/to/icon.svg">.
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 <kbd>.

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 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 <Logo /> 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

Pick an intention. Match the user's request to one of the 20 themes (trust, energy, harmony, spirit, urgency, …). Default to neutral.
Set <html data-theme="<intention>" class="dark"> (or omit class="dark" for light mode).
Use semantic tokens only: var(--background), var(--foreground), var(--primary), var(--card), var(--border), var(--ring). Never hex/rgb.
Use Geist for type, the 4-px grid for spacing, the 1.25 modular scale for sizes, Lucide for icons.
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.