Skip to content

docs / design-guide

Design guide

Tokens and components for every deadcode surface. Built on Tailwind v4; all tokens live insrc/styles/global.css.

01

Principles

Neo-brutalism with restraint: raw structure, deliberate color, nothing decorative that doesn't carry meaning.

01

Honest structure

Borders are visible. Boxes look like boxes. Nothing pretends to float.

02

Hard edges

Shadows are solid offsets, never blurred. Radius stays at 2px.

03

One loud color

The accent marks the primary action. Everything else is ink on canvas.

04

Mono for machines

Labels, metadata, and controls are set in mono. Prose is set in the sans.

02

Color

Colors are named by role, so a re-theme only edits the hex values in global.css. Each is a Tailwind color: bg-accent, text-muted, border-ink. Tints are decorative and carry no meaning.

canvas

Page background

surface

Raised surfaces, text on dark

ink

Text, borders, shadows

muted

Secondary text

rule

Hairlines and rulers, never text

accent

Primary action, highlights

danger

Destructive actions, warnings

info

Links, focus, notes

tint-1

Decorative tint

tint-2

Decorative tint

03

Typography

Atkinson Hyperlegible Next for display and prose. JetBrains Mono for labels, data, controls, and the hex mark. Use weights 400 and 700 only.

Display · Hyperlegible Next · text-7xl / bold / tight

Dead code.

H2 · text-4xl / bold

Section heading

H3 · text-xl / bold

Card heading

Body · text-base / text-muted for secondary

Body copy is set in the sans at a comfortable measure. Use .mark to highlight a phrase and .link for inline links.

Mono · JetBrains Mono · .eyebrow / labels / metadata

0xD34DC0D3 · v0.1.0 · // eyebrow label

.meta · build strings, counts, indexes · tabular figures

v0.1.0 · build 2026-01-01 · 03 registered · 0x0A

.cursor · animate-blink · one per view, static under reduced motion

Awaiting input

04

Borders & shadows

Borders use border-brut (border-brut-sm on small elements) in ink. Shadows are solid offsets toward bottom-right.

brut-sm · 2px

Fields, badges, small chips

brut · 4px

Default for cards and buttons

brut-lift · 6px

Hover state, applied by .brut-press

brut-lg · 8px

Hero objects, one per view

.brut-press

Hover to lift, click to press flat. Use on anything clickable.

.bg-grid

Dot texture for hero bands only.

05

Buttons

One primary per view. A bare .btn is the secondary style. Mono, uppercase, tracked.

html
<button class="btn btn-primary">Primary</button>
<a href="/x" class="btn btn-sm">Small link</a>

06

Badges

Status and metadata. Combine .badge with any background token.

DefaultNewLiveBetaSoonDeprecated

07

Forms

Fields use the small shadow at rest and the default shadow plus the focus ring on focus.

08

Cards

AppCard is the launchpad tile. Cards with an href get .brut-press and a launch arrow; the rest stay static.

Demo App

live

A launchable app card with a link.

Launch

Next App

soon

A placeholder card with no link yet.

src/data/apps.ts
{ name: "My App", tagline: "What it does.", href: "https://my-app.example", status: "live" }

09

Content

Code, callouts, and brand marks. HexMark is the hero-scale brand moment: 0xD34DC0D3 decoded byte by byte into deadcode. Use it once, inside an h1 with an sr-only name; it inherits font size from its parent.

shell
$ npm run dev
$ npm run build

Note

Callouts use a thick left border and a tint. Use danger for warnings.

Warning

Don't stack more than two colors besides ink in one component.

10

App shell

Every app on a subdomain wears the same chrome, so moving between apps feels like one system. The app owns its nav and content; the shell owns the way home.

  • Lockup: the 0x tile links to this site, then a muted mono /, then the app name linking to the app root. Never replace the tile with an app icon.
  • Header: lockup, app nav (mono, uppercase, accent on the current page), then account controls pushed right. Sticky, canvas background, brut bottom border.
  • Footer: ink bar. Left: deadcode · all apps linking to / and /#apps. Right: the accent hex, then the app name.
  • Config: read hosts from env, never hardcode them: <APP>_SITE_URL for this site, <APP>_AUTH_URL for voodoo.
  • Tokens: generate them from global.css, never hand-edit them. voodoo's scripts/sync-theme.sh is the reference.
html (structure)
<div class="brand">
  <a href="$SITE_URL/" aria-label="deadcode home">
    <span class="tile" aria-hidden="true">0x</span>
  </a>
  <span class="sep" aria-hidden="true">/</span>
  <a href="/">appname</a>
</div>

11

Usage

Rules of thumb for new pages and apps.

Do
  • Use the Base layout for every page.
  • Reach for .brut before writing custom borders.
  • Keep one accent CTA per view.
  • Use mono for anything a machine would print.
Don't
  • Blur shadows or add gradients.
  • Round corners past 2px.
  • Use hex values or arbitrary sizes inline; add a token instead.