Design System

This page is generated with ClaudeClaude Code
Overview

This document defines the design system for stoll.studio, including the theming system, colors, typography, spacing, layout, and components. All design tokens are implemented as CSS custom properties in a 5-tier architecture.

Global Constants Fixed values (black, white, phosphor): never change across themes
Base Tokens Per-theme primitives (text, accents, surfaces, borders, spacing scale, type scale)
Status Tokens Per-theme state values (info, success, error, warning)
Semantic Tokens Reference base/status tokens for specific purposes (links, bullets, code)
Component Tokens Reference base/semantic tokens for specific components (sticky bar, blockquotes, skip link)
Behind the scenes

This page documents the design system. The CSS manifests it. The Figma file materializes it. As a space for visual exploration and adjustment. Plotting out the token architecture as Figma variables and building a dedicated Token Inspector page allows to see the system as a whole and refactor it with confidence.

This page Documents the system: tokens, components, decisions, changelog
themes.css Manifests the system: CSS custom properties, theme definitions
Figma file Materializes the system: Figma variables mirroring the token structure, Token Inspector page for visual review and color exploration

Open Figma Token Inspector ↗

Themes

Four themes available, activated via URL parameter (?theme=name) or the footer switcher. Themes override base color tokens; semantic and component tokens inherit automatically.

Light Light theme: white surface, Hanken Grotesk, yellow accent bar with black text
Dark Dark theme: #1a1a1a surface, Hanken Grotesk, blue bar (#5dade2) with black text
Vibrant Vibrant blue (#3D38F5) surface, pink (#FF0080) accents, lime (#D4FF00) links
Terminal Single phosphor green (#00FF41) at varying opacities on pure black (#000), IBM Plex Mono throughout, normal weight (400) for all text

Theme switching is handled by theme-switcher.js which reads the URL parameter, applies the data-theme attribute on <html>, and propagates the theme to all internal links. A critical inline script in <head> prevents flash of unstyled content.

Light Theme Colors

Text colors.

Primary #313131: main headings, strong text
Secondary #515151: body text, paragraphs
Tertiary #7a7a7a: muted text, bullets
Quaternary #9a9a9a: dates, very muted elements
Light #c0c0c0: taglines, very light text

Accent, surface and border colors.

Accent 1 #ffff00: signature yellow
Accent 2 #268bd2: blue (links, code)
Accent 3 #ff0000: red accent
Surface #ffffff: main background
Surface Emphasized #f5f5f5: table headers, cards
Surface Secondary #f9f9f9: code blocks, blockquotes
Border #eee: primary borders
Border Secondary #e5e5e5: secondary borders
Border Strong #cccccc: structural dividers
Image BG #d5d5d5: translucent image card background

Status colors.

Info #268bd2: informational (blue)
Success #27ae60: success states (green)
Error #e74c3c: error states (red)
Warning #f39c12: warning states (orange)

Semantic and component colors.

Divider #cccccc: structural dividers (via Border Strong)
Link #268bd2: links (via Info/Accent 2)
Hover opacity: 0.75 on a:hover / a:focus, no color token, theme-agnostic
Code #268bd2: inline code text (via Accent 2)
Bullet #7a7a7a: list bullets (via Tertiary)
Meta #7a7a7a: figcaptions, project meta table headers, blockquote citations (via Tertiary)
Meta Secondary #9a9a9a: project subtitles, project credits (via Quaternary)
Sticky Bar BG #ffff00: Accent 1 yellow
Sticky Bar Text #000: black
Blockquote BG #f9f9f9: blockquote background (via Surface Secondary)
Blockquote Border #ffff00: blockquote left border (via Accent 1)
Skip Link BG #000: skip-to-content background (global black)
Skip Link Text #fff: skip-to-content text (global white)
Dark Theme Colors

Text colors.

Primary #ffffff: main headings, strong text
Secondary #e0e0e0: body text, paragraphs
Tertiary #b0b0b0: muted text, bullets
Quaternary #808080: dates, very muted elements
Light #606060: taglines, very light text

Accent, surface and border colors.

Accent 1 #ffff00: signature yellow
Accent 2 #5dade2: blue
Accent 3 #ff0000: red accent
Surface #1a1a1a: main background
Surface Emphasized #2a2a2a: table headers, cards
Surface Secondary #242424: code blocks, blockquotes
Border #333: primary borders
Border Secondary #444: secondary borders
Border Strong #666666: structural dividers

Status colors.

Info #5dade2: informational (blue)
Success #2ecc71: success states (green)
Error #e74c3c: error states (red)
Warning #f39c12: warning states (orange)

Semantic and component colors.

Divider #666666: structural dividers (via Border Strong)
Link #5dade2: links, interactive elements
Hover opacity: 0.75 on a:hover / a:focus, no color token, theme-agnostic
Code #5dade2: inline code text (via Accent 2)
Bullet #b0b0b0: list bullets (via Tertiary)
Meta #b0b0b0: figcaptions, project meta table headers, blockquote citations (via Tertiary)
Meta Secondary #808080: project subtitles, project credits (via Quaternary)
Sticky Bar BG #5dade2: Accent 2 blue
Sticky Bar Text #000: black
Blockquote BG #242424: blockquote background (via Surface Secondary)
Blockquote Border #ffff00: blockquote left border (via Accent 1)
Skip Link BG #000: skip-to-content background (global black)
Skip Link Text #fff: skip-to-content text (global white)
Vibrant Theme Colors

Text colors.

Primary #ffffff: main headings, strong text
Secondary rgba(255, 255, 255, 0.75): body text
Tertiary rgba(255, 255, 255, 0.6): muted text
Quaternary rgba(255, 255, 255, 0.45): dates, very muted
Light rgba(255, 255, 255, 0.3): taglines

Accent, surface and border colors.

Accent 1 #FF0080: pink
Accent 2 #D4FF00: lime
Accent 3 #00FFD9: cyan-teal accent
Surface #3D38F5: vibrant blue background
Surface Emphasized #312CDB: table headers, cards
Surface Secondary #4942F7: code blocks, blockquotes
Border rgba(255, 255, 255, 0.15): primary borders
Border Secondary rgba(255, 255, 255, 0.2): secondary borders
Border Strong rgba(255, 255, 255, 0.3): structural dividers

Status colors.

Info #69A0FF: informational (blue)
Success #00FF33: success states (green)
Error #FF3366: error states (red)
Warning #FFB800: warning states (orange)

Semantic and component colors.

Divider rgba(255, 255, 255, 0.3): structural dividers (via Border Strong)
Link #D4FF00: lime links
Hover opacity: 0.75 on a:hover / a:focus, no color token, theme-agnostic
Code #D4FF00: inline code text (via Accent 2 lime)
Bullet rgba(255, 255, 255, 0.4): list bullets (white-40)
Meta rgba(255, 255, 255, 0.6): figcaptions, project meta table headers, blockquote citations (via Tertiary / white-60)
Meta Secondary rgba(255, 255, 255, 0.45): project subtitles, project credits (via Quaternary / white-45)
Sticky Bar BG #FF0080: Accent 1 pink
Sticky Bar Text #fff: white
Blockquote BG #4942F7: blockquote background (via Surface Secondary)
Blockquote Border #FF0080: blockquote left border (via Accent 1 pink)
Skip Link BG #FF0080: skip-to-content background (Accent 1 pink)
Skip Link Text #fff: skip-to-content text (global white)
Terminal Theme Colors

Text colors.

Primary #00FF41: phosphor green, all headings
Secondary rgba(0, 255, 65, 0.85): body text
Tertiary rgba(0, 255, 65, 0.70): muted text
Quaternary rgba(0, 255, 65, 0.60): dates, very muted
Light rgba(0, 255, 65, 0.50): taglines

Accent, surface and border colors.

Accent 1 #00FF41: phosphor green (all accents unified)
Accent 2 #00FF41: phosphor green (all accents unified)
Accent 3 #00FF41: phosphor green (all accents unified)
Surface #000000: pure black background
Surface Emphasized #111111: table headers, cards
Surface Secondary #222222: code blocks, blockquotes
Border rgba(0, 255, 65, 0.15): primary borders
Border Secondary rgba(0, 255, 65, 0.2): secondary borders
Border Strong rgba(0, 255, 65, 0.30): structural dividers

Status colors.

Info #00BFFF: informational (cyan-blue)
Success #00FF41: success states (phosphor green)
Error #FF0000: error states (red)
Warning #FFFF00: warning states (yellow)

Semantic and component colors.

Divider rgba(0, 255, 65, 0.30): structural dividers (via Border Strong)
Link #00FF41: terminal green links (uses Primary color)
Hover opacity: 0.75 on a:hover / a:focus, no color token, theme-agnostic
Code #00FF41: inline code text (via Accent 2, phosphor green)
Bullet rgba(0, 255, 65, 0.4): list bullets (phosphor-40)
Meta rgba(0, 255, 65, 0.70): figcaptions, project meta table headers, blockquote citations (via Tertiary / phosphor-70)
Meta Secondary rgba(0, 255, 65, 0.60): project subtitles, project credits (via Quaternary / phosphor-60)
Sticky Bar BG #00FF41: terminal green
Sticky Bar Text #000: black
Blockquote BG #222222: blockquote background (via Surface Secondary)
Blockquote Border #00FF41: blockquote left border (via Accent 1, phosphor)
Skip Link BG #00FF41: skip-to-content background (Accent 1, phosphor)
Skip Link Text #000: skip-to-content text (global black)

Typography: Terminal theme uses monospace font throughout for authentic terminal aesthetic.

Font Family IBM Plex Mono everywhere (headings, body, navigation, all text)
Font Weight All weights normalized to 400 (normal): headings, body, bold text all use regular weight for authentic terminal look
Typography

Font families and their usage across the site.

Primary Hanken Grotesk (variable, 100–900): body text, headings, labels
Monospace IBM Plex Mono: code blocks, navigation links

Font sizes (desktop base: 20px, mobile base: 18px).

H1 2rem (40px): page titles
H2 1.3rem (26px) desktop, 1.8rem mobile: main statements
H3 1.25rem (25px) desktop, 1.4rem mobile
Body 1rem (20px) desktop, 1.05rem mobile
Masthead 1.5rem (30px) desktop, 1.6rem mobile
Small/Meta 0.8–0.85rem (16–17px): captions, dates, notes

Font weights using variable font capabilities.

300 Light
400 Regular (default body text)
500 Medium (navigation links)
550 Between medium and semi-bold (two-col labels)
600 Semi-bold (headings, bold text)
Spacing

Spacing scale using rem units (scales with base font size).

XS 0.25rem (5px): tight spacing, table cells
SM 0.5rem (10px): small gaps, heading margins
MD 1rem (20px): standard spacing, paragraph margins, navigation gap
LG 1.5rem (30px): section spacing, figures
XL 2rem (40px): large spacing, project credits
2XL 2.5rem (50px): section dividers (two-col margin-bottom)
3XL 3rem (60px): masthead margin
Layout

Breakpoints and responsive behavior.

Desktop ≥769px: two-column grids, inline navigation, container max-width 72rem
Mobile ≤768px: single column, hamburger menu with overlay, theme select dropdown, 18px base font
Small ≤600px: project column grids collapse to single column

Two-column structural layout (.two-col): the primary layout pattern used across all pages.

.two-col Grid section: 30% / 1fr on desktop, stacked on mobile. Top border, 0.75rem padding-top, 2.5rem margin-bottom.
.two-col-label Left column: topic name or section headline. Font-weight 550, primary color.
.two-col-role Right column, row 1: role or subtitle. Secondary color, 0.75rem margin-bottom.
.two-col-content Right column: body text, tables, nested grids. Spans rows 2–20 (or 1–20 when no role).
.two-col-note Left column, row 2: muted sidenote. 0.8rem, quaternary color.

Column grids: nest inside .two-col-content. Shared across stoll.studio (project.css) and teaching.stoll.studio (course.css). Usage: <div class="columns columns-2">.

.columns-2 Two equal columns (1fr 1fr). Collapses to 1 column on mobile.
.columns-3 Three equal columns (1fr 1fr 1fr). Collapses to 1 column on mobile.
.columns-4 Four equal columns. Collapses to 2 columns on mobile (not 1: image grids stay readable at 2).
.columns-1-2 Asymmetric, small left (1fr 2fr). Collapses to 1 column on mobile.
.columns-2-1 Asymmetric, large left (2fr 1fr). Collapses to 1 column on mobile.
Components

Navigation. Desktop: horizontal inline with masthead (flexbox, baseline-aligned). Mobile: hamburger menu with full-screen overlay.

Active state Underline via aria-current="page", 6px offset, 2px thickness
Hover state Same underline style as active state
Font IBM Plex Mono, weight 500
Mobile toggle CSS-only hamburger icon (3 lines, 24×2px, 7px spacing), animates to X on open. Uses var(--color-primary).
Mobile overlay Full-screen fixed overlay (z-index: 100001), var(--color-surface) background, vertical links at 1.5rem, fadein animation.
Mobile a11y aria-expanded, aria-label toggling, Escape key closes, body scroll lock when open.

Sticky bar: position sticky at top, z-index 99999.

Light Yellow (#ffff00) background, black text
Dark Blue (#5dade2) background, black text
Vibrant Pink (#FF0080) background, white text
Terminal Terminal green (#00FF41) background, black text

Content table (.content-table): a lightweight table used for structured lists across all pages.

.pl-year Optional first column: year/date, nowrap, secondary color, 1% width
.pl-name Name column: nowrap, bold label with optional small subtitle
.pl-desc Description column: secondary color, wrapping text

Table behavior rules.

First row No top padding (aligns with label baseline)
Last row No bottom border or padding
After paragraph p + .content-table adds top border and padding on first row
Mobile .pl-year hidden, data-year attribute shown as small label above name

Other components.

Custom bullets ⚬ character, tertiary color, 0.9em indent. Navigation excluded.
Blockquotes Surface-secondary background, 4px --color-accent-1 left border, 0.95rem text. Accent 1 is yellow in light/dark/terminal, pink in vibrant.
Figures 1.5rem margin, caption 0.8rem italic in meta color
Header Flex container: H1 left, inline meta right (language switcher, page note), baseline-aligned. Stacks vertically on mobile.
Footer Desktop: flex row, copyright left, theme links + DS link right. Mobile: stacked column, right-aligned, theme <select> dropdown replaces inline links.
Contact Form
AI agent-ready by design

Contact form (.contact-form): loaded via contact-form.css on the Contact page only. All fields are fully theme-aware through CSS custom properties.

Field layout .contact-form-field wrapper, 1rem bottom margin. Label above input, display: block, font-weight 500, --color-primary.
Inputs / textarea Full-width, 0.5rem padding, 4px border-radius. Border: --color-divider. Background: --color-surface. Text: --color-primary via both color and -webkit-text-fill-color (prevents browser override).
Select Native appearance removed. Custom ▾ arrow via ::after on the field wrapper (:has(select)). Options get explicit background/color to override browser defaults in dark themes.
Focus state No default outline. Border color switches to --color-primary.
Autofill override :-webkit-autofill uses -webkit-box-shadow: 0 0 0 1000px var(--color-surface) inset to suppress the browser's autofill background color, plus -webkit-text-fill-color: var(--color-primary).
Submit button Filled: --color-primary background, --color-surface text. Hover: inverted (surface background, primary text). Disabled: 50% opacity.
Form messages Hidden by default. Success: --color-success background, --color-black text. Error: --color-error background, --color-black text. Black is used (not primary) because --color-primary in terminal is the same green as --color-success.
AI agent-ready Explicit <label for> associations, standard name attributes, no JS-only submission barrier: intentionally usable by web-browsing AI agents and MCP browser tools.

Chrome WebMCP Early Preview ↗: a standard for exposing structured tools to AI agents. Standard HTML form actions map to the declarative model.

Accessibility
Skip link Hidden by default (top: -40px), visible on focus (top: 6px). High contrast black/white.
ARIA labels Navigation: aria-label="Main navigation". Current page: aria-current="page". Mobile toggle: aria-expanded, aria-label toggling.
Semantic HTML <header role="banner">, <nav role="navigation">, <main role="main">, <footer role="contentinfo">
Hreflang CV pages include hreflang tags for de/en with x-default fallback to English
CSS Architecture
poole.min.css Base framework (Poole by @mdo)
poole.overrides.min.css Custom overrides: two-col layout, content tables, navigation, footer, responsive styles
project.css Project-specific components: column grids, figures, project cards and headers
animations.css Animation definitions
contact-form.css Contact page only: form fields, select arrow, autofill override, button states, success/error messages
themes.css All CSS custom properties, theme definitions (light, dark, vibrant, terminal), and variable application rules. Loaded from /_themes/ submodule.
Changelog
2026-02-23 Added .columns-4 grid variant (4 equal columns, collapses to 2 on mobile). Updated design system docs to document .columns-4 and note shared naming convention with teaching.stoll.studio. Added cross-site theme carry: links between sister sites now pass the current theme as a URL parameter. Added Design System link to teaching.stoll.studio footer.
2026-02-22 Token system refinements. Added --color-meta and --color-meta-secondary semantic tokens to all 4 theme sections (figcaptions, project meta headers, blockquote citations, subtitles, credits: cascade via Tertiary/Quaternary). Changed --color-divider to reference Border Strong instead of Border Secondary in all themes (unified cascade from :root). Removed hardcoded rgba overrides for --color-meta/--color-meta-secondary in vibrant and terminal theme blocks: now resolved via CSS cascade through base tokens. Updated Figma variables to match.
2026-02-21 Documentation audit against themes.css source of truth. Added missing tokens across all themes: --color-image-bg (#d5d5d5) to light theme; Accent 3, Border Strong, and full Status Colors tables to dark, vibrant, and terminal themes. Corrected all four themes' "Link Hover" rows: no per-theme hover color token exists; hover is a global opacity: 0.75 on a:hover/a:focus. Fixed terminal theme: all three accents unified to #00FF41 (was yellow/cyan); Surface Emphasized #0A0A0A→#111111, Surface Secondary #050505→#222222; text colors Secondary–Light corrected from hex to rgba opacity variants. Added Contact Form component section. Fixed form message text color: --color-surface → --color-black. Updated CSS Architecture table.
2026-02-19 Renamed .project-list → .content-table across both repos: it's the generic default table style, not project-specific
2026-02-13 Added Terminal theme with bright green on black aesthetic and IBM Plex Mono throughout. Renamed themes: "default" → "light", "teaching" → "vibrant"
2026-02-12 Mobile hamburger navigation with full-screen overlay, footer theme select dropdown for mobile, --color-divider semantic token for structural dividers
2026-02-11 Added theme switcher to footer, dark theme sticky bar fix, navigation active/hover states, content tables across all pages, CV language switcher, Projects in navigation
2026-02-07 Initial design system documentation, theming system with URL-based switching
System Musings Log
2026-02-22 Status tokens: their own tier, or not?
Status tokens (info, success, error, warning) are semantically meaningful: they describe intent, not raw values. That makes them feel like they belong in the semantic tier. But semantic tokens reference base tokens, and status colors don't have obvious base equivalents to reference. Promoting them to base tokens just to create a reference chain adds indirection without clarity. Keeping them as their own tier is a pragmatic compromise, but it breaks the clean base to semantic to component cascade logic. No resolution yet.