Color, Contrast & the Three-Tier Hierarchy
Primary (slate-50/200) → muted (slate-400) → dim (slate-500 labels only) — readable text must be Tier 2 or above.
Why Color Is a Readability System, Not an Aesthetic One
The most common UI mistake with dark mode is using color as decoration — picking colors that look visually interesting without checking whether they are actually readable. The result is interfaces that look sophisticated in a design tool and are painful to read in a browser.
Color in dark mode is a readability system. Every text color choice is a decision about whether the user can comfortably read the content. This is why the academy design system uses a three-tier hierarchy: not three categories of "importance" but three readability tiers with specific brightness floors.
This three-tier model is consistent across all five ecosystem properties. The exact hex values may vary slightly by property, but the structure is identical: bright primary for impact, muted secondary for readable content, dim tertiary for decorative metadata.
The Three Tiers in Detail
Tier 1 — Primary: #f1f5f9 (slate-100), #e2e8f0 (slate-200), #cbd5e1 (slate-300). These are for hero text, section headings, stat figures, and CTA labels — anything that needs maximum visual impact. Tier 1 colors have 12:1–18:1 contrast ratios on dark backgrounds. Use them where hierarchy matters most. Do not use them for body paragraphs — that level of contrast is fatiguing at 2,000 words.
Tier 2 — Secondary (Readable Floor): #94a3b8 (slate-400). This is the brightness floor. Any text the user must read — body copy, lesson content, card descriptions, error messages, instructions — must be at Tier 2 or above. The 7.7:1 contrast ratio exceeds WCAG AA (and clears the 7:1 AAA threshold for normal text) and is comfortable for sustained reading. This is the most important tier rule: never go below this for readable content.
Tier 3 — Tertiary (Decorative Only): #64748b (slate-500) and dimmer. Data labels, timestamps, metadata, category markers, placeholder text. These are elements the user glances at but does not need to read carefully. The 4.1:1 contrast passes WCAG AA for large text only — it is below the threshold for normal 16px body copy. Using slate-500 for descriptions or instructions is a readability violation.
The Contrast Threshold Scale
The scale makes the physics concrete. Every color from white to slate-700 is measured against the academy's dark background (#0a0a0f). The pass/fail column is not aesthetic judgment — it is calculated contrast ratio against WCAG standards.
The key observation: the boundary between "acceptable body copy" and "decorative only" falls at slate-400 (#94A3B8). Slate-500 (#64748b) is 4.1:1 — which passes WCAG AA large text only. For 16px normal-weight body copy, it fails. This is why the three-tier rule exists: it provides a clear floor without requiring every developer to run a contrast calculator on every color choice.
Accent Colors Are Mode-Specific
The academy uses #00E5FF (cyan) as the primary accent in dark mode. The MASTER.md specifies a different accent for light mode: #0066CC (electric blue, 5.2:1 contrast on the light background #F6F8FA).
This is an important pattern: the same role can require a different color in different modes. Cyan (#00E5FF) has excellent contrast against dark backgrounds — its high luminance makes it pop. On a white or very light background, it disappears. Blue (#0066CC) has excellent contrast on light backgrounds but poor contrast on dark ones.
MASTER.md specifies both because bi-modal sites need mode-specific accent values. AI generating components must know which mode it is targeting — or use CSS variables that are swapped by the theme provider.
The Academy Color System in Practice
The academy's active color system, which this lesson uses, maps to the tier hierarchy directly:
- Hero headings:
#f1f5f9— Tier 1, maximum impact - Section headings:
#e2e8f0— Tier 1, high contrast - Body copy:
#94a3b8— Tier 2 floor, comfortable sustained reading - Accent/interactive:
#00E5FF— brand cyan, interactive signals - Data labels:
#64748b— Tier 3, glanceable metadata only - Borders:
rgba(255,255,255,0.08)— structural, not text
Every text color choice in the academy is explicitly in the MASTER.md under "Color System" with its CSS variable name and hex value. AI building academy components has no opportunity to improvise — the constraint is complete.
Color is not decoration when it determines whether users can read your product. The three-tier hierarchy is the specification that prevents color from being treated as decoration.