Vercel + Geist · Thorbis UI

Supporting guidance for the UI skill. DESIGN.md owns the rules; Native owns native platform behavior.

Source study: Vercel + Geist. The repository study is content/design/VERCEL_GEIST_REFERENCE.md.

Use this reference with UI when choosing primitives or their states. Open Type, Color, or Composition only when that specialist owns the decision.

Import the contract, not the costume

Thorbis does not become a Geist clone. Keep Inter, Thorbis OKLCH tokens, electric blue, quiet depth, sentence case, the inverted-L shell, and shadcn/Base UI primitives.

This reference describes web/workbench primitives. Native platform behavior follows Native under DESIGN.md D-025.

Take these system rules:

Role before shape

Choose the primitive by semantic job:

comparable columns -> Table
descriptive identity + 1–2 actions -> Entity row
static key/value facts -> Description list
short fixed choice -> Select
searchable known choice -> Combobox
local resource actions -> Menu
global go/do -> Command Menu
one default + close variants -> Split Button
blocking transaction -> Modal
associated desktop context -> Thorbis Inspector, not an ad-hoc drawer

If two primitives look similar, their behavior and semantics decide.

Semantic tokens only

A component consumes role tokens: surface, field, hover, active, selected, rim, text, focus, accent, status. It does not choose a numbered gray or raw value because it looks right.

Bundled type roles

Use named typography roles rather than independently tuning size, line-height, tracking, and weight. Type owns numeric typography; this reference does not define another rule for money or comparable columns.

Layer equals depth

Rest, sink, lift, overlay remain Thorbis law. The semantic layer owns its elevation and z-index. Use the lowest elevation that reads.

Empty state has a reason

Before rendering EmptyState, name one:

first-run
no-results
cleared
permission
plan
error
offline/degraded

Each reason gets specific copy and one primary next/recovery action. Never reuse Nothing here for all of them.

Loading is the final geometry

Skeletons match the row, avatar, field, media, and columns they replace. Preserve dimensions and focus context. A known empty state is not loading.

Actions keep context

Thorbis stays sentence case. Use Verb + Noun when consequence or ambiguity exists: Send invoice, Cancel job, Dispatch tech. Keep the primary row action visible; overflow secondary actions when the row would become a toolbar.

Command surfaces keep scope

⌘K: global go/do; useful zero-query state with recent/relevant items
/: current-view filter/search
Menu: one resource
Search route: refine and compare

A placeholder names scope. Back from a command sub-page preserves the query.

Data primitives are not generic containers

Table is for comparison.
Entity is for identity plus actions.
Description is for facts.
Badge is static metadata, not a disguised button.
Tabs are sibling views sharing scope and URL state. Back and a shared link preserve the selected view.
Gauge is only for a meaningful fixed ratio.

Accessibility belongs to the primitive

Encode focus management, accessible names, keyboard behavior, live announcements, reduced motion, hit targets, and non-color state in the primitive whenever possible. A feature caller should not have to remember the same contract repeatedly.

Test hostile content

Every reusable row/record/control is tested with very short and very long names, long addresses, missing media, portrait/landscape media, long filenames, large money values, localization expansion, and empty optional fields.

Visible grids are contextual

Vercel's visible guide grid is useful in marketing/docs. It is not Thorbis workbench chrome. Use normal layout grid for operational UI.

Refuse

Geist Sans as a Thorbis identity replacement
Vercel's exact colors or shadows
Title Case throughout the Thorbis product
visible construction grids on dispatch/CRM/finance
desktop drawers replacing routes or inspectors
badge-heavy status UI
component choice based only on visual resemblance

Audit

Primitive selected by semantic job
Semantic tokens only
Typography role, not one-off type tuning
Layer and elevation agree
Empty/loading reason is correct
Skeleton matches final geometry
Primary action keeps object context
Command/search/menu scope is correct
Accessibility behavior is owned by the primitive
Extreme user content has been tested