Skip to content

Patterns

Cross-cutting conventions every @diffgazer/ui primitive follows — keyboard handling, compound composition, interaction states, and variants.

Conventions every @diffgazer/ui primitive follows. Read the relevant one before composing or extending a component, or before authoring a new variant dimension.

PatternRead it when
Keyboard NavigationA component needs arrow-key or keyboard handling. Explains the headless-friendly philosophy: primitives expose highlighted, onKeyDown, and selection control points and compose with @diffgazer/keys.
Compound ComponentsBuilding a multi-part component whose pieces share state through React Context — Dialog, Tabs, Menu, NavigationList.
Interaction StatesStyling highlight, selected, or hover. The three TUI states: the keyboard cursor, the persistent choice, and the cosmetic pointer hover.
Variant ConventionsDeciding between CVA, a Record, a CSS file, or plain Tailwind for a variant dimension.

Choosing a variant approach

Variants are the load-bearing convention — the contract referenced from the UI Library Rules. Pick the first rule that matches:

  • Named variant dimensions (size, variant, tone, density) → CVA.
  • A variant key that maps to a non-class value → Record.
  • Styling that needs @keyframes, CSS counters, pseudo-element geometry, multi-attribute data selectors, or forced-colors / reduced-motion overrides → CSS file.
  • A single boolean conditional with no dimensions → plain Tailwind + cn().

See Variant Conventions for the full rules, shared variant modules, and anti-patterns.