Design System

The visual language of h-uman. Every color, every motion, every surface — designed to be not quite human.

Principles

Honest by Design

We don't pretend. UI states are clear, not clever. Errors look like errors.

Performance is Aesthetic

If it's slow, it's ugly. Every animation runs on the compositor. Every transition respects prefers-reduced-motion.

Token-Driven

No magic numbers. Every value comes from a token. Change once, update everywhere.

Color System

--hu-accent (Human green)

var(--hu-accent)

M3 Tonal surfaces

--hu-surface-dim
--hu-surface-container
--hu-surface-container-high
--hu-surface-container-highest
--hu-surface-bright

Dynamic primary ramp (50–950)

Typography

Avenir (Black)

Avenir

Type scale

--hu-text-2xs The quick brown fox
--hu-text-xs The quick brown fox
--hu-text-sm The quick brown fox
--hu-text-base The quick brown fox
--hu-text-lg The quick brown fox
--hu-text-xl The quick brown fox
--hu-text-2xl The quick brown fox

Geist Mono (code) 

              $ cmake --preset dev
$ cmake --build --preset dev
[100%] Built target human

Three-size maximum rule

Section heading (2xl)

Body text at base size. Only three type sizes visible in any single view section.

Caption (sm)

Glass & Surfaces

.hu-glass-subtle

Navigation, headers, subtle overlays

.hu-glass-standard

Panels, cards, elevated content

.hu-glass-prominent

Modals, dialogs, focus surfaces

Motion

Micro
Standard
Expressive
Dramatic

Duration scale (hover to animate)

--hu-duration-fast
--hu-duration-normal
--hu-duration-slow

prefers-reduced-motion — All animations respect the user's motion preference. When prefers-reduced-motion: reduce is set, durations collapse to near-instant and spring effects are disabled.

Spacing

An 8pt-based rhythm scale from --hu-space-2xs (2px) to --hu-space-6xl (128px).

--hu-space-2xs
2px
--hu-space-xs
4px
--hu-space-sm
8px
--hu-space-md
16px
--hu-space-lg
24px
--hu-space-xl
32px
--hu-space-2xl
48px
--hu-space-3xl
64px
--hu-space-4xl
80px
--hu-space-5xl
96px
--hu-space-6xl
128px

Elevation & Shadow

M3-inspired elevation ladder from level 0 (flat) to level 5 (tooltip). Semantic shadows adapt to light/dark theme.

0 Level 0
1 Level 1
2 Level 2
3 Level 3
4 Level 4
5 Level 5

Semantic Roles

Surface → Level 0
Card → Level 1
Dropdown → Level 2
Modal → Level 3
Toast → Level 4
Tooltip → Level 5

Shape & Radius

none 0
sm 4px
md 8px
lg 12px
xl 16px
2xl 24px
full 9999px

Iconography

Phosphor Regular — consistent stroke width, optical alignment, currentColor inheritance.

Full library: phosphoricons.com

Tonal Surfaces

M3-inspired surface hierarchy tinted with primary accent for branded depth. Use tonal surfaces for brand identity; neutral surfaces for content-first areas.

Page background
Neutral card/panel
Default tonal (4% tint)
Elevated interactive (6% tint)
Highest emphasis (8% tint)

Layout Archetypes

Every view in the design system conforms to one of six canonical archetypes.

Dashboard

Hero → scrollable card grid

List-Detail

Dual-pane on expanded

Conversational

Content first, controls bottom

Settings

Single column, max 640px

Marketplace

Sticky search → card grid

Log/Terminal

Controls top → mono output

Data Visualization

Chart tokens for categorical, sequential, diverging, and status palettes. Maximize data-ink ratio; prefer direct labels over legends.

Categorical (16 colors)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Sequential (Human Green)

100
200
300
400
500
600
700
800

Diverging

positive
neutral
negative

Status

success
warning
error
info
muted

State & Interaction

Neutral overlays for interactive states (M3). White veil on dark theme, black veil on light. Brand color appears in focus rings and primary accents, not hover washes.

Hover
--hu-hover-overlay
Pressed
--hu-pressed-overlay
Focus
--hu-focus-overlay
Disabled
--hu-disabled-overlay

Focus Ring

Focus rings: 2px solid accent with 2px offset. Visible on keyboard navigation, hidden on mouse click.

Accessibility

WCAG 2.2 AA minimum. Every component, every surface, every interaction.

Contrast

  • Text on background: 4.5:1 minimum (AA)
  • UI components: 3:1 minimum
  • Large text (≥24px / 18.66px bold): 3:1
  • Focus indicators: 3:1 against adjacent colors

Focus & Keyboard

  • All interactive elements focusable via Tab
  • Visible focus ring: 2px solid, 2px offset (WCAG 2.4.11)
  • Focus not obscured by sticky headers (WCAG 2.4.12)
  • Skip links for content, modals trap focus

Touch Targets

  • Minimum target: 44 × 44px (WCAG 2.5.8)
  • Spacing between targets: ≥8px
  • Enhanced on pointer: coarse devices

Motion Sensitivity

  • prefers-reduced-motion: reduce disables all animation
  • No auto-playing video or parallax without opt-in
  • WebGL disabled when reduced motion preferred
  • All transitions: opacity crossfade fallback

Components

LitElement web components from the ui/ workspace. All use --hu-* tokens exclusively.

<hu-card>

Glass, solid, hoverable, tilt. Surfaces: default, high, highest.

<hu-input>

Tonal variant for branded surface. Validation states built-in.

<hu-badge>

Status indicators. Info variant uses accent-tertiary.

<hu-code-block>

Syntax highlighting with copy button. Respects theme.

<hu-approval-gate>

Permission approval UI for agent actions.

<hu-workflow-timeline>

Vertical timeline for agent workflow steps.

Full component docs: Starlight documentation

Explore Further

Dive deeper into the design system documentation and brand guidelines.

Design Tokens Brand GitHub