DESIGN.md

version	alpha
name	Hal
description	Autonomous precision for the coding loop. Dark void aesthetic with a single warm accent, engineered for developers who trust machines to ship.
colors	primary on-primary accent secondary surface surface-elevated success warning #0a0a0c #f0f0f0 #dc2626 #8a8f98 #111114 #1a1a1e #27a644 #f59e0b
typography	display-hero display-section heading-feature body-large body body-medium caption label mono-body fontFamily fontSize fontWeight lineHeight letterSpacing fontFeature Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 72px 600 1.0 -2.4px 'liga' 1 fontFamily fontSize fontWeight lineHeight letterSpacing fontFeature Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 48px 600 1.05 -1.6px 'liga' 1 fontFamily fontSize fontWeight lineHeight letterSpacing fontFeature Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 32px 600 1.15 -0.8px 'liga' 1 fontFamily fontSize fontWeight lineHeight letterSpacing Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 18px 400 1.6 -0.02em fontFamily fontSize fontWeight lineHeight letterSpacing Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 16px 400 1.55 0px fontFamily fontSize fontWeight lineHeight letterSpacing Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 16px 500 1.5 0px fontFamily fontSize fontWeight lineHeight letterSpacing Geist, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif 14px 400 1.4 0px fontFamily fontSize fontWeight lineHeight letterSpacing fontFeature Geist Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace 12px 500 1.2 0.04em 'liga' 1 fontFamily fontSize fontWeight lineHeight letterSpacing fontFeature Geist Mono, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace 14px 400 1.5 0px 'liga' 1
rounded	sm md lg xl full 4px 8px 12px 16px 9999px
spacing	xs sm md lg xl 2xl 3xl 4xl 4px 8px 16px 24px 32px 48px 64px 96px
components	button-primary button-primary-hover button-ghost button-ghost-hover card card-elevated badge input backgroundColor textColor rounded padding typography {colors.accent} #ffffff {rounded.md} 12px 24px {typography.body-medium} backgroundColor #ef4444 backgroundColor textColor rounded padding typography rgba(255,255,255,0.03) {colors.on-primary} {rounded.md} 12px 24px {typography.body-medium} backgroundColor rgba(255,255,255,0.06) backgroundColor textColor rounded padding {colors.surface} {colors.on-primary} {rounded.lg} 24px backgroundColor textColor rounded padding {colors.surface-elevated} {colors.on-primary} {rounded.lg} 24px backgroundColor textColor rounded padding typography rgba(255,255,255,0.05) {colors.secondary} {rounded.full} 4px 12px {typography.label} backgroundColor textColor rounded padding typography {colors.surface} {colors.on-primary} {rounded.md} 12px 16px {typography.body}

Overview

Hal is an autonomous AI coding loop CLI. The visual identity reflects that: a dark void where a single warm accent — the HAL eye — marks the moment the machine takes the wheel. The design is terminal-native but refined, treating the interface like a precision instrument rather than a dashboard.

The system is built on a near-black canvas with subtle surface elevation, creating depth without visual noise. Typography uses Geist Sans for UI and Geist Mono for anything that looks like code, commands, or technical labels. OpenType ligatures are enabled globally as a structural detail, not decoration.

Colors

• Primary (#0a0a0c): The void. Deep ink with a barely perceptible warm undertone. Used for the deepest backgrounds.
• Surface (#111114): One step up from the void. Cards, panels, and contained surfaces.
• Surface Elevated (#1a1a1e): Slightly lighter for hover states, dropdowns, and elevated components.
• On Primary (#f0f0f0): Near-white text. Slightly softened from pure white to reduce eye strain on dark backgrounds.
• Secondary (#8a8f98): Cool silver-gray for body text, descriptions, and secondary content.
• Accent (#dc2626): The HAL eye. Warm red used sparingly for primary CTAs, active states, and brand marks. It is the only chromatic color in the system.
• Border (rgba(255,255,255,0.06)): Ultra-subtle semi-transparent white. The default border treatment.
• Border Strong (rgba(255,255,255,0.10)): Slightly more visible for prominent separations.

Typography

Geist Sans drives all marketing and UI text. Geist Mono handles code, commands, labels, and anything that needs to feel like terminal output. Both fonts enable OpenType ligatures globally.

Display sizes use aggressive negative letter-spacing — -2.4px at 72px, -1.6px at 48px — creating compressed, authoritative headlines. Below 32px, tracking relaxes toward normal. The weight system is narrow: 400 for reading, 500 for UI emphasis, 600 for headings. No bold above 600.

Layout

The spacing system is built on an 8px base unit: 4px, 8px, 16px, 24px, 32px, 48px, 64px, 96px. Sections are separated by generous vertical padding (64px–96px) with no visible dividers — the dark background provides natural isolation.

Max content width is approximately 1200px. The hero is a centered single-column with vast vertical padding. Feature sections use 2–3 column grids for cards. Code and terminal previews are full-width or contained with subtle borders.

Elevation & Depth

On dark surfaces, elevation is communicated through background luminance rather than shadow darkness:

• Flat (Level 0): #0a0a0c — page background, no shadow.
• Surface (Level 1): #111114 + 1px solid rgba(255,255,255,0.06) — cards, panels.
• Elevated (Level 2): #1a1a1e + 1px solid rgba(255,255,255,0.10) — hover states, dropdowns.
• Focus: 2px solid rgba(220,38,38,0.5) — accent-colored focus ring on interactive elements.

Shapes

• 4px: Small badges, inline code, toolbar buttons.
• 8px: Buttons, inputs, functional elements.
• 12px: Cards, panels, feature containers.
• 16px: Large panels, hero sections.
• 9999px: Pills, badges, status tags.

Components

button-primary is the high-emphasis action. Warm red background, white text, 8px radius, 12px 24px padding. Hover lightens to #ff4d5a. Used for the main CTA only.

button-ghost is the default action. Near-transparent white background (rgba(255,255,255,0.03)), near-white text, 8px radius. Hover increases background opacity to 0.06. Used for secondary actions and navigation.

card is the standard container. #111114 background, 1px solid rgba(255,255,255,0.06) border, 12px radius, 24px padding. No drop shadow — depth comes from the surface color step.

card-elevated is the hover/selected variant. #1a1a1e background with the stronger border.

badge is a neutral pill. rgba(255,255,255,0.05) background, secondary gray text, 9999px radius, 4px 12px padding. Used for tags, version labels, and status.

input follows the card pattern. #111114 background, 8px radius, 12px 16px padding. Focus state adds the accent-colored ring.

Do's and Don'ts

• Do use #0a0a0c as the deepest background and #111114 for surfaces.
• Do enable "liga" on all Geist text.
• Do use weight 600 for headings, 500 for UI emphasis, 400 for body.
• Do apply negative letter-spacing at display sizes: -2.4px at 72px, -1.6px at 48px.
• Do reserve the accent red (#dc2626) for primary CTAs and active states only.
• Do use semi-transparent white borders instead of solid dark borders on dark backgrounds.
• Do use Geist Mono for code, commands, and technical labels.
• Don't use pure white (#ffffff) as primary text — #f0f0f0 is softer on the eyes.
• Don't apply the accent red decoratively. It is a signal, not a theme.
• Don't use traditional CSS drop shadows for elevation on dark surfaces.
• Don't use positive letter-spacing on display text.
• Don't introduce additional chromatic colors into the UI chrome.