Konstrukt
The Hooman Loop design system. JSON-first design tokens, generated into CSS,
Swift/SwiftUI, a JSON manifest, and a text/ASCII output layer, with a
self-contained documentation site.
Konstrukt is the single source of truth: edit tokens in tokens/, run the
build, and every surface — web apps, marketing sites, internal tools, native
iOS, and character-cell channels — follows.
One palette · light + dark · 43 color roles · 8 type roles · 4 output
targets · WCAG AA gated · 0px radius · 0 shadows. Bauhaus / Swiss
International: flat surfaces, square corners, authority through typography
rather than chrome.
One palette, two modes
Konstrukt ships a single palette, atelier: warm off-white, near-black ink,
one teal accent. data-mode="light" | "dark" on <html> switches between two
flat token sets resolved at build time. No runtime theme math in the browser.
Tokens are layered: raw color ramps in tokens/primitives.json are referenced
as {color.teal.700} and resolved at build time, never emitted. Semantic roles
(accent, danger, status-review, category-3) are what consumers use, and
dark mode overrides only the roles that differ.
Quick start
npm install
npm run build # tokens/ -> dist/ (CSS, Swift, tokens.json, text) + docs/assets
npm run check # parity vs the committed snapshot + WCAG AA contrast
npm run snapshot # accept an intended token change
npm run check:text # text-layer linter + golden board
npm run docs # serve the docs site on http://localhost:4340
What it produces
| Output | Path | For |
|---|
| Themed CSS | dist/css/konstrukt.css | all web surfaces (light + dark) |
| Components | dist/css/base.css | portable Konstrukt components |
| Theme runtime | dist/css/theme.js | HLTheme — sets the mode on <html> |
| Text embed | dist/css/text.css | pre.kt styling for character-cell blocks |
| Swift package | dist/swift/Konstrukt/ | iOS / SwiftUI |
| Manifest | dist/tokens.json | tooling, design apps, AI agents (includes text) |
| Text spec | dist/text.json | glyph ladders, column budgets, reserved marks |
| Text renderer | dist/text.py | vendored into cron collectors, briefings, CLI tools |
| Docs site | docs/ | reference + integration guides |
Tokens
Every token is authored once, in W3C DTCG JSON, and its path becomes its CSS
custom property: status.draft-bg → --status-draft-bg. The reference page
reads the generated manifest, so what you see is what ships.
Typography is tokenized too. Each role (display, heading, subheading,
label, badge, body, meta, mono) is emitted as a font shorthand
plus tracking and case, and the Swift package gets the same roles as
KonstruktTextStyle:
h1 {
font: var(--type-display);
letter-spacing: var(--type-display-tracking);
}
Border widths are tokens as well: --stroke-hairline (1px), --stroke-rule
(the 2px ink rule) and --stroke-rail (the 4px accent rail).
Contrast
Every foreground/background pair the components render is checked against
WCAG 2.2 AA in both modes: 4.5:1 for text, 3:1 for control outlines, focus
rings and structural rules. npm run check fails the build when a pair drops
below. 80 pairs pass today.
Components
The portable component vocabulary: modules with 2px ink borders, status pills,
category tags, primary and quiet buttons, form fields, alerts, data tables,
question lists. Square by default, no shadows, teal reserved for the one
primary action on a surface.
Text layer
Charts, annotations and CLI motion for channels that render characters instead
of pixels. Nine primitives, two encodings, and a linter that fails a build when
a chart lies about a number.
The text layer is part of the versioned contract. Glyph ladders, column budgets
and reserved marks live in tokens/text.json. npm run build
emits dist/text.json and a self-contained dist/text.py for vendoring. Read
the spec: docs/text.md. Run the renderer:
python3 dist/text.py.
Chart designs
Twelve compositions that use the shipped primitives. Numbers on the slides are
example data; the phones are mockups, not device captures.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
