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

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