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.
02 · Logo
The symbol explains the language.
Maintain clear space equal to the chevron tile on every side. Do not rotate, stretch, recolor individual strokes, or place the light logo on a low-contrast background.
03 · Color
Orange signals meaning.
#F6F3EC · page ground#1D1B19 · text and code#FF5A2A · actions and emphasis#EBE6DC · secondary fields#FFD8CC · state halos#1541C6 · keyboard focusUse 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.
Small words.
Zhex keeps compact code understandable through visible flow, meaningful names, and checked types.
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 · 4px2 · 8px4 · 16px5 · 24px6 · 32px8 · 64px9 · 96px06 · Components
Few components, clear jobs.
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 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
- print "Hello, Zhex!"
- word greet(name: String) -> String …
- 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
A handful of ranked page and heading links; the count is announced and arrows plus Enter open a match.
| Component | Use | Avoid |
|---|---|---|
| Hero | One promise, one supporting sentence, one primary action | Repeating the same value proposition in a side panel |
| Section heading | Pair a clear claim with concise context | Decorative headings without informational value |
| Code window | Real syntax, filename, and visible result | Fake terminal noise or code used only as texture |
| Feature row | Link a concept directly to a working example | Rows that look interactive but do nothing |
| Run input | Collect program stdin beside a runnable example, byte-honest | Unlabeled fields or inputs that quietly rewrite the sample |
| Input hint | State the entry a run input expects, straight from the example's data; no-input cards say so instead of offering a box | Placeholder text that vanishes while typing, or a guessed format |
| Inline validation | Check the box against its declared kind before running, naming what was expected | Program trap lines as the entry's only guidance |
| Run action | Run the compiled example; dim while disabled | A busy state that hides the disabled affordance |
| Run message | Explain runtime and load failures inside the output pane | Long lines clipped behind horizontal scroll |
| Interactive input | Take a program's further reads live — one Send per typed line, End input acting like an empty terminal | A prompt with no place to type, or an output pane that pretends the run already ended |
| Demo grid | Draw a captured run's output cell by cell, tokens only, honest to the artifact's frames | Invented colors or cell sizes outside the tokens |
| Playback controls | Play, pause, or single-step a captured run; the label carries the state, and the run loops from the top | Controls that look active but do nothing |
| Year tabs | Switch between the archive years and the upcoming one; the selected tab fills ink, arrow keys move between tabs | A second page for what one panel switch shows |
| Calendar doors | One door per event day, counted from the day data, each opening that day's view | A hardcoded door count, or a door that promises a solution it cannot show |
| Door status | One of four honest labels per day, with color only supporting the text | A status that hints at answers before they exist |
| Group chip | Summarize a counted group inventory as rounded pills linking to each group's detail | A count the group cannot back up, or pills repeating what a heading already says |
| Code editor | Edit the program as plain labeled text in the mono face | A read-only block posing as an editor, or an unlabeled box |
| Mode switch | Switch one engine between whole-program runs and typed entries; the selected mode fills ink | Two separate pages for what one switch shows |
| Playground link | Open the card's complete editable source in the playground, beside the download action | A link that drops the source, its input, or its module siblings on the way over |
| Tour empty state | A shipped script that runs an entry, a word definition, and a failure with its caret | An empty pane with no way forward |
| Docs search | Find documentation pages and headings from the sidebar, against the build's generated index | A hand-maintained word list, or a field named only by its placeholder |
| Search results | A handful of ranked page and heading links, opened by keyboard or click | A 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
| Token | Role | Color |
|---|---|---|
| Keyword | Declarations, branching, loops, and error propagation | Signal coral |
| Flow | Composition and data movement | Light coral |
| Type | Signatures and contracts | Warm yellow |
| String | Literal text | Soft green |
| Number | Numeric literals and boundaries | Cool cyan |
| Function | Words and callable operations | Paper 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.
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.
- Lead with one clear message and remove repeated explanations.
- Use tokens rather than introducing one-off colors or spacing values.
- Link every element that visually promises interaction.
- Show real Zhex syntax and preserve source fidelity.
- Label experimental, planned, private, or unavailable behavior honestly.
- Check keyboard navigation, mobile reading, code overflow, and reduced motion.