# US UI

> One design system for the US, HERE and NOW surfaces: tokens, React components (a shadcn registry, namespace `@us`) and the rules they carry. HERE is naturally coloured (colour only for state), NOW is quiet, US is social. Read the guide before designing for any of these surfaces.

## Guide

- [Designing for US, HERE and NOW](https://ui.hereandmore.com/guide.md): the surfaces, the laws, the rules the tests hold, every token and component
- [The same guide as one text file](https://ui.hereandmore.com/llms-full.txt)

## Use it

- [Registry](https://ui.hereandmore.com/r/registry.json): add `"registries": { "@us": "https://ui.hereandmore.com/r/{name}.json" }` to components.json, then `npx shadcn@latest add @us/<name>`
- [Tokens](https://ui.hereandmore.com/us.css): CSS custom properties; [Tailwind bridge](https://ui.hereandmore.com/tailwind.css)
- MCP for agents: `{ "mcpServers": { "us-ui": { "command": "npx", "args": ["-y", "@here/us-ui-mcp"] } } }`
- [The gallery](https://ui.hereandmore.com/): every piece in every state, paper and night

## Components

- [Tokens](https://ui.hereandmore.com/r/us-tokens.json): The token contract: one vocabulary, two measured grounds (paper, night). Import first.
- [Component sheet](https://ui.hereandmore.com/r/us-ui-css.json): The plain-CSS component sheet every US UI component is styled by. Names no colour of its own.
- [cx](https://ui.hereandmore.com/r/cx.json): Join class names. No dependency.
- [motion](https://ui.hereandmore.com/r/motion.json): Still (the person's preference or the surface's word), move (a change during which a named thing keeps its place), a transition name, and the ground of a colour — with a sample of a loaded photograph.
- [Button](https://ui.hereandmore.com/r/button.json): A pressable with press feedback on every one; primary, secondary, accent, ghost, bad; four heights; loading.
- [Hold to Confirm](https://ui.hereandmore.com/r/hold-to-confirm.json): Press and hold — pointer or keyboard — fills a ring; release early cancels, hold to the end fires once.
- [Field](https://ui.hereandmore.com/r/field.json): Label, control, hint and an error with the required shape: what happened, what it cost, what to do.
- [Switch](https://ui.hereandmore.com/r/switch.json): A binary state that snaps, never springs.
- [Card](https://ui.hereandmore.com/r/card.json): A surface with a hairline; raised, flat, sunk or glass.
- [Type](https://ui.hereandmore.com/r/type.json): Kicker, Caption, Title, Voice (the serif sentence), Say and Num.
- [Pill](https://ui.hereandmore.com/r/pill.json): A small state read at a glance — five meanings and no more; can be live.
- [Tabs](https://ui.hereandmore.com/r/tabs.json): Roving tabindex tabs: arrows move, Home/End jump, selection follows focus.
- [Sheet](https://ui.hereandmore.com/r/sheet.json): A modal on the native dialog; rises from the foot on a phone; a decision cannot be dismissed by the veil.
- [LinkCard](https://ui.hereandmore.com/r/link-card.json): A way somewhere as one card: a tile whose corner nests in the card's, the place's name and a line, a round way on.
- [Said](https://ui.hereandmore.com/r/said.json): Someone's words as a bubble — the point in full ink — with the face, the name and the role beneath its tail.
- [Scircle](https://ui.hereandmore.com/r/scircle.json): A scircle and who is in it now: the anchor and everyone inside share one gooey halo; someone coming in glides onto the ring and joins it, someone leaving drifts out and pinches off. One is a bubble, three a cluster, more a wreath, and it breathes. The five standings are marks, never size: a PRIME's keel, a guardian's watch (a dot), a PRIME guardian's keel and seal (a diamond), a member plain, a guest in a bubble of their own; ScircleKey names them.
- [Copy](https://ui.hereandmore.com/r/copy.json): A value and a small Copy pill: it copies, says Copied in place, and says so when the browser refuses.
- [Toast](https://ui.hereandmore.com/r/toast.json): Feedback ranked by lifetime: a failure lingers 9 s with a verb, success leaves in 4.5 s.
- [Banner](https://ui.hereandmore.com/r/banner.json): Feedback that lasts as long as the condition does.
- [Faces](https://ui.hereandmore.com/r/faces.json): The people you share with — a stack for a row, a bar for the top of a surface (the US bar).
- [Stat tile](https://ui.hereandmore.com/r/stat-tile.json): A number that matters, with its unit beside it and never fused to it.
- [Row](https://ui.hereandmore.com/r/row.json): One row on the spine: glyph · name+spec · time · value · unit · actions.
- [Skeleton · Empty](https://ui.hereandmore.com/r/state.json): A placeholder that holds the box, and an absence that is said in the serif voice, never styled away.
- [Quiet](https://ui.hereandmore.com/r/quiet.json): The quiet sentence: a corner of a surface that is looking, empty, refused or unreached says so in one line of the quiet ink — never a spinner, never a card.
- [Glyph](https://ui.hereandmore.com/r/glyph.json): The seven places of a world — wonder, attention, market, making, routing, evidence, treasury — one stable mark each, in currentColor.
- [Source](https://ui.hereandmore.com/r/source.json): A provenance card: the verdict, what a source claims, what was actually observed, and what stays unverified. It never states more than was seen.
- [Scrub](https://ui.hereandmore.com/r/scrub.json): Time, scrubbed: a native range with a readout and marks; looking ahead never moves the present, and return-to-now is one press away.
- [Storyboard](https://ui.hereandmore.com/r/storyboard.json): A source as its frames in order — a listbox strip where every frame keeps its time and its provenance.
- [Compare](https://ui.hereandmore.com/r/compare.json): Two places, one clock: a shared control above two panes that can never disagree about the moment they show.
- [Stations](https://ui.hereandmore.com/r/stations.json): A numbered rail: every app has a stable place and the number carries the sequence; it lies down as a row on a phone.
- [Log](https://ui.hereandmore.com/r/log.json): What happened, when: receipts newest first, announced politely, never rewritten.
- [Question](https://ui.hereandmore.com/r/question.json): One question at a time: a band, a kicker, a serif question, one sentence, one control, one pill, a row of dashes.
- [Cover](https://ui.hereandmore.com/r/cover.json): The world is the ground: a photograph or a drawn field carries the page; the words sit on its scrim; a glass note floats beside the actions.
- [Scene](https://ui.hereandmore.com/r/scene.json): A scene: the world as the ground and one question at its foot — Cover and Question, fused. A cut from one scene to the next is a crossfade at the world's own pace that materialises, never a hard cut.
- [Head](https://ui.hereandmore.com/r/head.json): The head of a page: kicker · name · one sentence, the actions at the far edge, the pathway below. One shape for every page, so a person always knows where they are and what they can do here.
- [Frame](https://ui.hereandmore.com/r/frame.json): Evidence wears a frame: corner brackets, the time it was seen, where it came from; live when it is recording.
- [Steps](https://ui.hereandmore.com/r/steps.json): What an agent is doing, numbered, one state each — pending, running, done, refused, skipped — never a fake percent.
- [Thinking](https://ui.hereandmore.com/r/thinking.json): Three dots and an honest clock: who is thinking, for how long, on what.
- [Kernel](https://ui.hereandmore.com/r/kernel.json): The agent's own identity card: who it is, what it is for, whom it works for, its model and host when known, what it costs (always said), what it has spent, and what it may touch — each grant with its scope, a withheld one listed rather than hidden, revocable from the card.
- [Change](https://ui.hereandmore.com/r/change.json): A proposed change to a record, as a card: who proposes it, to what, and every field it would touch — what it holds now, what it would hold, where the new value comes from — before anyone applies it. A field the proposer may not change is listed with the reason; a before it does not know is said as unknown.
- [Memory](https://ui.hereandmore.com/r/memory.json): What is remembered, said plainly: each fact with who said it, where it came from when nobody typed it, when, and how much it weighs — never a hidden profile. A fact can be forgotten where the surface allows it, and forgetting is held, never tapped, because it cannot be undone.
- [Approval](https://ui.hereandmore.com/r/approval.json): A declared act awaiting a person: who proposes it, what it does, what it costs, what it rests on; irreversible acts are held.
- [Composer](https://ui.hereandmore.com/r/composer.json): The ask bar: a field that grows, tools to its left, chips beneath, one black send.
- [Budget](https://ui.hereandmore.com/r/budget.json): Spent against granted. Meters always; refuses only when the grant is metered.
- [Stream](https://ui.hereandmore.com/r/stream.json): Words as they arrive, with a caret while more is coming; announced in additions.
- [Icon](https://ui.hereandmore.com/r/icon.json): Our own icons: 44 drawn from primitives on a 24 grid, currentColor, each with a content hash and an authorship manifest.
- [Wheel](https://ui.hereandmore.com/r/wheel.json): Who drives — you, together, the mind — three positions that never spring back, each saying what it means before it is taken.
- [Palette](https://ui.hereandmore.com/r/palette.json): Ask or find in one field: hits grouped by kind with their reasons, ↑↓ ↵ esc, > @ # prefixes; a query that finds nothing becomes a question.
- [Ranked](https://ui.hereandmore.com/r/ranked.json): A ranked list that says why: numbered rows, reasons with their weight, knobs the person can turn, pin and mute; rank() is pure and tested.
- [Facets](https://ui.hereandmore.com/r/facets.json): Refinement as chips in named groups: each says how many it leaves, the set says what is left, one press clears.
- [NextAct](https://ui.hereandmore.com/r/next-act.json): The next thing, proposed: because · with · when · costs · also considered. One black press does it; nothing happens until it.
- [Suggest](https://ui.hereandmore.com/r/suggest.json): A field with the mind's completion as a ghost after the caret: Tab takes it, Escape waves it away; never the value until taken.
- [Canvas](https://ui.hereandmore.com/r/canvas.json): A place with numbered lanes: pan, zoom, fit; every node reachable by Tab, moved by arrows, opened by Enter; edges as soft cubics; a minimap; the mind's hand named and placed, its pieces marked. layout() and bounds() are pure and tested.
- [Deck](https://ui.hereandmore.com/r/deck.json): A deck of what is open: pinned first, the mind's tabs marked, one waiting dot; arrows move between, Alt+arrows move a tab, Delete closes, middle-click closes.
- [Split](https://ui.hereandmore.com/r/split.json): Two panes and a separator that is a control: drag it or arrow it, Home and End to the edges; the panes stack on a phone.
- [PersonCard](https://ui.hereandmore.com/r/person-card.json): A person as a card: face and name, where they are, the line between you drawn as touches over time, the last touch named, and what the mind suggests next — one press, never taken for you.
- [Explore](https://ui.hereandmore.com/r/explore.json): Discovery as a grid of cards that say their kind, their time and why they are here, and open with one press; a card with no reason says so.
- [Pilot](https://ui.hereandmore.com/r/pilot.json): The pilot rail, the same on every surface: who drives at the top and never out of sight; what the mind is doing, numbered; the next things it proposes, each a card; what it has spent against the grant; the ask bar at the foot.
- [Hand](https://ui.hereandmore.com/r/hand.json): A hand on a thing, visible: who holds it, what they are doing, since when. The canvas's mark for the mind's hand, for any row, field or card — a colleague's hand and the mind's read the same everywhere; it pulses while it moves, goes still when it stops, and never hides.