One system. Every surface.

How to use this system

This page is the normative reference for every GreenHat surface — the product tools, greenhatsec.com, and all content. Build to it, not from screenshots of existing pages: where a shipped page and this document disagree, this document wins.

Delegating brand work — to a person or an agent? Hand over this file and require three things: tokens only, library first, and the definition of done in Governance. Reject any change that introduces raw hex, a non-8px button, or a font that isn't actually loaded.

Design principles

Atomic Design, token-driven

Adopted from the Actionboard case study: components are the key building blocks, and their systematic reuse creates visual and functional consistency across products. Five layers compose bottom-up — and every layer resolves the same tokens.

Atomic layers map onto the token tiers: atoms consume component tokens (--gh-comp-*), component tokens point at semantic tokens (--gh-sys-*), semantics point at primitives (--gh-ref-*). A marketing hero and an exponential task card both resolve --gh-sys-primary; only the surface layer decides hero rhythm and the green-700 CTA override.

Color

One brand green — the forest family. Green-700 #0F7A35 is the text green and filled CTA (5.45:1 with white text). Green-600 #0F8A3D remains the brand/success fill when no normal-size white label sits on top. Click any swatch to copy.

Brand green ramp — --gh-ref-green-*

★ 600 = brand/success fill when no text sits on it · ★ 700 = primary text and filled CTA · 400 is the retired product green #62AC4A, demoted to decorative fill (status dots, chart series) — never text · 900 #0B3B2C is the logo deep green.

Neutral ramp (green-tinted) — --gh-ref-neutral-*

950 #0F1A12 is the brand's green-tinted near-black (body text on light). 100 is the surface tint; 300 the default border; 900 the dark-mode canvas.

Semantic roles — --gh-sys-* (what themes remap — these chips re-resolve live when you switch theme)

Data-viz categorical palette (fills only — legend text is always a neutral token)

Typography

One role-based scale. Body = Lexend, display = Lexend Deca 700 (marketing headlines), code = Geist Mono. The legacy dual scales collapse into this one scale — the old 14px-base system is now the compact density. Flip the density toggle in the top bar and watch every sample below re-resolve.

Density remaps sizes only — never roles. A body is always a body; data-density=compact just resolves it at 14px. The legacy scales map cleanly: old "sm" scale = comfortable, old "lg" h1 = compact display. Geist Sans is retired from the core brand — the brand typeface is Lexend; Geist survives as Geist Mono for code, and as the assurance surface face via the documented theme font exception.

Spacing, Sizing & Grid

A 4px base grid expressed in Actionboard's 16×N model. Chrome is fixed-width; content is grid-bound on a 12-column, 1440px-max grid (16px gutter · 56px margin).

Spacing scale — --gh-ref-space-*

The 12-column content grid

Radius & Elevation

Two-tier shape system — 4px controls, 8px containers — and five elevation levels with light and dark primitive sets.

Elevation — 5 levels, semantic pointers over two primitive sets

Elevation lives at the semantic tier: --gh-sys-shadow-1..5 point at --gh-ref-shadow-light-* or --gh-ref-shadow-dark-*. Themes flip the pointer, never the primitive — switch to Dark above and these five cards deepen live.

Motion & Iconography

One curve family, four durations. 150ms cubic-bezier(0.4, 0, 0.2, 1) is the default transition on color, background, border, shadow, opacity and transform. prefers-reduced-motion collapses all durations to 0.01ms.

Iconography — lucide, line-first

Focus & Accessibility

WCAG AA is the floor: normal text ≥ 4.5:1, large text and UI objects ≥ 3:1. Every default token pairing is measured — this table is normative, and it's why the old greens couldn't survive as text.

Token Architecture & Theming

Three tiers, one namespace: --gh-*. The Material-prefixed system, --daisy-* and --gs-* are all retired — same three-tier shape, one honest prefix. This very page is built on these tokens: the theme switcher above redeclares Tier 2 (plus, for the two surface-faithful themes, the documented font-primitive exception below).

/* app root contract */
<html data-theme="light|dark|exponential|assurance"
      data-density="comfortable|compact"
      data-contrast="normal|more">

/* Tailwind v4 bridge */
@theme inline {
  --color-primary: var(--gh-sys-primary);
  --color-surface: var(--gh-sys-bg-surface);
  --radius-button: var(--gh-comp-button-radius);
}

/* Tier 2 — what a theme remaps (excerpt of this page's own CSS) */
--gh-sys-primary: var(--gh-ref-green-700);        /* CTA fill  #0F7A35 */
--gh-sys-primary-text: var(--gh-ref-green-700);   /* text  #0F7A35 — AA on white */
--gh-sys-shadow-1: var(--gh-ref-shadow-light-1);  /* dark theme → shadow-dark-1 */

/* Tier 3 — components consume semantics */
--gh-comp-button-radius: var(--gh-ref-radius-md); /* 8px — the single button rule */
--gh-comp-table-row-hover: var(--gh-sys-primary-subtle);

/* Tailwind v4 bridge — @theme inline keeps existing utilities compiling */
@theme inline {
  --color-primary: var(--gh-sys-primary);
  --color-brand-primary: var(--gh-sys-primary);  /* legacy alias */
  --spacing-sidebar: var(--gh-comp-sidebar-w);
}

Stacked attributes on <html>: data-theme × data-contrast × data-density. daisy-notes' selectable "theme modes" become [data-theme] values — no parallel token file survives.

The font-primitive exception, enumerated. exponential remaps the font primitives to the system-ui stack — the tool ships no webfont, so this theme reflects what actually renders; if the tool adopts loaded fonts, re-point the theme here in the same change. assurance remaps them to Geist — load Geist via next/font on that surface and never rely on a base-rule fallback. Type sizes remain density-owned: a theme never remaps --gh-type-* (the later [data-density] block would clobber it anyway) — pair exponential with data-density="compact". Assurance CTAs render on the 8px button rule under GHDS; pills there are a documented surface divergence, not a license.

Atoms

Every load-bearing atom ships as a full Variants × Sizes × States matrix. The four core atoms are cell-normative below — every cell rendered live from tokens. Interactive cells respond to your cursor; forced-state cells show hover/pressed/focus frozen.

Button — the exemplar matrix · 5 variants × 3 sizes × 6 states · all 8px

Input — the form matrix · {No-Hint | Hint} × {Unfilled, Filled, Error, Disabled} × {Default, Hover, Active} · radius 4px

All 30 cells = {5 row-states} × {No-Hint/Hint} × {Default/Hover/Active where applicable}. The ×{Default/Hover/Active} axis modifies border/ring only; the error dot and lock glyph are fixed per row-state. Errors never rely on color alone.

Selection controls & small atoms

Molecules

Atoms bonded into the smallest functional compounds. Everything below is live and consumes only --gh-sys-* / --gh-comp-*.

Alert banners — info / success / warning / error

Cards — task · marketing feature

Disclosure & wayfinding · use on both surfaces; names follow the Component Gallery taxonomy

Menus, pickers & files · overlay panels shown frozen-open, like the forced-state button cells

Adopter molecules — audit-ledger & ARGUS

Use these before inventing local variants in audit-ledger, ARGUS, or dashboard work. They are small enough to stay molecules, but specific enough that teams otherwise drift.

- GET /api/users/42 as jim -> 200
+ GET /api/users/42 as jim -> 403
  evidence_source: authorization_matrix
  replay: reports/juice/access-map.txt

Deliberately not adopted from the Component Gallery taxonomy — check the alternative before building one: Carousel (use static grids; motion carries no evidence) · Rating (severity is badges + priority dots, never stars) · Color picker (color is token-governed, not user-picked) · Video (no embedded media on the brand surface today; wrap in the Figure shell if that changes) · Stack (a gap-spaced flex column on the 4px scale is the idiom — no dedicated component).

Organisms

Distinct interface sections. Two are already running on this page — the fixed Left Sidebar Nav with its green active state, and the sticky Top Bar. Below: Data Table, Modal, Command Palette, Empty State.

Data Table — zebra · hover · selected · sticky header

Header band = --gh-comp-table-header-bg: green-900 with white 11px caps in the default theme, light #FAFBFC with muted caps in Exponential, and forest with white caps in Assurance. Row hover = --gh-comp-table-row-hover. Selected = primary-subtle + inset 2px accent. Virtualized via react-virtual; reflows to cards under md.

ARGUS access-map matrix — endpoint × principal coverage

Dashboard rule: the coverage matrix consumes the full report.access_map object. Deduped unique findings can decorate cells and open proof drawers, but they must not be the only source for the endpoint × principal grid because empty, denied, mixed and untested cells are part of the evidence story.

ARGUS dashboard access-map flow — roles to endpoints

Use this view when ARGUS needs a dashboard-native scan map rather than a dense audit table. It is still fed by report.access_map: role nodes come from known_roles, endpoint nodes from endpoints[], and highlighted paths from finding overlays or unexpected role_outcomes. Motion mirrors the dashboard replay language: paths draw in, violation points pulse, and the scan sweep freezes under prefers-reduced-motion.

ARGUS dashboard endpoint-role matrix — finding overlay

Dashboard parity rule: this is the current argus-dashboard/components/EndpointMatrix.tsx visual model, retokenized for GHDS. Keep the check-only expected cells and warning-pill finding cells, but source rows from full report.access_map when available; selectUniques() decorates cells and drives the proof drawer.

Tree view · Rich text editor · Drawer

Marketing & Content

The brand-surface library: use these components on greenhatsec.com and every marketing or content page. Product chrome lives in Organisms — both surfaces share the same tokens. Names follow the Component Gallery taxonomy. Surface rules: tints come from primary-subtle — never raw rgba() greens; radii come from tokens; buttons follow the 8px rule; and every pattern is built once as a shared component, then imported. The hero organism is demonstrated in Overview.

Header / NavBar · Footer

Logo strip · Stat band

Process steps · CTA banner · Inline CTA panel

Animated checklist — the readiness visual

Article patterns — header · summary · takeaways · citation

Content cards — article · related links · download

Comparison panel · Contact form states

Risk matrix heat grid · the one tool organism with its own anatomy

Compose interactive tools — calculators, questionnaires, wizards, risk builders, readiness meters — from these parts: Stepper + Progress + Option cards + Spec list + Stat tiles + result Callouts, plus the heat grid above. Reuse the .seg segmented control for locale and mode switches. And build each primitive once as a shared component, then import it everywhere — never re-declare a pattern inside a page file (adoption plan in Governance).

Data Visualization

Charts are first-class. Every chart lives in a bordered 8px Chart Card with title, legend and range control. SVG-rendered so they theme via CSS variables — watch them re-color when you switch theme. Legend text is always a neutral token; series hues are fills only.

Content & Voice

"Security operators. Product builders. Independent auditors." — one company, three pillars, and the voice follows: operator-led, concise, confident, founder-friendly. Calm authority — never hype, never fear-selling. Overstatement erodes trust in a security and audit brand.

Idioms: eyebrow pills label sections · feature cards lead with a green line-icon · stats and the single accent word in a headline carry green-700 as text · partner logos grayscale.

Governance & Adoption

SemVer, additive-first — tokens and component APIs are contracts. The rebuilt Brand Hub becomes the living reference: it consumes the same --gh-* tokens it documents and renders every matrix cell. If docs and code disagree, the docs rendered from tokens win — the code is the bug.

Contribution rules

Phased migration

Definition of done — bringing any surface onto GHDS: fonts actually load (verify the rendered family in devtools, not the class name) · zero raw hex — the lint passes · every button 8px · every text pairing passes the Accessibility table · new components land in this document with their full matrices, in the same change. Every color pairing in this document has a measured contrast pass; every core-atom cell is enumerated and rendered live above.

GHDS v1.1.1 · synthesized from greenhatsec.com + the greenhat_tools monorepo + the Actionboard Design System methodology (Behance, kishore R) · this page is itself built on the tokens it documents.