The Design System as Source of Truth
MASTER.md is the contract AI must honour — not a reference it can consult and ignore.
The File That Changes Everything
The design-system/MASTER.md is not documentation. It is not a style guide. It is a constraint file — the single source of truth that tells AI exactly what it is allowed to build and exactly what it is not allowed to build.
When you start a new property, the first file you create is design-system/MASTER.md. Not the homepage. Not the component library. The design system file. This is a hard rule in CLAUDE.md:
This is the pattern behind five live properties: jeremyknox.ai, academy.jeremyknox.ai, indecision.io, tesseractintelligence.io, and rewiredminds.io. Each has its own MASTER.md. Each AI agent working on UI for these properties reads that file before any code.
What Goes in MASTER.md
The MASTER.md structure is consistent across all five properties. It is not a Figma export or a colour palette image. It is a structured text file with sections that AI can read as literal constraints.
The academy's own MASTER.md — which you can find at design-system/MASTER.md in this repo — is the reference implementation for this lesson. It contains:
Identity & Concept — what the product is, what tone it communicates, the one thing users should remember. This section answers the domain question: "What kind of product is this, and what should its UI feel like?" For the academy: "Intelligence briefing. Mission-critical. Earned authority."
Color System — every CSS variable with its exact value. Not "use a dark background" but --background: #0a0a0f. Not "use a cyan accent" but --accent: #00E5FF. The academy's MASTER.md specifies dark mode and light mode token values separately.
Typography Rules — exact sizes, weights, and line-heights for every text role. Body is 16px / 400 / 1.625. Headings are 600 minimum. font-weight 300 is banned. These are not suggestions — they are the hard rules from CLAUDE.md applied at the project level.
Component Patterns — the glass-card system, button variants, progress bars. Each with a CSS class name, a background value, and a border specification.
Anti-Patterns (DO NOT) — a list of prohibited patterns. "No purple gradients on white backgrounds. No font-light or font-thin anywhere. No text-slate-500 for body copy." This is the instruction set that prevents AI from making the aesthetically common-but-wrong choices.
The Directory Structure
MASTER.md is the top-level design document. Page-specific overrides live in a pages/ subdirectory. Token CSS files codify the values into CSS custom properties.
The override chain follows the same specificity model CSS uses: design-system/pages/home.md overrides design-system/MASTER.md for the home page only. Everything else inherits MASTER.md. This prevents "page exception" sprawl — the most common way design systems drift.
Knox's jeremyknox.ai has a design-system/pages/work-with-me.md for the developer services page because that page has a different layout from the rest of the site. The base rules (color system, typography, glass-card) come from MASTER.md. The section breakdown and layout specifics come from the page override.
The Priority Order
When an AI agent works on UI, the reading order is:
design-system/MASTER.md— project-level, always wins over defaultsdesign-system/pages/<page-name>.md— page-level, wins over MASTER.md for its page~/dev/design-intelligence.md— cross-site defaults (Inter, JetBrains Mono, glass-card pattern, ecosystem footer)- AI defaults — never acceptable
The AI is instructed to read these files in this order before any code. If MASTER.md says the accent color is #00E5FF, that value is used. If pages/dashboard.md says that page uses a monochrome surface variant, that overrides MASTER.md's glass-card spec. Nothing is left to AI improvisation.
Bi-Modal Requirements
The academy is bi-modal: dark mode is the default, light mode is a first-class alternative. This creates a constraint that differs from single-mode dark sites (like rewiredminds.io).
The MASTER.md rule is explicit: every new component must work correctly in both modes. This means using CSS variables from globals.css — never hard-coded hex values. When the theme toggles from dark to light, the CSS variables are swapped by the theme provider. Hard-coded #0d1117 stays dark regardless of the user's preference.
This is a common AI failure mode: it generates inline styles with hard-coded dark hex values because that matches the reference (which is dark). MASTER.md must explicitly prohibit this — and the academy's does.
The design system is not documentation of decisions already made. It is the instruction set for every decision still to be made — including the ones the AI will make while you are doing something else.