Design System

Maintainer note: this page is the stable entrypoint for design-system references. Keep the source map current whenever component paths, control primitives, or motion behavior changes.

Purpose

This is the authoritative reference for the Portfolio App's visual design system. It exists so a developer (or the author, months later) can understand the aesthetic intent, find any design parameter in source, and change it safely. The durable why of the design direction lives in the architecture ADR (see References); this reference is the what and the where.

Boundary with UX Engineering Standards

This reference owns what the interface looks like: the design tokens (color, typography, scale), the control-panel component primitives, and the materiality conventions. A separate page, UX Engineering Standards (engineering domain), owns how the interface must behave: accessibility (WCAG AA, keyboard, focus, ARIA, semantic HTML), motion and performance rules (prefers-reduced-motion, GPU-only animation), responsive/mobile-first doctrine, and testing approach. Every component documented here must meet the standards documented there. The two pages cross-link; neither duplicates the other.

How the redesign is documented (three complementary homes)

Design work is recorded in three places, each with a distinct job; none duplicates the others:

1. The visual-identity ADR (10-architecture) holds the why: the decision, the alternatives, the constraints, and the deferral of true 3D. The durable rationale.
2. This Design System reference (20-engineering) holds the what and where: token values, component contracts, materiality conventions, and the source map. The maintainer's reference.
3. The feature catalog (00-portfolio/features) holds the reviewer-facing capability view: user-facing design features (e.g. the hero, the live metrics dashboard) are documented there as feature pages following template-feature-details.md, with low-tech and technical summaries and verification steps. Where possible these fold into existing feature groups (the hero extends "Navigation and UX Polish" and "Theming and Accessibility"); a genuinely new capability such as the live metrics dashboard may warrant its own feature-group page.

In short: why lives in the ADR, what/where lives here, what a reviewer sees and how to verify it lives in the feature catalog. This reference stays focused on tokens, components, and source mapping, and does not restate the feature-catalog content.

Scope

In scope: the design tokens (color, typography, scale), the reusable control-panel component primitives, the materiality and motion conventions, and a map from each of these to its location in the portfolio-app source tree.

Out of scope: the behavioral standards every component must meet (accessibility, motion/performance rules, responsive doctrine, testing) — those live in UX Engineering Standards; copy/content strategy; information architecture; the historical sequence of how the system was built (that is not documented as narration by design).

The aesthetic in two sentences

The interface presents one coherent hardware fiction in two states: light mode is warm beige institutional hardware in daylight (powered down), and dark mode is the same hardware powered on with phosphor instrumentation. It is stylized and confidently web-native (not photoreal), and readability always wins.

Phase 2C token lock (current)

• Light mode palette (locked): #E8E2D0 page base, #D4CBB3 surface, #C9BFA3 inset surface, #1A1814 primary ink, #A34722 accent, #9A958A line.
• Dark mode palette (locked): #0A0A0A page base, #1A1814 surface, #211E18 inset surface, #E8E2D0 warm-cream ink, #00FF41 phosphor accent, #003311 divider line.
• Type registers (locked): Space Grotesk (display), Inter (body), JetBrains Mono (mono/readouts), Departure Mono (pixel accent labels and counters).
• Panel grammar (locked): prose on clean background, data in inset panels, interactive controls in raised/outset panels.

Source map (where the design lives in portfolio-app)

Fill in / confirm exact paths during implementation. This map is the single most useful entry on this page for a maintainer or reviewer.

Concern	Source location	Notes
Color tokens (both modes)	src/app/globals.css	Phase 2C lock under :root (dark powered-on) and html.light (beige powered-down)
Elevation tokens (both modes)	src/app/globals.css	Theme-aware depth recipe (--depth-*, sidewalls, cast shadows, inset shell tokens)
Typography (fonts)	src/app/layout.tsx	next/font setup for Space Grotesk, Inter, JetBrains Mono, Departure Mono
Type scale + glow utilities	src/app/globals.css	type-*, type-register-pixel, glow-accent, control-strip/control-link classes
Panel primitive	src/components/Panel.tsx	Elevated + inset variants, rivets, sheen, bevel
Readout primitive	src/components/Readout.tsx	Long string compaction to prevent overlap with adjacent readouts
LabelTag primitive	src/components/LabelTag.tsx	Uppercase mono utilitarian labels/chips
Dial primitive	src/components/Dial.tsx	Generic analog gauge primitive used by legacy/control contexts
ControlButton primitive	src/components/ControlButton.tsx	Deep hardware CTA/control element with inlaid labels for hero and nav
Theme switch primitive	src/components/ThemeToggle.tsx	Cockpit-style backlit rocker with localStorage persistence and html class toggling
Deploy pipeline primitive	src/components/DeployPipeline.tsx	One-time staged LED sequence with post-spec timing (1s per stage)
Nav control strip composition	src/components/NavigationEnhanced.tsx	Full-bleed brand-and-controls control strip, no hamburger/menu toggle
Footer recessed panel	src/app/layout.tsx + src/app/globals.css	Inset footer surface with control-style text links
Hero composition	src/app/page.tsx	Above-the-fold split layout with clean copy area and instrumentation panel
Home module composition	src/app/page.tsx	Module 01-06 order and section-level panel grammar
Operating principles panel	src/components/home/OperatingPrinciplesPanel.tsx	Accessible annunciator (radiogroup/radio) plus aria-live CRT detail
By-the-numbers cluster	src/components/home/ByTheNumbersCluster.tsx	Banked inset instrumentation (seven-segment, nixie, bar, gauge, lamps)
Keycap primitive	src/components/Keycap.tsx	Reusable raised key with tokenized cap/legend variants, sidewalls, and state classes
Keypad primitive	src/components/Keypad.tsx	Inset panel keypad composition built from Keycap descriptors
Career era cards	src/components/home/CareerEraCards.tsx	Four channel-strip style cards for era highlights
Tech stack keyboard	src/components/home/TechStackKeyboard.tsx	Interactive radiogroup keyboard with 21 curated tech-stack keys and CRT detail panel
Tech stack icons	src/icons/TechStackIcons.tsx	16 vendored Simple Icons SVGs + 5 text legends (Java, AWS, Azure, REST, SQL Server)
Design preview	src/app/design-tokens-preview/page.tsx	Canonical rendered component gallery (keep complete and in-sync with component PRs)

Phase 2C.2 implementation notes

• Dark-mode realism uses a lift-with-light approach: depth separation comes from edge highlights and lift halos in addition to shadow stacks, rather than relying on black-on-black drop shadows.
• Elevation behavior is now centrally tunable through theme-aware token groups in globals.css, and consumed by panel, control-button, dial, and keycap/keypad treatments.
• Keycap palette now includes the original 8 roles plus an expanded --key2-* secondary set per theme, with AA-verified cap/legend pairs.
• src/app/design-tokens-preview/page.tsx is the canonical component gallery. Every reusable design-system component must be represented there, and updates belong in the same PR as component changes.

Phase 2C.3 implementation notes

• The keycap stack now uses a dedicated depth language (--depth-raised-top-*, --depth-sidewall-*, --depth-cast-shadow*) to render a clear top-face + sidewall silhouette rather than flat color blocks.
• Dial now uses stable per-instance gradient IDs and a dial-mount shell class so multiple gauges can render concurrently without SVG paint-server collisions.
• Panel default and inset variants were aligned to shared depth tokens so composite assemblies (keypads, control strips, readout banks) inherit one elevation model.
• src/app/design-tokens-preview/page.tsx was rebuilt as the canonical inventory (palette, type, panels, controls, instruments, keys, composites) and includes a mini keyboard module used for visual and accessibility verification.
• Keycap legend AA is now validated against gradient endpoints (lightest + darkest top-face points), not just base fills; token pairs in globals.css and preview constants must stay synchronized.

Phase 2C.1 implementation note

• Keycap and Keypad are currently design-tokens preview primitives only (see src/app/design-tokens-preview/page.tsx).
• Home-page integration was intentionally deferred in this phase; src/app/page.tsx contains TODO markers for future copy and lead-slot promotion decisions.

Phase 2C.4 implementation notes

• TechStackKeyboard is the first production home-page module using Keycap/Keypad as interactive components (not preview-only).
• Keycap width-ratio bug fixed: proportional sizing now uses --keycap-unit CSS variable (3.78rem = base 3.2rem + gap 0.58rem) with explicit width calcs on .keycap--1u|1-25u|1-5u|2u size classes.
• TechStackKeyboard implements the OperatingPrinciplesPanel radiogroup + CRT pattern (accessible annunciator with aria-live=polite detail region) for interactive tech-stack browsing.
• 21 curated keys organized into 6 categories (languages, frontend, backend, data, cloud, tooling), each with hardcoded blurbs.
• Icon assets: 16 Simple Icons SVGs vendored as React components; 5 text legends used for missing or semantically incorrect icons (Java, AWS, Azure, REST, SQL Server).
• Keyboard navigation: arrows/Home/End for traversal, Enter/Space for selection; focus-visible states on all keys.
• Reduced-motion safe: no animation complexity, only CSS state-based styling.

Sub-references

• Components (components.md) — each primitive's purpose, props, accessibility behavior, and source path.
• Tokens (tokens.md) — color values for both modes, mapping, type scale, source paths. (Create when token documentation is fully normalized.)
• Materiality & motion (materiality-and-motion.md) — depth/texture conventions (single top-left light source, bevel/shadow approach, glow intensity) and animation philosophy. (Create when final polish values are locked.)

Validation / Expected outcomes

• A reviewer can locate any design parameter in source within one lookup using the source map.
• A maintainer can change a token or component and know exactly which file to edit and what the convention is.
• The reference stays current: every design phase updates the relevant sub-reference as part of its definition of done.

Failure modes / Troubleshooting

• Source map drift (paths change but the table does not) → updating this table is part of each design PR's definition of done.
• Token values in docs diverging from globals.css → tokens.md is generated/confirmed against source, not authored independently.

References

• ADR-0021: Visual Identity and Design-System Direction — the durable decision and constraints.
• UX Engineering Standards — the accessibility, motion/performance, responsive, and testing standards every component here must meet.
• Design System: Components Reference
• Portfolio App source: globals.css, src/components/, layout.tsx.