00Read this first
- These values are the system. Every token on this page exists in css/benran-core.css; do not invent parallel ones.
- Search the components before building one. There are six, plus two sheet formats; most needs are a link, a stamp, or a trail.
- No ad-hoc values: no raw hex, no one-off sizes, no new easing curve. The motion budget is two durations and one curve.
- Token names are roles. --trace is linework, --accent is the seal. Read what a token is for, not what colour it happens to be.
- One tenth, one accent. Content stays near a tenth of the surface. Seal, trace ripple or roundel - only one may lead, and there is never more than one seal.
- No weight, no fill, no depth. No bold, no panels or washes, no shadows, gradients or glass, and no radius except circles and the seal.
01Colour
Nine role tokens. Each dot is split: paper by day on the left, the same sheet at night on the right, so both themes are on the page at once. At night the ground goes to inkstone and the silhouettes become paper cutouts - the names stay true because none of them names a hue.
| Pair | Day | Night | What it may carry |
|---|---|---|---|
| --ink on --paper | 14.0 : 1 | 14.1 : 1 | Everything essential, at any size. |
| --faint on --paper | 3.5 : 1 | 3.5 : 1 | Text 18px and up, or a caption that repeats an adjacent label. Nothing smaller and essential. |
| --faint on --surface | 3.6 : 1 | 3.3 : 1 | The same rule on a sheet; the night value is lower, so treat it as the floor. |
| --accent on --paper | 4.1 : 1 | 4.7 : 1 | The seal and the link dot. Never words. |
| --on-accent on --accent | 4.1 : 1 | 3.8 : 1 | The seal's reversed mark. Decorative. |
| --trace, --trace-alt, --hairline | 1.8 / 2.2 / 1.5 | 2.4 / 2.3 / 1.5 | Lines only. None of them ever carries text. |
The night theme is authored, not inverted. The trace colours are pulled down to roughly the same quietness against inkstone that they have against paper, and faint is set to the same 3.5 : 1 in both - so a ripple is exactly as loud at night as by day, and the contrast rule for faint text does not quietly change meaning when the theme flips.
02Typography
Four voices, all quiet. Words of weight stand upright in a vertical column; the small voice that names things is a tracked Latin caption; body text is a serif at a double line height. There is no bold anywhere - emphasis comes from placement and isolation.
A short paragraph of placeholder text. It runs narrow, sits low on the sheet, and leaves the air around it alone.
| Token | Size | Tracking | Where |
|---|---|---|---|
| --fs-display-lg | 34px | 0.4em | The largest vertical word. One per sheet. |
| --fs-display | 26px | 0.4em | The wordmark in a title block; a sheet's vertical title. |
| --fs-heading | 18px | 0.5em | Section headings, bookmark titles. Uppercase, weight 400. |
| --fs-label | 15px | 0.45em | The stamp button's upright label. |
| --fs-body | 13px / 2 | 0 | Running text in the serif stack, capped at 36em. |
| --fs-small | 11px | 0.3em | Chips, list numbers, the x mark. |
| --fs-caption | 10px / 300 | 0.35em | Captions, links, field labels, placeholders. Uppercase. |
| --track-num | 10px / 300 | 0.25em | Numbers and dates: tiny, tracked, never tabular columns. |
| --font-serif | Songti SC, Palatino Linotype, Book Antiqua, Palatino, Noto Serif CJK SC, SimSun, serif | Vertical display, headings, body. Songti first carries both scripts where it exists; elsewhere a Latin serif sets the Latin and the CJK serif catches the rest. System fonts only; nothing is vendored. | |
| --font-sans | Avenir Next, Futura, Century Gothic, Helvetica Neue, Arial | Captions and numbers. A geometric sans, light weight. | |
Vertical text is set with text-orientation: upright, so a Latin word stands letter over letter instead of lying on its side. It keeps the column reading as an object on the sheet - a signboard, a spine - rather than as a rotated line of text, and it lets the same voice carry any script without a second rule.
03Space and layout
Space is the material. The gaps are large and few: a section sits 170px from the last one, a block 56px from its heading, and inside a component the rhythm stays small and tight so the objects read as objects.
| Token | Value | Note |
|---|---|---|
| --page-max | 1060px | Measure ceiling, centred. |
| --page-pad | 40px / 22px | Side margin; the smaller value below 760px. |
| --space-section | 170px / 120px | Between sections. The paper between chapters. |
| --space-block | 56px | Between a section's heading and its content. |
| measure | 36em | Body text never runs wider. |
| breakpoints | 900px / 760px | At 900 the composed sheet drops a column; at 760 everything goes to one column and the margins and section gap shrink. |
| 8 | 8px | Between the dots of a trail. | |
| 14 | 14px | Pagination circles; the x mark's columns. | |
| 22 | 22px | A component's caption to its specimen. | |
| 26 | 26px | Between items in a component row. | |
| 56 | 56px | --space-block. | |
| 70 | 70px | Between components and motifs. | |
| 170 | 170px | --space-section. |
The scale jumps from 70 straight to 170 on purpose. Between those two numbers is the distance at which a reader stops seeing one arrangement and starts seeing two - and this system only ever wants one or the other, never the uneasy middle.
04Form
The silhouette is a line, not a box. One-pixel hairlines, a shelf edge with angled ticks, and circles. Nothing has depth: no shadow, no gradient, no glass, and the only rounded shapes are true circles and the seal.
| Token | Value | Where |
|---|---|---|
| --rule | 1px | Every line: horizon, edges, underline, focus outline. There is no second weight. |
| --tick | 9px | The shelf's end ticks. |
| --tick-angle | 35deg | Their lean - a shelf edge seen in slight perspective. |
| --focus-offset | 3px | Focus is a 1px ink outline standing 3px off the element, everywhere. |
| radius | 0 / 50% / rx 4 | Square by default; circles for roundel, dots and pagination; the square seal alone gets rx 4 on a 22 box. |
| elevation | none | No shadows. Sheets are separated from paper by a hairline and one step of ground. |
A single line weight is what keeps a sparse page from looking unfinished. When every rule, edge and outline is the same 1px, the eye reads them as one drawing - add a 2px rule anywhere and it becomes the loudest thing on a page that has almost nothing else on it.
05Motion
Stillness. Two ambient moments - a ripple that slowly widens and fades under an object, and steam dots that drift up three pixels - and two short fades for interaction. Nothing slides, bounces, or scales on hover.
| Token | Value | Where |
|---|---|---|
| --t-fade | 0.3s | The link's seal dot, chip border, input underline, pagination fill. |
| --t-ink | 0.35s | The stamp button inking. A touch slower, like ink taking. |
| --ease | ease-out | The only interaction curve. |
| --d-ripple | 7s | One ripple, scale 0.2 to 1, fading out - on --ease-ripple. |
| --ease-ripple | cubic-bezier(0.16, 0.84, 0.44, 1) | Fast release, long settle - how a ring on still water behaves. |
| --d-steam | 6s | Steam dots drift 3px, ease-in-out, staggered 0.7s apart. |
Only opacity, colour and the two ambient drifts are allowed to move. A page this empty amplifies every motion on it, so anything faster or larger than a fade reads as an event. Under prefers-reduced-motion the ripple freezes at three-quarter size, the steam stops, and nothing is lost.
06Screen - still water
One optional surface treatment. Below the horizon the paper becomes still water seen at a low angle: hairline rings travel out from under the resting object. Move across the right-hand panel and the source follows you, slowly; press and a single ink ring drops into the surface.
| Uniform | Value | What it does |
|---|---|---|
| uHorizon | 0.62 | Waterline height from the bottom. Matches the overlay horizon at 38% from the top; nothing is drawn above it. |
| uPitch | 26px | Ring spacing across the water, in CSS pixels scaled by device pixel ratio. Divided by uFlat it is still 5px front to back, so rings never merge into a band. |
| uFlat | 5.0 | Vertical squash. Circles on the water, flat ellipses to the eye - a low viewing angle, like the ripple motif. |
| uReach | 0.26 | How far the rings carry before fading, in canvas widths. |
| uSpeed | 0.22 | Rings emitted per second. Slow enough that no single ring draws the eye. |
| uLine | 1 CSS px | Every ring is one hairline. Width is held constant with fwidth, so rings stay 1px at their flanks. |
| uDropSpeed / uDropFade | 0.22 / 0.9 | The pressed ink ring: growth in canvas widths per second, and decay per second. |
| uPaper / uTrace / uInk | tokens | Read from --paper, --trace and --ink at runtime and re-read on every theme change. The shader has no path to --accent: the seal is never water. |
| spring | k 34 / d 8 | The source follows the pointer on a spring, and returns to rest under the object when the pointer leaves. |
Enhancement only. Underneath the canvas is the complete static design - the ripple motif at the waterline - and the canvas stays transparent until its first frame, so a machine without WebGL2 loses nothing. It stops when scrolled off screen, and under prefers-reduced-motion it draws one settled frame and never starts a loop. It draws lines and nothing else, so the emptiness rule holds inside the canvas too.
Where it belongs: the empty lower half of a sheet, under an object resting on a horizon. Not behind text, and never across a whole page - water with nothing resting on it is only noise.
07Components
Six components and two sheet formats. Every state is live: hover, focus with the keyboard, press the chips and the pagination. Disabled items are actually disabled.
- First entryCaption06:00
- Second entryCaption09:30
- Third entryCaption12:00
- Unavailable entryCaption--:--
Every hover is a colour change and nothing else, and every disabled state is the hairline colour. With no weight or fill to lean on, the system has exactly one way to say "not available": let the thing fade to the colour of the rules around it.
08Motifs
The signature shapes. A reader recognises Benran from these long before the palette: a shelf edge, small solid objects, a roundel, one seal, a trail of dots, flat rings on water.
The objects are solid because everything else is a line. A 1px page needs a few points of real mass to rest the eye on, and a small filled silhouette carries that mass without a panel or a wash. The cutouts in each one are paper showing through - which is why, at night, they read as the ground rather than as highlights.
09Composition
The parts on one sheet: a head, a vertical title with the sheet's single seal, a narrow column of text and a trail list, and one object resting on the horizon. The copy is placeholder, so what a reader takes away is the arrangement - and how much of the sheet is left empty.
A short paragraph of placeholder text. It sits in a narrow column, keeps to the upper left, and leaves the rest of the sheet to the air.
- First entry01
- Second entry02
- Third entry03
| Part | As built | Why it is that way |
|---|---|---|
| Sheet | --surface, 1px --hairline | One step off the paper and a hairline edge - separated without a shadow. |
| Head | roundel + caption + number | The roundel is in ink here, because the ripple is this sheet's accent. Only one may lead. |
| Vertical title | --fs-display, upright | The sheet's one word of weight, in the corner, not the centre - it is an object placed on the page, not a headline over it. |
| Seal | --accent, 18px | Under the title, where a signature goes. The only seal on the sheet, and small enough to sign it rather than lead it. |
| Text column | 22em max | Narrow and high. Together with the title and head it keeps content near a tenth of the sheet. |
| List | b-list | The trail between entries is the same dotted path as the steam - one motif doing two jobs. |
| Shelf | 60% horizon + object + ripple | The object sits on the line and the ripple spreads under it. Nothing floats. |
| Caption | v-num | At the foot, centred on the object it belongs to. |
It is tempting to fill a sheet like this - a second object, a longer paragraph, a second seal. Each addition would be fine alone, and together they would turn the sheet into a layout. The test before adding anything: what would have to leave to make room for it?
10Rules
The refusals matter more than the permissions.
- Keep every element small and let the paper carry the composition.
- Anchor every object on a horizon, a trail or a ripple.
- Let one accent lead each surface: a seal, a trace ripple, or a roundel.
- Carry every essential word in --ink.
- Check both themes with the masthead toggle - they are authored separately.
- Set vertical words upright, whatever the script.
- Fill any area larger than a silhouette. No panels, no washes.
- Use a bold weight. Emphasis comes from placement and isolation.
- Add shadows, gradients or glass.
- Round a corner, except true circles and the seal.
- Place more than one seal on a surface.
- Let --trace, --trace-alt or --hairline carry text.
- Run the still-water screen behind text or across a whole page.