vroqjs.com

99-reference/component-vocabulary.md

Component vocabulary

Component vocabulary

This file defines the global public vocabulary for Vroq v02 components.

Use this file as the source of truth when creating, refactoring, or documenting components.

The goal is to make component APIs easy to remember, easy to validate, and easy for LLMs to generate correctly.

Main rule

All public component APIs should start with a props object.

Allowed public call shapes:

Component({ ...props })
Component({ ...props }, ...children)

Do not introduce new public positional signatures such as:

Component(text, props)
Component(label, onClick, props)
Component(binding, props)

Those older patterns are harder to document and easier for LLMs to misuse.

Shared public prop categories

These categories define the common vocabulary that components should reuse whenever possible.

  • common props
  • content props
  • interaction props
  • visual props
  • state props
  • layout props
  • accessibility props
  • composition props

Not every component needs every category.

The rule is: prefer an existing vocabulary word before inventing a new prop name.

1. Common props

Use these across most components when relevant:

  • class
  • className
  • style
  • as
  • id
  • title

Rules

  • class and className are accepted aliases when class-based styling is needed
  • style is the escape hatch for local one-off styling
  • as changes the rendered element when the component supports it
  • id is allowed for DOM identity and labeling
  • title should only be used for semantic titles or the DOM title attribute when that meaning is clear

2. Content props

Use these names for visible content.

  • text — generic text content for text-like primitives
  • label — action label or form control label
  • title — semantic title of a card, modal, section, or compound widget
  • subtitle — supporting title text
  • message — body message for alerts, dialogs, and feedback
  • placeholder — input placeholder text
  • helper — helper text for an input or field
  • error — error message content for a field or feedback component
  • success — success message content for a field or feedback component
  • icon — icon content or icon node

Rules

  • use text for generic display text primitives such as Text
  • use label for clickable or interactive labels such as Button, Checkbox, and menu-like items
  • use title and subtitle only when the component has meaningful title structure
  • do not invent near-synonyms like captionText, btnText, or headingText unless the component truly needs a distinct semantic role

3. Interaction props

Use these names for controlled behavior and callbacks.

  • onClick
  • onChange
  • onOpenChange
  • onClose
  • onFocus
  • onBlur
  • onInput
  • onSelect
  • onSubmit

Controlled value rules

Prefer these names:

  • value + onChange
  • checked + onChange
  • open + onOpenChange

Rules

  • use value for controlled selection or text-like state
  • use checked for boolean input state
  • use open for overlays and disclosure state
  • prefer onChange over custom callback names when the action is fundamentally a value update
  • use onClick for button-like immediate actions

4. Visual props

These define the shared design-system vocabulary.

  • tone
  • variant
  • size
  • emphasis
  • surface
  • shape
  • shadow
  • border

Recommended meanings

  • tone — semantic intent such as neutral, primary, success, warning, danger, info
  • variant — presentation mode such as solid, soft, outline, ghost, plain
  • size — scale such as xs, sm, md, lg, xl
  • emphasis — relative visual weight when a family uses it
  • surface — surface style such as base, raised, sunken, overlay
  • shape — corner or silhouette style such as square, rounded, pill
  • shadow — shadow preset name or boolean enablement
  • border — border preset name or boolean enablement

Rules

  • prefer these words across all families when possible
  • do not create family-local synonyms unless truly necessary
  • if a component needs a new visual prop, it must be justified and documented

5. State props

Use these words when a component exposes a visible or interactive state.

  • disabled
  • loading
  • readOnly
  • selected
  • active
  • invalid
  • required
  • state

Rules

  • prefer booleans like disabled, loading, readOnly, selected, and active when the state is binary
  • use state only when the family truly needs a named multi-state value such as default, error, success
  • do not mix state="disabled" with disabled={true} in the same family unless there is a strong reason

6. Layout props

Use these for container-like and layout-aware components.

  • gap
  • pad
  • align
  • justify
  • wrap
  • block
  • grow
  • inline

Rules

  • gap controls spacing between children
  • pad controls internal padding when a component family uses named padding sizes
  • align and justify should follow flex-style meanings
  • wrap controls flex wrapping behavior
  • block means the component should take full available row width when that concept applies
  • grow means the component should expand in flexible layouts when that concept applies
  • inline means inline rendering where relevant

7. Accessibility props

These are not Vroq-specific, but components should preserve them clearly.

  • aria-label
  • aria-labelledby
  • aria-describedby
  • role

Rules

  • do not hide or rename standard accessibility props
  • icon-only interactive components should usually require an accessible label

8. Composition rules

Container components

Container and layout components may take positional children after the props object:

Card({ pad: "md" }, childA, childB)
VStack({ gap: "lg" }, childA, childB)

Non-container components

Leaf and widget components should use named content props instead of positional content.

Good:

Text({ text: "Hello" })
Button({ label: "Save", onClick })
Checkbox({ checked, onChange, label: "Done" })

Avoid:

Text("Hello")
Button("Save", onClick)
Checkbox(binding, { label: "Done" })

9. Family guidance

Typography family

Prefer:

  • text
  • tone
  • size
  • weight
  • align
  • truncate
  • lines

Action family

Prefer:

  • label
  • icon
  • onClick
  • tone
  • variant
  • size
  • disabled
  • loading

Input family

Prefer:

  • value or checked
  • onChange
  • label
  • placeholder
  • helper
  • error
  • success
  • disabled
  • readOnly
  • required
  • size
  • variant
  • state

Surface and container family

Prefer:

  • title
  • subtitle
  • tone
  • variant
  • surface
  • pad
  • shadow
  • border

10. Migration rule for v02

When refactoring existing v02 components:

  • keep behavior stable where practical
  • move public APIs toward object-first props
  • keep positional children only for container-like components
  • update demo app examples to use the canonical API
  • update docs to show only the canonical API

Final rule

When naming a prop, ask:

1. does an existing vocabulary word already fit? 2. is this prop name semantically clear? 3. will a fresh LLM guess this name correctly? 4. will this make docs shorter instead of longer?

If not, choose a better vocabulary word or simplify the API.