Changelog - 2026-01-19 (#3)

Design System Documentation Hub

Overview

Created an internal design system hub for collaborators to reference components, patterns, and theme documentation. The hub includes a comprehensive theme token reference page documenting the complete emblem theming system.

Pages Added

`/design-system` — Hub Index

Navigation page for exploring all design system documentation:

Category groupings — Foundation, Components, Features, Reference
Navigation cards — Title, description, and link for each page
Quick links footer — Fast access to all documented pages
Emblem theme styling — Uses semantic color tokens throughout

`/design-system/theme` — Theme Token Reference

Complete documentation for the emblem theme system:

Brand Colors

Visual swatches with CSS variable names and hex values
Crimson, navy, amber, electric brand palette
Background/foreground colors (ivory, midnight, haiti-blue, charcoal, snow)

Graphite Scale

Full 11-step neutral grey strip (950 → 50)
Hover tooltips with variable names and values

Semantic Tokens by Mode

Table showing how each token resolves across light/dark/vibrant
Covers background, foreground, surface, primary, secondary, accent, muted, border, ring

Effect Tokens

Glow opacity, spread, and color per mode
Text shadow intensities
Additional effect token documentation (hero gradients, card effects, headline gradients)

Mode Characteristics

Visual cards showing each mode's personality
Light: Clean, professional
Dark: Bold, confident
Vibrant: High-impact expressive

Usage Examples

CSS variable usage with Shiki syntax highlighting
Tailwind class examples
Helper class documentation (.card, .btn-primary, .gradient-text, .hero-shell)

File Locations

Points to emblem-theme.css and global.css

Technical Implementation

Astro Code Component

Used Astro's built-in Code component for syntax-highlighted code blocks:

---
import { Code } from 'astro:components';

const cssExample = `.my-component {
  background: var(--color-surface);
}`;
---

<Code code={cssExample} lang="css" theme="aurora-x" />

Benefits:

Uses Shiki under the hood
Respects astro.config.mjs theme settings
Supports all Shiki languages and themes
Zero additional dependencies

Styling Approach

Uses semantic CSS variables for automatic theme adaptation
Minimal custom styles scoped to page components
Visual swatches rendered with inline styles from data
Tables for structured token comparisons
Mode cards with hardcoded colors to show actual appearance

Routes

Route	Description
`/design-system`	Hub index with navigation cards
`/design-system/theme`	Complete theme token documentation

Future Additions

Placeholder categories in the hub for future documentation:

Components — Button, Card, Input component references
Features — Feature-specific documentation
Reference — Additional reference materials

Internal Use

This design system hub is intended for:

Collaborators — Quick reference for available tokens and patterns
AI assistants — Understanding the theming system for accurate code generation
Developers — Consistent implementation across the site