← All entries

Waerrk · Brand & Design

Waerrk Brand v1.0 README

Slugbrand-v1-readme
TierTier 01
Statelive
Confidence100%
UpdatedApr 20, 2026

Waerrk Brand

Committed brand foundation for the Waerrk app. Tokens, typography, material, motion, icons, voice. Consumed by the Next.js frontend.

Source for this document: the design branch exploration, locked as v1.0 on 2026-04-19. Exploration history lives in docs/design-notes/vision-board.html and vision-board-discarded.html.

Quick start

  1. Copy or @import tokens.css into your root stylesheet (app/globals.css in Next.js).
  2. Import tokens.ts where typed constants are needed in JS.
  3. Read voice.md before writing any user-facing copy.
  4. Install fonts via next/font/google (recommended) or self-host.
  5. Install icons: npm install @phosphor-icons/react, use weight thin.

Table of contents

  1. Logo
  2. Typography
  3. Color
  4. Spacing and radius
  5. Material (edge, grain, gradient)
  6. Motion
  7. Focus states
  8. Icons
  9. Voice (see voice.md)
  10. File structure
  11. Future: DB-backed tokens

1. Logo

Status: Text-based placeholder. Final SVG arrives separately.

Working wordmark: Poster Geist 700 caps with Æ ligature. Renders as WÆRRK in Geist bold 700, tracking −0.03em, uppercase. Archival-massive, reads as stamped.

Placeholder SVG available at assets/logo/wordmark.svg. Use currentColor for fill so the mark inherits text color in both themes.

2. Typography

Font stack (committed):

SlotFontLicensePurpose
Body / UIGeist SansOFLAll reading flows, controls, forms
DisplayNewsreaderOFLHeadlines and section titles only
Meta / CodeGeist MonoOFLLabels, tags, code, CMDK

Newsreader: italic vs regular

  • Italic: single accent word in a headline, pull-quotes, magazine-style callouts between data rows. Maximum one italic block per headline.
  • Regular: headline base, section-title body, H3, tier names. Default for H1 through H3.

Never: run Newsreader through long body paragraphs. Body is Geist Sans.

3. Color

Principle: Monochrome. No accent color. Destructive is the only functional color exception.

Theme-aware via [data-theme="dark"] and [data-theme="light"].

Secondary palette · Muted Editorial (functional only, never brand-level): blue #4A7FBF, green #5FA37A, amber #BC924B, red #B85753, violet #8370B3, teal #4F9BA5, neutral #8A8A8A.

Always prefer semantic aliases in product UI: --status-success, --status-warning, --status-error, --status-info.

4. Spacing and radius

Radius scale (Soft Standard, quarter-circle corners): --radius-sm 6px, --radius-md 10px, --radius-lg 16px, --radius-xl 20px.

Scale pattern: Card 14 / Button 10 / Input 8 / Tag pill (999px).

Spacing scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128 px. Tokens --space-1 through --space-10.

5. Material

Three layers stack on cards and status surfaces:

  • Light-edge: 1px inset highlight top, shadow bottom.
  • Grain: fractal-noise SVG overlay, diagonal 158° fade (top-left light source).
  • Card gradient: subtle top-down brightness.

Status surface material uses 158° gradient, 6% top fading to 55%, 22%-alpha colored border, 14px radius.

6. Motion

Principle: Slow, weighted, credible. Endel-slow, never Notion-bouncy.

Duration tokens: --dur-fast 150ms, --dur-base 280ms, --dur-deliberate 400ms, --dur-slow 600ms.

Easing tokens: --ease-default, --ease-weighted, --ease-sharp.

Interactive-gate rule: hover animation + cursor: pointer fire only on genuinely interactive cards (<a>, <button>, or .is-interactive modifier). Decorative cards stay passive.

Forbidden: bounce/spring/elastic, scale beyond 0.98-1.02, rotate, glow-pulse, auto-animation without user input.

7. Focus states

Keyboard-only. :focus-visible with 2px outline on --text-0, 2px offset. WCAG 2.1 AA compliant.

8. Icons

Phosphor Icons, weight thin (1px stroke, round caps, 24px grid).

9. Voice

Separate document: voice.md. Summary:

  • Direct over buildup. Verb first.
  • Benefit first.
  • Concrete nouns.
  • Trust the reader.
  • No apology.
  • No filler.

English informal always. German informal du. No em-dashes. No AI filler.

11. Future: DB-backed tokens

Current pipeline is file-based. Migration plan when Waerrk Supabase DB is live:

  1. Create brand_tokens table (category, name, value, theme, description, section, updated_at).
  2. Parse tokens.css :root and [data-theme] blocks into rows.
  3. Build script regenerates tokens.css + tokens.ts from the table on change.
  4. Frontend continues to consume generated files. No runtime DB calls (zero latency, works offline).

File structure stays stable across this migration — frontend import path never changes.