svelte-kit-vice/docs/canon/vocabularies.md

title	type	audience	authority	status	generated
Canonical vocabularies (generated)	canon	human + agent	canonical — the closed sets, generated from the code consts	current	npm run docs:vocabularies (do NOT edit by hand)

Canonical vocabularies

Generated from the code — do not edit. Run npm run docs:vocabularies to regenerate; npm run docs:check fails if this file drifts from the consts. This is the ONE place the closed sets are spelled out (the reason every other doc links here instead of copying a list that would go stale). When building a component you draw part archetypes, event families/verbs, intents and holds from exactly these sets (STUMBLES #1).

Part archetypes (26)

The cross-component classification a part may declare (ARCHETYPE_VOCABULARY, src/uix/morfo/types.ts). Omit it for a plain display part that pulls no shared styling.

Archetype	Role
provider	root context provider
trigger	activates an action or opens an overlay (button-like)
field-trigger	a field/input/select/combo trigger — NOT a button; owns the flush field-control treatment, never the generic button/popover chrome
content	primary content panel of an overlay or section
overlay	modal/dim backdrop behind content
viewport	scrollable / focusable container
item	list / tree / menu item
option	selectable option in a select-like list
indicator	visual progress / decorative state
thumb	draggable handle (slider, scroll, switch)
track	background of slider / scroll / progress
label	text label associated with a control
title	overlay or section title
description	secondary descriptive text
close	dismiss / close button
action	call-to-action button
header	section header (often above content)
footer	section footer (often below content)
image	<img>-based content
fallback	shown when primary content unavailable
arrow	pointer arrow (tooltip / popover)
separator	visual divider
group	grouping container for related items
input	form input element
segment	discrete sub-input (pin-input segment, OTP digit)
preview	file / link / data preview

Sema families (8) — default hold + persistence

Each event declares a semantic.family; the default perceptual hold and persistence come from SEMA_HOLDS_BY_INTENT (src/uix/sema/holds.ts), overridable per event. Named holds map to SEMA_DURATIONS.

Family	Default hold	Persistence	Per-intent overrides
contact	120ms (glimpse)	transient	—
emerge	240ms (brief)	transient	—
shift	600ms (noticed)	transient	—
commit	240ms (brief)	transient	fulfill: 400ms/transient
signal	240ms (brief)	transient	risk: 240ms/untilFix; threat: 240ms/untilAction; loss: 240ms/transient
handle	240ms (brief)	transient	—
sustain	600ms (noticed)	stateBound	—
delegate	600ms (noticed)	transient	—

Sema verbs, by family

The canonical verb set an event may use for each family (SEMA_VERBS, src/uix/sema/verbs.ts). A family.verb pairing outside this is drift.

Family	Verbs
contact	press · tap · activate · focus · trigger · release
commit	select · unselect · toggle · save · submit · confirm · complete · fail · cancel · reset · discard · delete · restore · expire · acknowledge · apply · partial · block · move · set · remove · reorder · upload
signal	announce · notify · warn · alert · inform · emphasize · remind
handle	pick · carry · drop · drag · resize · reorder · rotate · scroll · zoom
emerge	present · dismiss · open · close · expand · collapse · reveal · hide
shift	enter-mode · exit-mode · navigate · route · step · return · context
sustain	start · progress · loading · waiting · syncing · processing · streaming · pending · retrying · upload · end
delegate	offer · plan · authorize · act · review · escalate · return

Sounds (16)

THE catalogue (SOUNDS, src/uix/sema/sound-names.ts). A component names one of these and writes nothing else: the type of a pack rule accepts a name or SILENT, and nothing more. Whether a name resolves to a synthesised recipe or to a .wav is decided here, never at the component.

A name is applied over the family base and BEFORE the intent deltas, so the evaluative profile always survives it — which is what makes the old D.7 / S-07 class of defect impossible rather than merely forbidden.

Silence is not a name: it is SILENT, one canonical value for the whole system ($uix/sema). Declared on a channel slice, the resolver honours it by dropping that channel.

touch · step · tick · open · close · slide · alert · air · settle · snap · tick.fulfill · tick.risk · tick.threat · tick.loss · alert.risk · alert.threat

Intents (6)

The evaluative axis (INTENTS, src/uix/intent.ts). commit and signal require one; the intent policy per family is SEMA_FAMILY_POLICY.

neutral · affirm · fulfill · risk · threat · loss

Directions (2)

The sense of a traversal (SEMA_DIRECTIONS, src/uix/sema/types.ts), projected as data-event-direction. Per emission like the intent, and unlike it undeclarable on the EVENT: one shift-navigate is the previous month and the next one is the following month, so only the caller knows (TriggerOptions.direction). Optional — most occurrences have no sense to declare, and an invented one is worse than none.

A SENSE, never an axis: eidos maps forward onto the inline end and backward onto the inline start, so RTL flips through :dir(rtl) and nothing upstream knows about it. Distinct from SoundContour (ascending / descending, src/uix/sema/sounds.ts), which shapes a pitch, and from Morfo.direction, which names the parts that carry the dir stamp (the RTL contract — see docs/canon/direction-contract.md).

forward · backward

Hold / perceptual durations

The named perceptual scale (SEMA_DURATIONS, src/uix/sema/durations.ts); an event hold is a label from here or a raw ms number.

Label	ms
subliminal	50
glimpse	120
brief	240
settled	400
noticed	600
insistent	1200
persistent	3000

Haptic kinds (7)

The kind a haptic channel signature may use (HapticSignature, src/uix/sema/channels.ts). Haptic is opt-in (new EngineSemantic({ haptic: true })).

tick · tap · pulse · thud · success · warning · error

Palette scales (33)

The donor scales a component color prop accepts under intent="neutral" (PALETTE_SCALES, src/uix/eidos/lib/types.ts) — the per-instance override (<X color="teal">). NEVER hand-count this list.

gray · slate · blue · cyan · teal · green · yellow · amber · orange · red · pink · purple · mauve · sage · olive · sand · tomato · ruby · crimson · plum · fuchsia · violet · iris · indigo · jade · grass · brown · sky · mint · lime · gold · bronze · steel

Sizes (8)

The size scale (SIZES; the physical primitives are SIZE_PRIMITIVE_KEYS, src/uix/eidos/lib/types.ts). full is a layout semantic, not a physical tier. Each component exposes the subset its recipe supports.

Physical: xxs · xs · sm · md · lg · xl · xxl · layout: full

Placement grids (2 × 9)

The 3×3 grids a placement prop draws from (POSITIONS / LOGICAL_POSITIONS, src/uix/eidos/lib/types.ts). Narrow with Extract<…>; add component-only values (static) by union. NEVER re-declare a grid — four components did until 2026-08-15 and were kept in step by hand.

Choosing is a BEHAVIOUR decision, not a naming one: does the placement have to flip for a right-to-left reader? A strip pinned to bottom-end belongs on the trailing edge in both directions; a panel that opens to the physical right because that is where the space is does not. This pair settles EID-3, which recorded the physical exception in July 2026 and left its doctrine pending.

Grid	Mirrors in RTL	Values	Used by
Position (physical)	no — left is the screen's left	top-left · top-center · top-right · middle-left · middle-center · middle-right · bottom-left · bottom-center · bottom-right	Dialog · Drawer · Toast · floating anchors
LogicalPosition	yes — start/end follow the direction	top-start · top-center · top-end · left-center · center · right-center · bottom-start · bottom-center · bottom-end	Affix + its consumers (Fab · MenuDial) · OnionMenu · Avatar badge

Variant archetypes

The canonical variant sets per archetype (EIDOS_VARIANTS, src/uix/eidos/lib/types.ts). A component narrows to one set; component-only values live in its own types.ts.

Archetype	Variants
control	surface · outline · ghost
selection	solid · outline · ghost
chip	soft · solid · outline · ghost
marker	solid · soft · outline
tabs	line · surface · pills · segmented

Shared strings (common.*, 40)

The shared idlangref leaves (commonLangs, src/uix/langs/common.ts), reachable via v.commonRef(...) or #?common.{path}|Fallback — reuse these instead of re-declaring a close/cancel/clear label per component.

buttons.cancel · buttons.clear · buttons.close · buttons.decrement · buttons.dismiss · buttons.edit · buttons.increment · buttons.next · buttons.prev · buttons.redo · buttons.remove · buttons.reset · buttons.save · buttons.submit · buttons.undo · calendar.prev-month · calendar.next-month · calendar.month-select · calendar.year-select · month-grid.prev-year · month-grid.next-year · year-grid.prev-page · year-grid.next-page · date.year · date.month · date.day · time.hour · time.minute · time.second · time.day-period · time.time-zone · time.am · time.pm · time.period.dawn · time.period.morning · time.period.afternoon · time.period.dusk · time.period.night · time.period.late-night · field.empty