Design foundations

Overview

Tokens connect reusable values to their purpose in an interface. This system has three layers: primitives, semantic roles, and component aliases.

1. 1. Primitives

   The available palette, type scale, weights, radii, and durations.

   --palette-indigo-base: #3c41bf

2. 2. Semantic roles

   Values named for their purpose. A role can change between light and dark themes.

   --color-action-background: var(--palette-indigo-base)

3. 3. Component aliases

   Scoped settings for the component’s rendered properties, geometry, or motion.

   --button-background: var(--color-action-background)

One value, three levels

The button receives its color through a semantic role. The role can change with the theme while the component keeps the same API. Separate roles retain separate names even when their current values match.

Naming and ownership

Names use lowercase kebab-case. Primitives describe a value or scale (--font-size-18); semantic roles describe a purpose (--color-action-background-hover); component tokens begin with their owner and identify a property (--button-background-hover). Variants and states follow the property. Default states omit a suffix; themes keep the same names and change their values.

Background, text, border color, font size, and font weight have distinct names. A token named for a component’s background controls that background in every appearance variant. For example, --button-background is transparent on an outlined button. Shared roles belong in the theme; local component settings stay with their component, and one-off artwork geometry stays local.

Color values and component assignments below are generated from the same CSS used on the site. The component tables include responsive, state, and theme overrides. A component setting must be overridden on its owning element; setting it only on a parent does not replace a value declared by the component itself.

Why am I doing all this?

I want to make the thinking behind this site visible. Even a small personal site involves decisions about hierarchy, typography, color, spacing, interaction, and accessibility. Applying design thinking means understanding how those decisions work together, testing them, and refining them as the site grows.

Managing those decisions is a skill in itself. This reference shows how I turn individual choices into reusable patterns, document their purpose, and keep the experience consistent as things change.

Color roles

Color primitives describe the palette. Semantic roles describe purpose: surfaces, text, actions, borders, overlays, and focus indicators. Component aliases select those roles for a particular element.

The alias examples below show the light-theme relationships. A theme can override a semantic role without changing the primitive palette or the component API.

Palette

Semantic organization

• Surfaces: --color-surface-page, --color-surface, and --color-surface-* identify the surrounding canvas.
• Foregrounds: --color-text-* and --color-link identify readable ink. Decorative brand colors remain separate from inline link ink.
• Interaction: accent, hover, focus, border, and overlay roles describe states and boundaries.

The light and dark token table lists every semantic color role with its values and aliases.

Spacing

Spacing follows a 6px rhythm at the default root size: 0.5rem is 6px and 1rem is 12px. Shared layout roles define gutters and section padding; component-specific gaps remain local where no shared role exists.

Shape and elevation

Radius primitives describe geometry. Component shape roles keep independently changeable decisions separate, even when values match. Focus geometry defines ring width and offset; elevation tokens are complete shadow recipes, while shadow color roles hold only a color.

Light and dark themes

Each semantic color role has a light and dark value. The table shows both resolved colors and their aliases; unchanged roles inherit their light definition. The page theme follows system preference until a manual selection is made. A system-theme change while the page is open clears that manual selection.

Foreground and surface pairs

--color-text-primary pairs with page and raised surfaces. --color-text-inverse pairs with contrasting surfaces. The brand surface has a dedicated foreground role. Component aliases select a complete pair rather than changing a fill in isolation.

Typography

Albert Sans carries headings, labels, metadata, and controls. Source Serif 4 carries reading text and quotations. The type scale supplies reusable values; semantic roles and component recipes determine where those values appear.

Families and weights

Bundled Albert Sans faces are 400, 600, and 900; Source Serif 4 faces are 400, 700, and 900. A requested weight of 700 in Albert Sans matches the available 900 face under the CSS font matching rules. The values below describe requested CSS weights, not a promise that every family has every face.

Text styles

Examples show the wide-screen recipe. Responsive values and context-specific exceptions are listed with each style.

Size and line-height inventory

Button

Buttons express actions or prominent destinations. Appearance, intent, surrounding surface, and size are independent dimensions of the component.

Examples

The examples show filled and outlined treatments, accent and neutral intent, and the supported surfaces. Specimen buttons have no application action.

Size and accessories

Specifications

The homepage’s filled CTA uses --button-background → --color-action-background. Its outlined résumé CTA sets that same component token to transparent. Both hover backgrounds use --button-background-hover. Intent and surface modifiers select the background/text pair; size modifiers and responsive rules update font and spacing settings.

The testimonial pause control uses a neutral background when selected, retaining its accent border. The hero and closing CTA use 16px labels, 10px inline padding, and 6px gaps at ≤800px. Their decorative icons are 23px, reducing to 20px at that breakpoint. Font and spacing overrides appear in the token table; decorative icon geometry stays local.

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Usage

• Navigation: an anchor with a destination retains native link behavior.
• Actions: a native button represents an in-page operation.
• Disabled state: native buttons use disabled. An unavailable anchor has no href and carries aria-disabled="true".
• Accessories: button__icon sits before or after the label. Decorative icons are hidden from assistive technology; the visible label names the action.
• Composition: a button-style affordance inside an already interactive card is noninteractive, avoiding nested controls.

Markup

<a href="/" class="button button--outline button--neutral">Home</a>
<button type="button" class="button button--compact">Pause scroll</button>

Contact CTA and footer

A closing composition combines a contact invitation, primary and secondary destinations, decorative artwork, credit, and a contact link group.

Example

Specifications

Template API

The default template and the 404 variant share the same anatomy and styling. The variant changes only the credit suffix.

<!-- include:site-footer -->
<!-- include:site-footer {"variant":"404"} -->

Dialog

A modal dialog holds a focused task above the page. The native dialog element contains keyboard focus while open and supports Escape dismissal; the shared controller restores focus to the opener.

Example

A shared dialog

A dialog keeps a focused task separate from the underlying page. Its content scrolls within the viewport while the close action remains available.

Specifications

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Usage

A dialog has a unique accessible name connected through aria-labelledby. Descriptive text can be connected through aria-describedby. The opener identifies the dialog, and the close action has an explicit accessible name. The inverse surface variant changes fill and ink together.

Editorial composition

Editorial layouts pair readable prose with supporting artifacts. Blocks stack headings and prose; paired rows place media alongside text on wide screens and stack in narrow portrait layouts.

Example

Text beside an artifact

A paired layout places an artifact beside its explanation, keeping the evidence and the decision in the same reading context.

The composition stacks on narrow portrait screens. Prose, media, and the space between them retain a consistent rhythm as the layout changes.

Specifications

Metadata

A metadata group pairs a term with its value. Groups wrap as space narrows, and longer values wrap within a 300px maximum measure.

Example

Client

Example organization

Main Skills

Research, interaction design, and a deliberately longer description to check wrapping

Year

2026

Specifications

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Project card

A linked project summary combines artwork, a category badge, a title, and metadata. The containing layout determines card width; the component owns its internal spacing and image treatment.

Example

Example

Project title

Client

Client name

Main Skills

Design disciplines

Year

Year

Specifications

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Content and behavior

The complete card is one native link. Titles and metadata wrap with content. Artwork uses a cover crop, so essential visual information belongs away from the image edges. Lazy loading and responsive image candidates preserve the same fallback image and text when JavaScript is unavailable.

Tags and badges

Tags describe content without implying selection or navigation. Badges use a compact treatment over imagery; inverse tags sit on accent surfaces.

Examples

• Product design
• A longer descriptive label
• Case study

Specifications

Token definitions and overrides

Generated from production CSS. Rows are grouped by source file, not cascade priority. Each row shows an authored assignment and its selector or media condition; specificity, stylesheet order, and matching conditions determine the result. Component tokens are scoped to their owning element. Dark template selectors apply in both system and explicit dark modes.

Testimonial

A testimonial combines a quotation with an author, role, and optional portrait or destination. The example uses fictional attribution and a neutral portrait placeholder.

Example

Specifications

Content and behavior

The quotation remains plain text. The portrait is decorative because the attribution names the author. When a destination is present, only the attribution is linked. A carousel is a separate composition; the quote component itself is static.

Cursor family

The cursor family distinguishes ordinary content, actions, and draggable content on fine pointers. Artwork is enlarged below for inspection; hovering each tile previews its native cursor. Touch input retains native behavior.

Default

--cursor-default

Hotspot 4, 3 · fallback auto

Interactive

--cursor-interactive

Hotspot 16, 3 · fallback pointer

Grab

--cursor-grab

Hotspot 19, 20 · fallback grab

Grabbing

--cursor-grabbing

Hotspot 19, 20 · fallback grabbing

Text selection

Usage

The default cursor belongs to ordinary content. The interactive cursor identifies actionable elements. Grab and grabbing represent available and active drag states. Editable text keeps the native text cursor.

Motion and accessibility

Motion roles separate duration from easing. Components combine a duration and easing token with a named animation or a property transition. Shared roles are listed below; local timings remain identified as component-specific values.

Animation examples

Previews are static until replayed. Reduced motion keeps them static.

Interaction and accessibility

Project cards lift 6px on hover using --motion-duration-interaction and --motion-easing-standard. Pressed buttons move down 1px using --motion-duration-feedback. Dialogs enter with fadeUp and --motion-duration-dialog-enter.

Reduced motion suppresses entrances and continuous animation, shortens transitions, and keeps content visible. Carousel playback starts paused and requires an explicit action to resume. The replay examples remain static while reduced motion is active.