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.

#	Slide	File
1	One language, every channel	page-01.png
2	Meetup RSVPs	page-02.png
3	Morning brief	page-03.png
4	Plant watering	page-04.png
5	Weekly review	page-05.png
6	Same chart, two encodings	page-06.png
7	Design sprint	page-07.png
8	Client pipeline	page-08.png
9	Morning brief, on a phone	page-09.png
10	Site traffic, on a phone	page-10.png

Documentation

• Design system reference and live token explorer: npm run docs, or the published copy at thehoomanloop.com/konstrukt.
• Text layer reference: docs/text.html. Spec: docs/text.md. Review sheet: docs/text-review.html.
• The full contract — token model, build, gates, consumption, and adoption status — is in DESIGN.md.
• iOS integration: docs/ios.html.
• Deploying the docs: scripts/README-deploy.md.
• Agent entry points: llms.txt (curated index), llms-full.txt (generated full docs), AGENTS.md (working in this repo). The live public docs page is thehoomanloop.com/konstrukt.

Editing tokens

Author tokens in tokens/ as W3C DTCG JSON. A token's path becomes its CSS custom property (status.draft-bg → --status-draft-bg). Never edit anything in dist/ — it is generated. After editing, run npm run build && npm run check && npm run check:text. If the parity gate fails because you meant to change a value, run npm run snapshot and commit the snapshot diff alongside the token change.

Proposals

proposals/ holds work that is under review and promises nothing. It has no version, no gate, and no compatibility guarantee. When a proposal is stable it is promoted into tokens/ and src/ through the checklist in CONTRIBUTING.md, and only then does it ship.

Contributing

Read CONTRIBUTING.md first. The short version: a new output needs a gate, a new primitive needs a real consumer in the same pull request, and a vendored copy carries a version stamp.

License

MIT for the code and tokens. The Konstrukt name and marks are not covered by the license. See LICENSE.

---

Konstrukt is a project of The Hooman Loop.