# Vercel + Geist

Source study: [Vercel + Geist](https://design.thorbis.com/research/studies/vercel-geist). The repository study is `content/design/VERCEL_GEIST_REFERENCE.md`.

Use this reference with [UI](https://design.thorbis.com/skills/ui) when choosing primitives or their states. Open [Type](https://design.thorbis.com/skills/type), [Color](https://design.thorbis.com/skills/color), or [Composition](https://design.thorbis.com/skills/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](https://design.thorbis.com/skills/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](https://design.thorbis.com/skills/type#numbers) 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