Skip to content

UI Style Guide

Jump to bottom
rebaserHEAD edited this page Jul 26, 2026 · 1 revision

UI Style Guide

This page pins down the visual language GRIMP already ships with, so new surfaces (the start screen, settings, future dialogs) look like they belong. If you're building UI, start here.

The short version: dark navy theme with one blue accent, dense flat chrome with 1px separators, design tokens over hardcoded hexes, and small SS14 pixel-art touches for personality.

Theme tokens

All colors live in src/App.css as Tailwind v4 @theme tokens. Use the utility classes (bg-panel, text-muted, border-subtle) in components. Don't hardcode hexes; if a color you need isn't a token, that's a conversation about adding one, not a reason to inline it.

Token Hex Role
panel #0d1b2a Darkest surface: toolbars, side panels, inset wells
surface #16213e Mid surface: panel headers, status bar, landing card
elevated #1a1a3e Floating surfaces: dropdowns, menus; also the body background
subtle #2a2a4a Every 1px border and separator
active #0f3460 Selected/pressed fill, primary confirm buttons
hover #1a2a4e Hover fill on interactive rows and buttons
primary #e0e0e0 Main text
muted #888888 Secondary text, labels, shortcut hints
accent #4488ff The one accent: brand title, links, active tool, progress, primary buttons
danger #cc4444 Destructive actions and errors
success #88ff88 Positive status
warning #ff8800 Warnings and caution states

There is exactly one accent color. Resist adding a second; state is communicated with fills (hover, active) and the accent, not with new hues.

Type

  • Segoe UI stack app-wide, set once on <body> in index.html.
  • The scale is dense, editor-style:
    • text-xs (12px) for menus, panel content, and buttons
    • 10px for the status bar and toolbar labels
    • 9px uppercase with tracking-wider for section headers ("Tiles", "Entities")
    • 20px+ only for full-screen moments (the landing title, modal headings)
  • Monospace is reserved for perf/debug overlays.

Chrome patterns

The editor chrome follows the GIMP-style density direction (ui label on the issue tracker): flat, compact, information-first.

  • Panels are flat fills separated by 1px border-subtle lines. No shadows inside the chrome; shadows mark things that float (shadow-lg on dropdowns, shadow-2xl on full-screen cards).
  • Hover state is bg-hover. Selected state is bg-active plus text-accent.
  • Toolbars stack a Font Awesome free-solid icon over a tiny label over a muted shortcut hint.
  • Collapsible panels use a surface header row with a ▾/▸ glyph on the right.
  • Corner radius signals scale: rounded-sm on chrome elements, rounded-lg on large buttons and info boxes, rounded-xl on full-screen cards.

Buttons

  • Primary: bg-accent, white, font-semibold, hover:brightness-110, active:brightness-90.
  • Secondary: bg-elevated, border-subtle, text-primary, hover:bg-hover.
  • Danger confirm: dark red fill in the #6b2020 family with white text.
  • Focus is focus:ring-2 focus:ring-accent/50 on anything keyboard-reachable.

Modals

  • Full-screen rgba(0,0,0,0.7) overlay. Click-outside cancels; Escape cancels; Enter confirms.
  • A centered card with a subtle border, radius 8, generous padding, and centered text.
  • Confirm dialogs carry the chief engineer mascot at the top: 64px, image-rendering: pixelated.

Full-screen moments

The landing and loading screens set the template for anything that owns the whole window:

  • An animated space canvas (stars, parallax) behind the content.
  • A glass card in front: bg-surface/95 with backdrop-blur-sm, border-subtle, rounded-xl, shadow-2xl.
  • The GRIMP title in text-accent, subtitle and helper text in text-muted.

The start screen (issue #35) should extend this template rather than invent a new one.

Pixel art and personality

  • SS14 sprites and art always render with image-rendering: pixelated. Never let the browser smooth them.
  • The personality layer is deliberate but small: the chief engineer in confirm dialogs, the space clown easter egg (toolbar button, occasional drift-by on the landing screen).
  • Rule of thumb: the chrome stays utilitarian; the personality stays out of the working area and never costs a click.

Known drift

  • ConfirmModal.tsx is inline-styled with hardcoded hexes (#1a1a2e card, #e8a33d warning icon) that near-miss the tokens. Migrate it to token classes when it's next touched.

Clone this wiki locally