v10 · Specimen 2026 · apparat · the mechanism set expanded
Each mechanism, its own logic.
v10 keeps everything v9 got right — the rolling-ball toggle, hairline linework, light physicality, enamel palette — and corrects the small details that didn't: knob tickmarks now sit cleanly in the ring outside the cap, the rocker indicator floats free of the pill's top edge. The pips are now pucks-in-cuts (rocker grammar, small scale). The toggle's off-state shows three hairline detent dots inside the empty slot. And the mechanism vocabulary grows: a step counter, a pivoting lever, a number tumbler, a segmented gauge, a press-and-hold confirmation pad. Each does one thing, in its own mechanical way.
Operating Map
new checkpoint · workflow before mockupThis pass changes the purpose of v10: the page is no longer only a mechanism catalog. It now has to prove how Arrange's real work threads intersect without losing any existing UI exploration.
Grammar Foundations
the language before the sentencesv10 is built from a tiny grammar. The system has three peer primitives, four reductions, and one light source. Everything else — toggles, dials, sliders, hold-pads — is a sentence assembled from this vocabulary. The point is restraint: a designer should be able to compose any new control without inventing a new primitive.
Cut · Puck · Zone
Three peer-level primitives sit at the same hierarchy. Each does one thing the others can't, and each composes with the others. Every visible element in v10 belongs to one of these three roles.
A depression in the surface. The cut's interior is the SAME color as the field — depth comes only from inset shadows. Cuts can hold pucks, text, dots, or fill with enamel to express state.
A raised operable element — a button, knob, wheel, or dial. Pucks for actions live in cuts (the cut is the puck's address). Pucks for persistent state (Type-B) sit on the surface with a state ring.
A same-level region on the surface, tonally distinct from the surrounding field. The zone says "operable elements live inside this area" without changing depth — pucks and cuts compose within it.
A cut is the same color as the field
The interior of an empty cut is paper-white in paper mode, dark-field in ink mode — identical to the surrounding surface. Depth comes only from inset shadows. A cut is not a black hole punched in the paper; it's the paper, recessed. State — checked, held, filled — is what brings color in.
The cut never goes "dark to indicate emptiness." Emptiness is the field at rest. Color is reserved for state.
Text layer near the surface · color layer deep
A cut can reveal two distinct sub-layers at different effective depths. The TEXT LAYER sits just under the surface and stays legible (readable numerals, labels, status dots). The COLOR LAYER sits deep, mostly in shadow until state activates and pulls the enamel up into the cut. Use the text layer for readable content; the color layer for state-as-color.
Same dial, two layers. Default reveals the readable text; .dial-cut--accent brings the deeper color layer up.
Light comes from above-front. Always.
Every shadow in the system is cast by one fixed light source: above and slightly in front. The top of a puck catches a hairline highlight; the bottom drops a 1px shadow. The top interior of a cut is in shadow; the bottom rim catches a sliver of light. This consistency is what lets the eye trust the surface as a coherent physical object — never a collage of effects.
The puck-on-surface drops a shadow downward (light from above); the puck-in-cut shows a dark crescent below it (puck blocks light reaching the cut floor). Same rule, different geometry.
Five depth levels, each with its own mark
When information is nested more than one level deep, switch to a different visual mechanic at each level. The eye categorizes by kind of mark, not by depth of shadow. Stacking shadows of increasing intensity produces visual noise; switching mechanics produces legible hierarchy.
Rule: no mechanic adjacent to itself. A cut may not directly contain another cut — it must contain a stratum first.
Six pigments. State only. Never decorative.
Color is reserved for state. The palette is desaturated by design — real oxide pigment, not RGB-primary. A colored mark on a paper field reads as vermilion, cobalt, jade, ochre, plum, sienna — restraint at the chromatic level.
No purples, no teals, no per-component palettes. If a component needs a color it doesn't have, the system is wrong.
Apply in order. Hold every element against them.
From DESIGN.md. Before adding a screen, control, or feature, hold it against the ten principles. If it fails one, it does not ship until that failure is named and accepted in writing.
- Useful before clever. Every element earns its presence by doing work.
- Reduce until it breaks, then add back one. Subtraction is the default.
- The room is the unit. The whole product is organized around it.
- The plan generates the rest. Information architecture comes first.
- Honesty in materials. A button looks like a button. State changes look like state changes.
- Restraint as ornament. Whitespace, alignment, and typography do the decorative work.
- One voice. Spacing, type, color, motion, copy, iconography follow one system.
- Calm at rest. The interface does not move unless something has actually changed.
- Preserve judgment. The tool documents decisions; it does not flatten them.
- Finish the detail. Door handles and hover states decide whether the tool is felt as cared for.
"Imagine Rams reviewing the screen, then imagine an architect in the middle of programming a 400-room VA hospital using it on a Tuesday afternoon. The screen should satisfy both at once." — DESIGN.md
Mechanisms
the verbs · cuts · pucks · knobs · dials · toggles · sliders · press · statusEvery working mechanism is built from the three foundational primitives. The patterns below are arranged from simplest (a single dot indicating state) to most compound (a window-dial that combines a puck, a cut, a substrate, and an animated paint trail). Same grammar throughout — only the composition changes.
Surface dots · the most reduced state mark
A dot embedded in the field surface. Off = bare rule ring; on = filled with one of the six enamel pigments. No label, no border, no chrome — the dot's color carries the state, its position carries the meaning. Used for status indicators, "live" lamps, group counts.
Checkbox cut · the simplest grammar element
A cut that fills with enamel when checked. No puck, no border, no label on the surface — the entire mechanism is "cut" plus "color in cut." This is the foundational state-as-color pattern that every other compound mechanism extends.
The punch · Type-A button in its address cut
A button puck always has a corresponding void cut into the surface — the void is the puck's address. At rest the puck covers the void with just a hairline halo of black; on press, the puck depresses into the cut. No hover state, no color change — only the press is the action.
Pucks that don't press — state via routed rings
When a puck represents persistent state rather than a press, it has no void address. Instead, state is carried by an enamel arc routed around the puck's perimeter — continuous (CSS conic-gradient) or discrete (SVG tick marks). The puck stays still; the ring loads.
Rotational pucks · two modes
A puck in a circular cut that rotates between positions. Positional knobs land at one of N fixed angles — marker stays at the chosen position, IS the value. Step knobs ratchet one notch per click and snap back to neutral — the marker is momentary feedback, the ring around the knob records the count, the transient label carries the value.
A puck with a window — values walk around the dial
The dial is a puck with two sub-layers: a face on top carrying a pill-shaped cut, and the text layer underneath carrying values. Each click rotates the face one slot so the cut walks around the dial. Numeric (infinite or bounded), enum/words — same mechanism. The last example uses .dial-cut--accent to bring the deep color layer up to the substrate.
Ball in slot · enamel follows
A ball rolls in a slot; the trail behind it fills with enamel. The standard kugel is a hairline-outlined channel; the well variant is a deep cylindrical recess with the ball trapped in a cavity behind a slot opening that's slightly narrower than the ball. During the roll, the paint line travels horizontally across the ball — at the midpoint you see the crisp half-and-half.
Discrete value selectors
N discrete positions, current value carried by the position of the marker. Kugel-style uses the rolling-ball mechanism with detent dots along the slot. Surface-slot cuts only a razor line and detents into the field, with no surrounding chassis. Well-style is the deeper mechanical variant.
The punch · plus two ways to confirm
The punch is the base — a puck in a cut that depresses on press, fires on release. For destructive actions, add a hold-to-confirm layer: hold-ring fills an enamel arc around the puck, hold-fill washes the cut interior with enamel from the bottom up, hold-cut is a standalone cut (not a button) you press into directly. Same intent, three recording mechanisms.
Tonally distinct surface regions
A zone says "operable elements live here" by tonal shift alone — no depth change. Slider tracks, control plates, and grouping containers all use the zone primitive. Indicator dots can sit inside a zone (zone-scoped state) or outside on the bare field (field-scoped state).
Filled wells inside a strip cut
Read-only "N of M" visual: one outer cut (the chassis) holds N small filled-cut wells. Empty wells share the strip's field-colored interior; lit wells fill with enamel — same fill grammar as .check.is-checked, at gauge-segment size.
Specialized mechanisms
Less common but well-defined. Each carries its own physical metaphor: levers pivot around a center, twist-locks rotate the indicator (not the cap), surface labels appear transiently next to a control when it changes.
A number in a cut, two pucks on either side
The number sits in a recessed mono cell. The two puck buttons are raised at rest, depress when held. Disabled at the limits.
One choice at a time
Segmented is a row of mutually-exclusive options, the selected one raised as a puck above the rest. Slot is a pill toggle — off is the bare cut, on is the cut with an enamel dot above it. Use segmented for ≤4 closely related options, slot for stand-alone toggles.
A puck riding a track, value mark above
For continuous ranges where the discrete slider's positions are too coarse. The puck rides a recessed track; the enamel trail behind it grows with the value. A small value pill appears above the puck on hover or focus.
Number wheel · drag-to-commit
Tumbler: a vertical number wheel showing previous, current, next values. Scroll-wheel + keyboard arrows. Used for time pickers, version numbers, anything where adjacent values matter. Slide-confirm: drag the handle from left to right to confirm; release early and it snaps back — friction of intent.
Less common but well-defined
The mechanisms below have specialized roles. Lamp is a status indicator. Plunger is a push-handle for "fire this off" actions. Iris contracts/expands radially (scope-of-view). Dropzone is a drag-drop target. Holdpad is the legacy hold-to-confirm primitive (Hold-cut and Hold-ring from §2I are its successors).
Composition
primitives assembled · the bridge to the applicationA single primitive answers one question. Compositions answer the questions a designer asks while working — what is this room, what changed, what's next, what needs attention. Below: the canonical composition patterns and the containment rule that holds them legible at any density.
A row of live state at a glance
The instrument cluster reads like the panel above a steering wheel: each cell holds one named value with a tiny mono label. Cells share a hairline rule, the values are mono and tabular-numbered. This is the most recurring composition pattern in v10 — it appears on every working surface.
A working row of decisions
Operable elements grouped by intent. A zone defines the active region; dials, sliders, and buttons live inside. An indicator dot outside the zone shows field-scoped state. This is what a "settings panel" looks like in v10 — bounded, legible, no chrome.
Five depth levels · no mechanic repeats
The rule from §1E shipped: when nesting more than one level deep, switch the visual mechanic at each level. Cut → stratum → crest → margin-rule → eyebrow. The example below shows a panel (cut) containing a strata-sectioned interior with a crest sub-region holding a margin-ruled list of eyebrow-labeled values.
What goes where
- Buttons get voids. Any puck that responds to press sits in a cut. The void is the puck's address; it is not optional.
- Indicators get rings or dots. Persistent state pucks (Type-B) carry their state with a perimeter ring; smaller status uses a surface dot.
- Groups get zones. Two or more related operable elements live inside a zone. The zone is tonal only — no extra depth, no border.
- Text near the surface. Labels, values, and dots live in the text layer (near-surface, readable). Enamel fills live in the color layer (deep, state-only).
- No mechanic adjacent to itself. A cut never directly contains another cut. A puck never directly sits on another puck. Switch mechanics at each level of nesting.
- Color is state. Color appears only when something has changed, is active, or needs attention. Decorative color is a bug.
Replace boring text with physical instruments
Most "boring" interface text — status badges, counters, percentages, on/off labels, priority words, sync indicators — has a physical primitive that says the same thing more directly. This is the canonical translation table. Use the primitive when the value is operable or meaningful; keep text only when the value is purely informational and can't be glanced.
progress counter
binary state
status badge
numeric value the user can change
ordered enum
checkbox
severity / "out of"
continuous progress
destructive action
The rule: when the value is actionable (editable, toggleable, settable), use the primitive. When it's purely informational and reads in passing, leave it as text. Never use a primitive that's bigger than the cell it lives in.
Primitives stacked to say more than either could alone
The grammar gets interesting when primitives compose into instruments that show two or three dimensions of state at once — current value AND headroom, current AND target, value AND trend. These compositions aren't new primitives; they're new sentences made from existing words. Each is built from pieces shown elsewhere in this document; they're shown together here because the composition is the contribution.
The dial shows the precise current value (operable). The ring around it shows what fraction of the allowable maximum that value occupies. One glance reads both. As the ring approaches 1.0, the user sees they're nearing the limit even if the number alone wouldn't tell them.
A cut with a center target mark, where the enamel fill grows LEFT for negative drift or RIGHT for positive. The eye reads direction AND magnitude in one mark. When on target (0 drift), the center mark glows emerald — no fill needed. Use for any value with a target: NSF vs program area, ACH vs MEP requirement, schedule vs plan.
Two gauge-strips stacked: current above (cobalt), target below (emerald), aligned cell-for-cell. The eye instantly sees both how far you've come and how far you have left — without doing arithmetic. The same shared cell width is the alignment grammar.
A row of thin enamel marks in a cut, each one an event color-coded by kind. Reads like a heartbeat. Hover for the event narrative. Use as a "what's been happening" indicator in a room's title or a department row.
Three pucks at the vertices of a triangle representing a three-way trade-off (here: program vs schedule vs budget). The active vertex has its cut filled in enamel — you pick one to prioritize. Hairlines connect the three to read as a system, not a row.
None of the above introduces a new primitive. Each is a composition: pieces from §02 stacked, aligned, or wrapped to communicate more than any one alone. When the right pattern doesn't exist, build it from what does — the test of the grammar is whether the language extends without adding vocabulary.
Room Workflow · The Desk
one room · several applets · paper as groundArrange is a project surface, not a configurator. A room is not edited in one big form — it lives across several applets that the planner has open at once. This section drops the chrome and shows the real grammar: paper, then a few applet-cuts on it, then pucks and inner cuts inside each one. No tabs, no lenses. Just a desk with the right tools laid out.
Paper → applet-cut → inner-cut → puck
Information density without overwhelm. Each level of nesting is calmer than the level above, not more elaborate. A puck is a puck whether it sits on paper, in an applet, or three cuts deep. Depth tells the eye what is grouped; tone tells the eye what is categorical.
Raw paper. Edge to edge. No chrome.
A cut into paper. The applet window. Always labeled.
A cut inside the applet. Optional enamel wash for category.
Terminal. The actual data. Stops the recursion.
CATH-201 in progress
The same room you've seen before, now laid out the way it really lives: Detail open in the middle, Lookup and Coordination plates to the right, Tasks below, Workbench preview tucked in the corner. The qty buttons in Detail still cascade live into MEP — that part is real, not a mockup.
Try the qty buttons in Detail · Equipment — the Coordination plate's MEP unmet count cascades.
Application
the grammar at production scaleThe Desk in §4 proves the recursion works for one room. Application proves it scales: the same paper-then-applet-then-cut-then-puck grammar carries the project shell, the detail stack, scope changes, peer papers, and full-screen modes. Every specimen below sits on raw paper — no chrome around the showcase, because there's no chrome around the real surfaces either.
The frame · tree, detail, header · no menubar, no taskbar
The real Arrange shell is three regions: a slim header strip for scope and live status, a tree rail for the project plan, and a detail field for the active node. There is no menubar, no taskbar, no floating windows. Every region is a working surface in v10's grammar — applets, inner-cuts, pucks — not OS chrome layered on top.
Cath Procedure
Each row is a labeled cut into the detail field. Scrolling through them is the room's full editing surface — full content of the stack lives in 5B.
- No menubar. Project · Lookup · Coordinate · Workbench · Output aren't menus — they're tree nodes, scope-switches (5C), or full-screen modes (5E). Reached by the navigator, not by a top bar.
- No taskbar. Arrange doesn't manage windows. Each surface is either inline in the detail stack (5B), a scope switch (5C), or a full-screen mode (5E). Nothing minimizes.
- No floating applets with chrome. An applet is a labeled cut into paper, not a window with minimize / close controls. The chrome is the label and the inner-cuts; nothing else.
- Compare mode adds a third paper (see 5D); multi-project mode opens a second project as a peer rail beside this one, not as a window stacked over it.
The room opens as one scrollable paper
The detail field is not a modal and not a form wizard. It is a vertical stack of applet-cuts inside the selected room: program, attributes, equipment, MEP, Revit, tasks, and outputs. Each cut can be scanned closed, opened inline, or promoted to a full-screen mode in 5E.
Move between project, department, room, and source
Scope changes are not windows. The active paper changes level: project overview, department slice, room detail, reference source, or output package. The chain at the top says where the user is; the scope plate below shows what can be jumped to without inventing menu chrome.
The scope plate changes the content of the paper, not the chrome around it. The tree rail in 5A and the chain above stay coherent no matter how deep the user moves.
Peer papers instead of overlapping windows
Compare mode adds a peer paper for the reference or the other project, then a narrow delta rail between them. Nothing floats. Nothing hides the active room. The user reads left-to-right: baseline, change, current.
Promote a cut when the work needs room
MOVE, MEP coordination, Revit matching, and output packaging can take over the paper. Promotion is a mode change, not a floating app. The scope chain remains, the undo puck remains, and the mode returns to the same room stack when dismissed.
The room canvas as a paper
Workbench is a 5E mode, but it's the load-bearing one — a 3D layout canvas where rooms are placed, scaled, and walked through. In the new grammar the paper is the canvas: a recessed cut at the center, an instrument strip above for live state, a thin tool rail at left, and a panel dock at right. No floating windows. The 3D viewport, the toolbox, and the dock are all cuts in the same paper.
The rules section 5 proves
The rebuild keeps the application legible by making every large move a change of scope, stack, peer paper, or mode. That is the production contract: preserve the user's place, never invent extra chrome, and let downstream consequences stay visible.
From DESIGN.md: the work sits in the line of Rams, Ive, Jobs, and the Bauhaus. The Bauhaus claim — that form, function, and craft are a single problem, not three — is the operating principle. Rams gives the restraint. Ive and Jobs give the insistence on a point of view carried end to end. Le Corbusier gives the conviction that the plan generates everything. Zumthor reminds us that the building (or the app) is felt before it is understood.
Clarity with soul. Clarity without soul is cold. Soul without clarity is noise.
Before · After
v9 → v10 · the same control, refinedGradient, emoji, soft radius, hover-lift. Decorative.
A hairline-outlined cut filled with cobalt enamel. Press deepens the cut briefly. No theatrics.
📋 Room Information
Boxed panel, emoji, bold labels, gradient button. The data is a text list; status is decorative.
No decoration. Status is the puck, not an emoji. Color groups by category, not by ornament. Depth carries grouping.
Implementation Contract
prove the workflow first · no more 90% mockupsThe next v10 UI should not be another composed screenshot. It should be a constrained vertical slice of the real app: one room, one user goal, one source of truth, one completed loop. The surface is only successful if every current capability in the loop still has a home — and every surface in the slice obeys the recursion: paper, applet, inner-cut, puck. No exceptions.
A user changes one equipment quantity and immediately understands what changed, which standard it came from, whether the room drifted from template/reference, what MEP utilities moved, whether reports are still ready, and what Revit needs next.