A Hypertext Article Series · Begun April 2026
Design
Primitives
A taxonomy of the foundational decisions that determine whether a design system holds together under pressure — from token to component, from pixel to pattern, desktop first.
What this is
Most design system documentation tells you what to do. This one tries to explain why each decision exists — and what breaks when you get it wrong.
A design primitive is any building block that cannot be decomposed further without losing its meaning. Color is a primitive. Typography is a primitive. Spacing is a primitive. A button is not — it is a composition of primitives, and its correctness depends entirely on the quality of the decisions made at the primitive level.
This series moves through those decisions layer by layer. Each chapter is a deep reference on one primitive: its structure, its variables, its failure modes, and the decisions that compound across a system. Where it helps, there are live specimens — rendered HTML you can interact with in the browser.
The goal is not to produce a design system. It is to produce the vocabulary and judgment needed to evaluate any design system — and to build one that holds.
The scope is web applications. Not marketing sites, not mobile apps, not native software — though the principles bleed across boundaries. Within that scope, the perspective is biased toward desktop and pointer-driven interfaces, which are examined first and most thoroughly. Mobile and touch are covered as a layer on top, not as the primary frame.
Why desktop first
The conventional wisdom since 2010 has been mobile-first. As a browser rendering strategy, it remains sound. As a design strategy for application development, it deserves scrutiny.
Mobile-first works well for content sites and simple transactions. It struggles with applications that have complex state, dense data, multiple panels, precise interactions, and users who spend hours in the product each day. For those applications — productivity tools, dashboards, IDEs, CRMs, financial products, creative tools — the desktop canvas is not a large phone. It is a fundamentally different medium.
Desktop challenges
- Canvas size with no natural constraint
- Hover as a distinct interaction state
- Pointer precision enabling dense layouts
- Multiple modalities (keyboard, mouse, trackpad)
- Multi-panel and multi-window compositions
- Right-click context menus
- Drag, resize, reorder, and scroll nesting
- Higher density information expectations
Mobile simplifications
- Canvas width is the primary constraint
- No hover state — only active
- Touch targets set a minimum density floor
- Single modality — touch
- Single-panel, sequential navigation
- No right-click
- Drag is gesture-only, limited use cases
- Lower density is a feature
Mobile-first tends to produce design systems optimized for touch targets, linear flow, and minimal density. When those systems are scaled up to desktop, the result is often spacious but underpowered — a mobile app rendered at 1440px wide. The inverse is harder but more generative: a system designed for the full complexity of desktop, with a mobile layer that reduces and simplifies.
That is the strategy here. Each chapter establishes the desktop treatment completely before addressing how it adapts downward.
The stack
Design primitives form a dependency hierarchy. Decisions at the foundation constrain everything above them. Components cannot be more coherent than the tokens they draw from. Tokens cannot be more coherent than the scale decisions that generate them.
Principles & Constraints
Brand character · Density posture · Motion philosophy
Scales & Foundations
Color · Type · Space · Radius · Shadow · Duration
Semantic Tokens
surface.default · text.muted · border.interactive · action.primary
Base Components
Button · Input · Checkbox · Label · Icon · Badge · Tooltip
Composite Components
Form · Navigation · Modal · Table · Date Picker · Combobox
A change at any layer propagates upward. Adjust the base spacing unit and every component reflows. Change the primary color and every interactive element shifts. This is what makes the lower layers so consequential — and why they deserve more careful treatment than they typically receive.
The articles in this series follow this stack from the bottom up. Foundation chapters come first. Component chapters reference the foundation decisions they depend on. Interaction chapters cut across the full stack.
Chapters
Each chapter is a standalone reference. You can read them in order or jump to what you need. Earlier chapters are assumed knowledge in later ones.
I — Foundations
-
01
Color
Scale construction, semantic layering, light and dark modes, contrast requirements, and the decisions that determine whether a color system is extensible or brittle.
Planned
-
02
Typography
Typeface selection, type scale construction, hierarchy, line height and measure, and the mechanics of rendering text at every size the system will use.
Planned
-
03
Spacing & Density
Base units, scale generation, component padding, gap relationships, and the concept of density posture — how a system decides between compact and comfortable.
Planned
-
04
Grid & Layout
Column grids, breakpoints, layout primitives (sidebar, main, panel), and the desktop-specific challenge of filling a wide canvas without producing an undirected composition.
Planned
-
05
Elevation & Depth
The z-axis in web interfaces — shadows, blur, layering, and the semantic vocabulary of surface elevation. What raises, what recedes, and why it matters for focus management.
Planned
-
06
Motion & Easing
Duration scales, easing curves, the physics metaphors that make transitions feel honest, and the performance constraints that determine which properties should ever be animated.
Planned
-
07
Border & Radius
Radius scales, border weight, when to use border vs. shadow vs. background change to separate surfaces, and how radius decisions encode the character of a product.
Planned
-
08
Iconography
Icon grid and weight, sizing relative to text, filled vs. outlined vs. duotone, icon-only accessibility, and the coherence problems that arise when mixing icon families.
Planned
II — Base Components
-
09
The Button Taxonomy
Anatomy, hierarchy (primary through ghost), size scales, icon integration, loading and disabled states, and hover and motion systems. The most complete reference in this series.
Published · 6 parts
-
10
Text Inputs
Anatomy, proportion, label placement, placeholder vs. floating label, prefix and suffix patterns, validation states, and the sizing relationship between input and surrounding form.
Published · 2 parts
-
11
Select & Combobox
Native select vs. custom dropdown, the anatomy of the listbox, search and filter within selection, multi-select patterns, and the popover positioning problem.
Draft
-
12
Checkbox, Radio & Toggle
When to use which, the sizing and hit-area relationship, indeterminate states, group alignment, and the label association requirements that are more commonly wrong than right.
Planned
-
13
Date & Time
Calendar anatomy, date range selection, time input patterns, timezone display, and the compounding complexity of date-time inputs in international products.
Draft
-
14
Color Input
The spectrum of color picker fidelity from simple swatches to full HSL/hex editors, and how to match input complexity to the precision the use case actually requires.
Planned
III — Composite Components
-
15
Navigation
Top nav, sidebar nav, tabs, breadcrumbs — the structural patterns that orient users in complex applications, and the desktop-specific challenge of accommodating many destinations.
Draft
-
16
Overlays: Modal & Drawer
When to block vs. slide, focus trap mechanics, backdrop behavior, size and positioning in large viewports, and the stacking problem when overlays contain overlays.
Planned
-
17
Overlays: Popover & Tooltip
The distinction between tooltip (information) and popover (interaction), positioning and collision avoidance, delay and dismissal patterns, and rich tooltip composition.
Planned
-
18
Feedback & Notification
Inline validation, alert banners, toast notifications, progress indicators, and empty states — the vocabulary of a system that communicates its own status.
Planned
-
19
Data Tables
Column sizing, sorting, filtering, row selection, inline editing, fixed columns and headers, virtualization for large datasets, and density options for data-intensive applications.
Planned
-
20
Forms
Label alignment, field grouping, multi-step flows, validation strategy (inline vs. on-submit), and the layout decisions that determine whether a form feels manageable or overwhelming.
Planned
IV — Interaction Patterns
-
21
Hover, Focus & Active
The complete state model for interactive elements — how the pointer, keyboard, and touch modalities produce different state sequences and why each requires distinct treatment.
Planned
-
22
Keyboard Navigation
Focus order, roving tabindex, composite widget patterns (grid, listbox, toolbar), keyboard shortcuts, and the desktop reality that many power users never touch the mouse.
Planned
-
23
Drag, Resize & Reorder
The full drag interaction model — hit areas, drag handles, drop targets, ghost images, scroll-on-drag — and the desktop-specific patterns that have no mobile equivalent.
Planned
-
24
Loading & Skeleton States
Optimistic updates, skeleton screens vs. spinners, progress communication, error recovery, and the interaction design of latency — making waiting feel intentional rather than broken.
Planned
How to read this
Each chapter is a self-contained HTML document with live rendered specimens. The specimens use real CSS and real HTML — no screenshots. You can inspect them, modify them, and observe how the design behaves rather than simply reading about it.
Chapters reference each other. A chapter on button states will point back to the motion chapter for duration values. The navigation chapter will reference the color chapter for active state treatment. Following those references is worthwhile — the dependencies are real, and understanding them is the point.
Design primitives are not rules. They are decisions with consequences. This series tries to make the consequences legible so that you can make better decisions — including the decision to deviate deliberately, which is different from deviating by accident.
The series has a point of view. It favors restraint over expressiveness, coherence over novelty, and utility over aesthetics. Where there are genuine trade-offs with no clear winner, it says so. Where there is a right answer that the industry has largely converged on, it says that too — and tries to explain why convergence happened.
Chapters marked Published are complete. Chapters marked Draft are in progress and may be incomplete or subject to revision. Chapters marked Planned do not yet exist.
Design Primitives · A hypertext article series · Desktop web, by necessity.