Principles
What the system is going for, and where it will have to choose. Each principle comes with a place where both directions are reasonable and the principle tips the decision.
Tools before brand
We are building the workbench first and the storefront later. Every decision right now should make a control clearer, faster, or more consistent. Identity work is deferred, not rejected.
Example
A big illustrated hero on the home page would look great and is on-brand for a library. It also spends effort on the one page librarians spend the least time on, and introduces a visual language we haven't committed to.
Keep the paper
Our palette comes from paper, and paper comes from books. The beige canvas is not sacred as a background, but it is the root of the color theme: every neutral, from the lightest raised surface to the darkest ink, descends from that warm family. The theme can keep evolving as long as it stays recognizably related to what came before.
Example
What visual recognition we have rests on a handful of cues, and the warm neutrals are the strongest of them. A returning user finds their way around a rearranged home page easily enough; a page that has gone cold reads as somewhere else before they read a word. That makes the canvas the cheapest thing to swap and the most expensive thing to lose.
Quiet surface, quick hands
Polished, not extravagant. Flat controls, one accent, muted status colors, gradients and ornament used sparingly. The interface should be forgettable so the books and the work are not.
Example
A moment that deserves celebration, like finishing a reading goal or a big import. A quiet toast is on-principle and a little cold. A flourish is warm and off-principle.
Everything answers back
A pointer landing, a key pressed, a click made: each gets an immediate, visible response. Hover snaps in with no transition. Press squeezes. Selection changes instantly. The site should feel like it is listening even when the server is slow.
Example
A soft hover fade looks more refined when you watch it in a prototype or a demo. Under your own cursor it reads as lag. We chose snap because it feels faster in the hand.
Never hide the wait
Loading, saving, and progress are part of the UI, not a failure state. Every request over about 100 ms shows something: a spinner, a skeleton, or a progress bar. Slow and honest beats fast-looking and blank.
Example
A request that is usually 80 ms but sometimes 2 s. Showing a spinner every time flickers on the fast path. Delaying it leaves the slow path frozen. Pick a threshold and live with the flicker or the gap.
Motion is information
Animate only what changed: something entering, leaving, moving, or changing state. Durations are short, curves are decisive, exits are faster than entries. Reduced motion is honored everywhere.
Example
A subject page hero with a staged reveal would add atmosphere. It is also 600 ms of the user waiting to read. Editorial pages are the most tempting place to break this rule.
Dense on the desk
Desktop is a workbench for people who spend hours here. Controls are compact, more fits per screen, secondary actions are one click away rather than buried. Mobile gets larger targets and simpler layouts, but desktop is not a stretched phone.
Example
44 px touch targets on desktop are safer for accessibility and worse for density. Our medium control is 32 px.
Keyboard is a first-class pointer
Editors and librarians live on the keyboard. Every control is reachable by Tab, every action has a visible focus ring, forms submit on Enter, and focus never gets lost inside a shadow root or an overlay.
Example
Keyboard shortcuts speed up power users and are invisible to everyone else. Adding them means also adding a way to discover them, which is more UI to design.
One way to say each thing
One selected look, one hover mechanism, one icon set. When two components disagree, one of them is wrong. Fewer patterns is the point, even when the second pattern is nicer.
Example
A purpose-built component like the scorecard looks better tuned than the shared one. Every bespoke piece is a debt the next person inherits. Allow it only when the shared component can't be extended.
Nothing shifts
Layout stability is a feature. No weight change on hover or selection, tabular numbers for anything that counts, reserved space for content that is loading. A page that jumps feels broken even when it isn't.
Example
Reserving space for a region that might come back empty leaves a hole. Not reserving it means a jump when it fills. For carousels and availability data we usually can't know in advance.
Accessible is the floor
Contrast is tested in CI. Text is at least 4.5:1, control edges at least 3:1, motion respects the OS setting, and semantics come from native elements first.
Example
Hairline dividers between result rows look better below 3:1. At full weight the list reads as a spreadsheet. We allow extra-subtle for repeating separators, and someone will reach for it on a control border.
Tensions
The pairs that keep coming up, and how we resolve them so far.
- Cozy vs. snappy
- Warm palette and serif titles pull toward slow and soft. Instant hover and short durations pull toward brisk. Color and type carry the warmth, motion carries the speed. Never soften motion to match the palette.
- Density vs. accessibility
- Compact controls and hairline dividers serve the librarian's screen. Contrast is non-negotiable and tested; size floors differ by pointer type.
- Honesty vs. calm
- Showing every wait and every state adds visual activity. The quiet surface wants less. Feedback is local and small, never page-wide unless the page itself is what's loading.
- One system vs. the special case
- Editorial pages, celebrations, and purpose-built tools all want exceptions. Exceptions are allowed only where the shared component can't be extended.