Zhex design system · Version 1

Small words.
Big ideas.

This system gives Zhex one visual and verbal language across the brand, website, documentation, and code examples. It is designed for contributors who need to explain the language clearly without making compactness feel cryptic.

01 · Foundation

Clarity through composition.

Modular

Pages, components, and messages are built from small reusable parts—just like Zhex programs.

Explicit

Hierarchy, state, links, and data flow remain visible. Decoration never hides structure.

Direct

Copy is concise, typography is confident, and orange marks the next useful action.

DirectionFunctional editorial: warm neutral ground, black structural typography, and signal orange used with restraint.
PromiseCompact ideas remain understandable as they compose into larger programs.
MottoSmall words. Big ideas.

03 · Color

Orange signals meaning.

Paper#F6F3EC · page ground
Ink#1D1B19 · text and code
Signal orange#FF5A2A · actions and emphasis
Surface#EBE6DC · secondary fields
Orange soft#FFD8CC · state halos
Focus blue#1541C6 · keyboard focus

Use orange for selected phrases, action states, progress, and syntax—not as the default page background. A surface should usually contain one dominant orange signal.

04 · Typography

Large ideas, readable details.

Display

Small words.

Body

Zhex keeps compact code understandable through visible flow, meaningful names, and checked types.

Monospace

flow name → greet → print

Use display type for one main idea at a time. Body copy stays between 65 and 76 characters per line. Monospace is reserved for code, labels, status, and technical metadata.

05 · Spacing and layout

A visible rhythm.

1 · 4px
2 · 8px
4 · 16px
5 · 24px
6 · 32px
8 · 64px
9 · 96px
CanvasMaximum content width: 1240px, with responsive edge padding.
ReadingLong-form content: 65–76 characters per line.
StructurePrimary regions use normal grid or flex flow. Orange rules mark transitions without becoming decoration.

06 · Components

Few components, clear jobs.

Primary action

Read examples →

One solid action per viewport whenever possible.

Text action

Review the roadmap →

Use for secondary navigation and lower commitment.

Status

Working Go interpreter

Pair color with explicit text; never use the dot alone.

Run input

Labeled, prefilled with the example's real input, and styled like the output pane.

Input hint

Two numbers, one per line

Says what the box expects, straight from the example's data; a card that reads nothing says so and offers no box.

Inline validation

Expected one number — "abc" is not an integer.

Checks the run input against its declared kind before the program runs; the message names what was expected.

Run action

The primary action for runnable examples; dimmed while the artifact loads.

Run message

runtime error: "abc" is not a signed 64-bit decimal integer

Runtime and load failures wrap inside the output pane instead of clipping.

Interactive input

The program reads each line as you send it; End input reports end-of-file.

Opens under the output when a run reads past its input box — Send passes one typed line to the program, End input ends its input like an empty terminal.

Demo grid

Draws a captured run's frames cell by cell on paper, with a line grid and ink cells — tokens only.

Playback controls

Play, pause, and single-step a captured run at a fixed pace; the label carries the state, and playback loops from the first frame.

Year tabs

Switch between the archive years and the upcoming one; the selected tab fills ink, and arrow keys move between tabs.

Calendar doors

One door per event day, counted from the day data; a door shows the day number, its title, and one honest status badge, and opens that day's view.

Door status

Not solved yetWorking on this problemPart 1 solved, part 2 in progressSolved

Four honest states, nothing between them; the label carries the meaning and color only supports it.

Group chip

One rounded pill per group in a counted inventory, linking to the group's detail; the name carries the meaning, the mono orange count sizes it, and the whole pill is the target.

Code editor

Plain editable text in the mono face, labeled in text; the source stays the visitor's to change, never a picture of code.

Mode switch

Two modes over one engine — run a whole program or type entries one at a time; the selected mode fills ink and arrow keys move between modes.

Playground link

Sits beside the download action on every example card and opens that card's complete, editable source; the compiled run stays on the card.

Tour empty state

  1. print "Hello, Zhex!"
  2. word greet(name: String) -> String …
  3. greet(42) — a failure with its caret

One shipped script a visitor can run as-is: an entry, a word definition, and a deliberate failure showing its caret diagnostic.

Docs search

Lives at the top of the documentation sidebar; labeled in text, never placeholder-only.

Search results

  1. Words and flowsLanguage · Words and flows
  2. Handle a failureLanguage · Results

A handful of ranked page and heading links; the count is announced and arrows plus Enter open a match.

ComponentUseAvoid
HeroOne promise, one supporting sentence, one primary actionRepeating the same value proposition in a side panel
Section headingPair a clear claim with concise contextDecorative headings without informational value
Code windowReal syntax, filename, and visible resultFake terminal noise or code used only as texture
Feature rowLink a concept directly to a working exampleRows that look interactive but do nothing
Run inputCollect program stdin beside a runnable example, byte-honestUnlabeled fields or inputs that quietly rewrite the sample
Input hintState the entry a run input expects, straight from the example's data; no-input cards say so instead of offering a boxPlaceholder text that vanishes while typing, or a guessed format
Inline validationCheck the box against its declared kind before running, naming what was expectedProgram trap lines as the entry's only guidance
Run actionRun the compiled example; dim while disabledA busy state that hides the disabled affordance
Run messageExplain runtime and load failures inside the output paneLong lines clipped behind horizontal scroll
Interactive inputTake a program's further reads live — one Send per typed line, End input acting like an empty terminalA prompt with no place to type, or an output pane that pretends the run already ended
Demo gridDraw a captured run's output cell by cell, tokens only, honest to the artifact's framesInvented colors or cell sizes outside the tokens
Playback controlsPlay, pause, or single-step a captured run; the label carries the state, and the run loops from the topControls that look active but do nothing
Year tabsSwitch between the archive years and the upcoming one; the selected tab fills ink, arrow keys move between tabsA second page for what one panel switch shows
Calendar doorsOne door per event day, counted from the day data, each opening that day's viewA hardcoded door count, or a door that promises a solution it cannot show
Door statusOne of four honest labels per day, with color only supporting the textA status that hints at answers before they exist
Group chipSummarize a counted group inventory as rounded pills linking to each group's detailA count the group cannot back up, or pills repeating what a heading already says
Code editorEdit the program as plain labeled text in the mono faceA read-only block posing as an editor, or an unlabeled box
Mode switchSwitch one engine between whole-program runs and typed entries; the selected mode fills inkTwo separate pages for what one switch shows
Playground linkOpen the card's complete editable source in the playground, beside the download actionA link that drops the source, its input, or its module siblings on the way over
Tour empty stateA shipped script that runs an entry, a word definition, and a failure with its caretAn empty pane with no way forward
Docs searchFind documentation pages and headings from the sidebar, against the build's generated indexA hand-maintained word list, or a field named only by its placeholder
Search resultsA handful of ranked page and heading links, opened by keyboard or clickA wall of matches, or results that look clickable but do nothing

07 · Code presentation

Syntax should reveal the flow.

word greet(name: String) -> String
    "Hello, " + name + "!"

let name = read-line("Your name: ") try

flow name
    greet
    print
TokenRoleColor
KeywordDeclarations, branching, loops, and error propagationSignal coral
FlowComposition and data movementLight coral
TypeSignatures and contractsWarm yellow
StringLiteral textSoft green
NumberNumeric literals and boundariesCool cyan
FunctionWords and callable operationsPaper white

08 · Content voice

Explain first. Impress second.

Concrete

Say what the language does: “flow passes each result forward.” Avoid abstract claims without examples.

Compact

Prefer short sentences and visible structure. Remove repeated value propositions.

Honest

Call the interpreter experimental, label private access, and separate current behavior from future plans.

HeadlineOne memorable idea: “Small words. Big ideas.”
SupportExplain the practical value in one sentence.
EvidenceShow real code, output, examples, or roadmap status.

09 · Accessibility

Clarity must work for everyone.

  • Body text remains at least 16px with a 1.5–1.75 line height.
  • Orange is paired with text, shape, or position; it never carries meaning alone.
  • Every interactive element has a visible keyboard focus state and a descriptive label.
  • Large headlines wrap at words, not arbitrary characters.
  • Code and tables scroll horizontally instead of clipping on narrow screens.
  • Reduced-motion preferences remove nonessential transitions.

10 · Release checklist

Before a Zhex page ships.

  1. Lead with one clear message and remove repeated explanations.
  2. Use tokens rather than introducing one-off colors or spacing values.
  3. Link every element that visually promises interaction.
  4. Show real Zhex syntax and preserve source fidelity.
  5. Label experimental, planned, private, or unavailable behavior honestly.
  6. Check keyboard navigation, mobile reading, code overflow, and reduced motion.