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 bordersContent & interaction
--foregroundPrimary text--muted-foregroundSecondary text--primaryAccent fills, primary actions--primary-textAccent as text: links, hover, selected labels--secondarySecondary fills--accentHover fills--ringFocus ringsStatus
Status is never communicated by color alone — always pair with an icon or text.
--successValid, complete, passed--warningCaution, lossy, degraded--infoNeutral information--destructiveErrors, destructive actionsChart & 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 5Translucent 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
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
Code & data
Inline code like clamp(1rem, 2vw, 1.5rem) sits on a muted chip.
{
"name": "tools",
"private": true,
"processing": "local-only"
}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
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.
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.
Page widths
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
Entrance pattern
Staggered fade-up (12px, ~400ms) for content appearing on load or after processing. Never more than one stagger per view.
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.
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.
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)
accessibilitybinarybracescalculatorimagepaintbrushpen-toolterminalinfotriangle-alertoctagon-xcircle-checkcircle-xloader-2chevron-downchevron-upchevron-rightarrow-rightarrow-leftarrow-left-rightpanel-leftplusminusxcheckcopypenciltrash-2shufflerotate-ccwredo-2undo-2grip-verticalmore-verticalsearchfilefile-jsoninboxminimize-2shield-checksquare-stackgrid-2x2maximizemonitorsmartphonetabletconstructionhousehelp-circleDefault 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.