Style Guide
Iron & Ale design system documentation — Light & Dark themes
Side-by-Side Theme Preview
Light Theme
Body text in light theme with good contrast.
Muted text on surface
Dark Theme
Body text in dark theme with good contrast.
Muted text on surface
Color Tokens
Semantic Tokens (Theme-Aware)
These tokens automatically adapt to light/dark theme:
| Token | Light Value | Dark Value | Preview |
|---|---|---|---|
| --bg | #f9fafb (gray-50) | #111827 (gray-900) | |
| --surface | #ffffff | #1f2937 (gray-800) | |
| --text | #111827 (gray-900) | #f9fafb (gray-50) | |
| --text-muted | #6b7280 (gray-500) | #9ca3af (gray-400) | |
| --accent | #2563eb (primary-600) | #60a5fa (primary-400) | |
| --button-bg | #2563eb (primary-600) | #3b82f6 (primary-500) | |
| --border | #e5e7eb (gray-200) | #374151 (gray-700) |
Contrast Ratios (WCAG AA)
Body Text on Background
--text on --bg
✓ WCAG AA Pass (7:1+)Button Text
--button-text on --button-bg
✓ WCAG AA Pass (4.5:1+)Primary (Blue)
Neutral (Gray)
Typography
Font Size Scale
Body text (text-base) — 1rem / 16px • line-height: 1.5. The quick brown fox jumps over the lazy dog.
Small text (text-sm) — 0.875rem / 14px. Secondary information and captions.
Extra small (text-xs) — 0.75rem / 12px. Fine print and labels.
Monospace (font-mono) — Used for code.
Spacing Scale
Based on 0.25rem (4px) increments. Use p-*, m-*, gap-* utilities.
| Token / Class | Value (rem) | Value (px) | Preview |
|---|---|---|---|
| --space-1 / p-1 | 0.25rem | 4px | |
| --space-2 / p-2 | 0.5rem | 8px | |
| --space-3 / p-3 | 0.75rem | 12px | |
| --space-4 / p-4 | 1rem | 16px | |
| --space-6 / p-6 | 1.5rem | 24px | |
| --space-8 / p-8 | 2rem | 32px | |
| --space-12 / p-12 | 3rem | 48px |
Components
Buttons
Variants
Sizes
States
Cards
Basic Card
Simple card with body only.
Card with Header
Card body content goes here.
Form Controls
Tab into inputs to see focus ring styling.
Alerts
Badges
Links
Default link: Click here
Muted link: Secondary action
Utilities Examples
Flexbox
Grid
Text Utilities
This is centered, truncated if too long, and uppercase text
Images & Theming
For images that need to work in both themes, consider:
- Use transparent backgrounds when possible
- Provide separate light/dark variants in
/images/ - Use CSS filters or overlays for compatibility
Example: Image with overlay
Overlay adapts to current theme.
Accessibility & QA
Keyboard Focus
All interactive elements have visible focus rings. Tab through this page to test.
ARIA Live Regions
Theme changes are announced to screen readers via aria-live="polite".
Contrast Testing
Run locally with:
How to Edit
Theme Variables Location
Changing a Color
- Open
assets/css/variables.css - Find the semantic token (e.g.,
--accent) - Update the value in
:rootfor light theme - Update in
.theme-darkfor dark theme - Refresh to see changes
Adding Image Variants
Place light/dark image variants in /images/ with naming convention:
Then use CSS to swap based on theme class or media query.