Skip to content
Design system

Foundations

Color, type, space, motion, icons, Ducky, and the principles behind them.

Principles

The product rules every tool inherits. If a design decision conflicts with one of these, the principle wins.

Privacy-first

Everything runs locally in the browser. No accounts, and no data or files leave the device unless a tool explicitly says so. The only thing sent anywhere is anonymous, EU-compliant analytics and error reports.

Browser-first

Prefer native browser APIs and client-side processing. A backend is the exception, never the default.

Fast & lightweight

Shared bundles stay lean. Heavy dependencies (editors, WASM) load lazily, per tool, only when needed.

Focused

Each tool does one job well. Inputs, controls, output — nothing competing for attention.

Accessible

Keyboard-first, screen-reader friendly, visible focus, reduced-motion aware. Not an afterthought.

Composed, not re-invented

New tools pick a template and compose these components. They inherit type, color, motion, focus, and hover from globals.css and the shared primitives — never from a per-tool CSS patch.

Colors

Every color comes from a semantic token defined in globals.css — components never use raw palette classes. Toggle the theme in the header: all swatches below resolve per-theme.

Surfaces & structure

Both themes sit off pure white and pure black — full-white surfaces glare. The ladder is ordered by lightness: the sidebar reads recessed, the page sits between, and cards float a hair brighter. Elevation comes from that lightness step, not from shadows.

--sidebarSidebar (recessed)
--backgroundPage background
--cardSurface / panels (raised)
--popoverFloating surfaces
--mutedMuted surface, wells
--borderBorders & dividers
--inputControl borders

Content & interaction

--foregroundPrimary text
--muted-foregroundSecondary text
--primaryAccent fills, primary actions
--primary-textAccent as text: links, hover, selected labels
--secondarySecondary fills
--accentHover fills
--ringFocus rings

Status

Status is never communicated by color alone — always pair with an icon or text.

--successValid, complete, passed
--warningCaution, lossy, degraded
--infoNeutral information
--destructiveErrors, destructive actions

Chart & palette output

For generated palettes, charts, and data visualization inside tools.

--chart-1Palette output 1
--chart-2Palette output 2
--chart-3Palette output 3
--chart-4Palette output 4
--chart-5Palette output 5

Translucent tints need a theme-stable token, not primary. --primary is a solid button fill and gets darker in dark mode (L .457 → .398), so bg-primary/25 over the dark surface separates by only ΔL .063 — half of what the same class gives in light — and reads as invisible. Highlight overlays should either raise the dark-mode alpha or switch to a bright, theme-stable token: Word Counter's keyword marks use bg-primary/25 dark:bg-chart-1/35, landing both themes in the same visible band. Status tints are safe because success / warning get brighter in dark mode.

Achromatic tokens in globals.css write hue as none, not 0. A written 0 is red;color-mix(in oklch) then pulls a pink cast into gray mixes. Usage rule: build surfaces from bg-background / bg-card / bg-muted, text from text-foreground / text-muted-foreground, and status from success / warning / info / destructive. One accent (primary) per screen. Ad-hoc hex values and Tailwind palette classes (e.g. bg-zinc-100) are not allowed in components.

Typography

Geist Mono is the interface default — labels, controls, data, and body copy. Noto Sans (font-heading) is reserved for page and section headings. Geist Sans (font-sans) exists for long-form prose when mono hurts readability.

Scale

Display heading
Page title
Section heading
Subsection heading

Body text — the default reading size for descriptions and instructional copy. It stays at text-sm across all breakpoints.

Small text — captions, metadata, timestamps, and secondary explanations.

Form & status text

Overline labelField labelHelper text explains a control without stating the obvious.Error text states what went wrong and how to fix it.Success text confirms the outcome.Warning text flags something lossy or partial.

Code & data

Inline code like clamp(1rem, 2vw, 1.5rem) sits on a muted chip.

{
  "name": "tools",
  "private": true,
  "processing": "local-only"
}
1.618numeric result — always tabular-nums

Content extremes

A deliberately long multi-line tool title that wraps gracefully instead of truncating or overflowing its container

Long descriptions stay at reading width (max-w-prose), even when the workspace around them is full-width. Dense technical copy keeps leading-relaxed so mono text never feels cramped.

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==

Rules: one h1 per page; heading levels never skip; long unbroken strings get break-all; numbers that update get tabular-nums so layouts do not shift. Body copy inherits text-wrap: pretty from :root; headings h1–h4 use balance; multi-line editors that must not reflow mid-keystroke set [text-wrap:stable].

Spacing & Layout

A 4px base unit, two density modes, and sharp corners everywhere. Tools pick one density per page and stick to it.

Spacing scale

1 · 4px — icon-to-text
2 · 8px — inline gaps, control clusters
3 · 12px — inside compact components
4 · 16px — form rows, card padding (compact)
6 · 24px — card padding, stack spacing
8 · 32px — between component groups
16 · 64px — between page sections

Density

Controls are h-8 by default (compact, data-dense tools) with h-7/h-6 for toolbars. Comfortable layouts use gap-6 / p-6; compact ones gap-4 / p-4.

Comfortable — gap-6 / p-6
Compact — gap-2 / p-4

Shape & elevation

Interactive controls are square (rounded-none) — this is the site's signature. Depth comes from borders and background steps, not shadows; only floating layers (popovers, dialogs, toasts) cast shadow.

surface
well
floating
focus ring

Page widths

workspace · max-w-7xl — editors, tables, canvases
reading · max-w-prose — descriptions, help
narrow · max-w-md — simple converters

Breakpoints: single column below sm; split panes stack vertically below lg; the section navigation hides below lg. Page gutters are px-6 on desktop, px-4 on mobile. Decorative hover uses the hover-fine: variant (fine pointer + hover capability). Phone chrome pads with env(safe-area-inset-*); the viewport is viewportFit: "cover". Desktop html sets overscroll-behavior-y: none, restored to auto on coarse pointers.

Motion

Motion exists for comprehension and feedback, never decoration. CSS transitions are the default and must name the properties they change — never transition-all. The motion library is reserved for gestures and layout animation, loaded per tool.

Durations

Hover & press150msnamed CSS transitions
Text swap150mstext-states-swap, ease-in-out
Icon swap250msicon-swap, ease-in-out
Label width300mscard-resize, cubic-bezier(0.22, 1, 0.36, 1)
Number pop-in500ms8px, 2px blur, 70ms stagger, overshoot ease
Expand / collapse200msCSS, ease-out
Dialog & popover200msfade + zoom-95
Selection blink260msmenu highlight off 100ms, on 160ms, then close
Toast500mscubic-bezier(0.22, 1, 0.36, 1)

Entrance pattern

Staggered fade-up (12px, ~400ms) for content appearing on load or after processing. Never more than one stagger per view.

1
2
3

Value transitions

Numeric results use transitions.dev number-pop-in: changed digits travel 8px with 2px blur, a 500ms overshoot ease, and 70ms stagger across the cells that actually changed. Unchanged digits stay still. Reduced motion snaps.

5.59234

State swap

CSS is the house way: TextStateSwap and IconSwap, not more motion/react. Text uses transitions.dev text-states-swap (old label exits up with blur, new one enters from below). The label slot width tweens between the two sizes so the button eases instead of snapping (card-resize, 300ms). Icons stay stacked in one grid cell and cross-fade with scale + blur (icon-swap, generalized to n states so Copy can do idle/success/error). Reduced motion snaps.

Selection blink

On macOS, a menu item blinks once before the menu closes — highlight off, then back on — so the click is confirmed. Web menus usually close on the same frame. CommandItem, DropdownMenu items, Select, Combobox, and PhoneActionsMenu (via the shared dropdown) all use useSelectionBlink: 100ms off, 160ms on, then the action runs. Keyboard Enter takes the same path. A second activation during the blink is ignored. prefers-reduced-motion skips the wait entirely.

Built in once on the shared primitives, not copied per tool. The restore holds for 160ms so the confirmation is still on screen when a command bar or menu closes; about a quarter of a second in all.

Feedback pattern

State changes get instant visual confirmation: hover the card, or press the button to see the press-down affordance shared by all buttons.

hover me

Name every transition (transition-colors, transition-[width], never transition-all). Gate decorative hover with hover-fine: so a tap on a coarse pointer does not leave the hover tint stuck. Reduced motion: every non-essential animation is disabled when prefers-reduced-motion is set — CSS via the motion-safe:/motion-reduce: variants, and motion-library animations via its reduced-motion handling. Spinners and progress indicators remain (they communicate state), but nothing slides, zooms, or staggers.

Icons

lucide-react is the icon set for the whole site. A small subset also has a hand-animated counterpart in @/components/icons for interactive controls.

Animated

Animated icons live in @/components/icons, animate on parent hover/focus via useIconAnimation, and are reserved for interactive controls — tool actions and the site chrome (sidebar navigation, top bar, workbench gate).

State-driven

Unlike hover-animated icons, these animate on a state change. The panel toggle slides its divider line to mirror the sidebar's open side; expand-shrink is a hybrid — it nudges its arms on hover and swings them 180° between lucide's expand and shrink on click. Click to preview.

Static (lucide-react)

Category glyphs
accessibility
binary
braces
calculator
image
paintbrush
pen-tool
terminal
Status & severity
info
triangle-alert
octagon-x
circle-check
circle-x
loader-2
Navigation
chevron-down
chevron-up
chevron-right
arrow-right
arrow-left
arrow-left-right
panel-left
Actions
plus
minus
x
check
copy
pencil
trash-2
shuffle
rotate-ccw
redo-2
undo-2
grip-vertical
more-vertical
search
Files & structure
file
file-json
inbox
minimize-2
shield-check
square-stack
Layout & devices
grid-2x2
maximize
monitor
smartphone
tablet
Misc
construction
house
help-circle

Default size is size-4 in controls. Reach for the animated counterpart only when an icon sits in a user-triggered action (buttons, copy, upload/download). Status and severity icons (info, warning, error, success, loading) never animate. Icons without an animated counterpart stay static lucide, even inside interactive controls.

Decorative icons always get aria-hidden, and normally stay static — the one exception is geek stats, where every box title carries an animated glyph that plays once as its block scrolls in. That is driven by PanelIcon, which fires the samestartAnimation handle off first viewport entry instead of hover, then releases it once the animation has played out. Reserve that pattern for showcase pages; product surfaces keep decorative icons still.

Ducky

Ducky, the rubber duck from the launch video, is the site's mascot: a 4×4 ordered dither of a few ellipses, drawn in code in src/lib/pixel-duck.ts and rendered by PixelDuck. It shows up where a page has nothing to show yet, or something to own up to.

Poses

Each pose in both looks: inked (an outline and its shading) for light grounds and dithered (its lit parts) for dark ones. With look="theme", the default, Ducky follows the site theme, so he stays white on either.

PlainThe 404 page. It bobs gently.
TalkingThe Konami code easter egg (↑ ↑ ↓ ↓ ← → ← → B A), beak open on each voiced letter.
HammeringLocked WIP tools and their Open Graph cards: a construction helmet, swinging between the wind-up and the hit.
ExperimentingThe beta notice and beta tools' Open Graph cards: goggles and a test tube whose bubbles rise.