Behavior Tokens

Tokens that control motion, opacity, and focus states across all components. These ensure consistent interaction feedback throughout the interface.

Motion

Animation duration and easing for transitions. Used by buttons, inputs, cards, modals, and progress bars.

Token	Default	Purpose
`--tui-motion-duration`	`200ms`	Transition duration for hover, focus, and state changes
`--tui-motion-timing`	`ease-in-out`	Easing function for smooth transitions

Usage

.my-component {
  transition: background-color var(--tui-motion-duration) var(--tui-motion-timing);
}

Reduced Motion

Components respect prefers-reduced-motion. When enabled, animations are disabled or simplified. The motion tokens still apply to non-animated transitions.

Opacity

Consistent opacity values for disabled and overlay states.

Token	Default	Purpose
`--tui-opacity-disabled`	`0.75`	Disabled state for buttons, inputs, chips
`--tui-opacity-backdrop`	`0.5`	Modal backdrop overlay

Usage

.my-component[disabled] {
  opacity: var(--tui-opacity-disabled);
  cursor: not-allowed;
}

Focus Ring

Accessible focus indicators. These are intentionally not tied to the primary theme color — focus rings need consistent visibility regardless of brand colors.

Token	Default	Purpose
`--tui-focus-ring-width`	`2px`	Outline thickness
`--tui-focus-ring-offset`	`2px`	Gap between element and ring
`--tui-focus-ring-color`	`#2563eb`	Ring color (accessible blue)

Usage

.my-component:focus-visible {
  outline: var(--tui-focus-ring-width) solid var(--tui-focus-ring-color);
  outline-offset: var(--tui-focus-ring-offset);
}

Accessibility Notes

2px width ensures visibility on all backgrounds
2px offset prevents the ring from overlapping content
#2563eb provides 4.5:1+ contrast on white backgrounds
All interactive components use this consistent pattern

Border Width

Token	Default	Purpose
`--tui-border-width`	`1px`	Standard border thickness

See Border Helpers for utility classes.

Layers (Z-Index)

Consistent stacking contexts for overlays and portaled content.

Token	Default	Purpose
`--tui-layer-surface`	`0`	Base layer, default content
`--tui-layer-elevated`	`2`	Cards, raised surfaces
`--tui-layer-overlay`	`100`	Dropdowns, popovers
`--tui-layer-modal`	`1000`	Modal dialogs, drawers
`--tui-layer-top`	`9999`	Tooltips, toasts, critical UI

Usage

.my-dropdown {
  z-index: var(--tui-layer-overlay);
}

Utility Classes

Layer utilities are available: .is-layer-surface, .is-layer-elevated, .is-layer-overlay, .is-layer-modal, .is-layer-top

Shared Keyframes

Reusable animations defined in _motion.scss. Components reference these instead of defining their own.

Keyframe	Purpose
`tui-fadeFromTransparent`	Fade in (start at opacity 0)
`tui-fadeToTransparent`	Fade out (end at opacity 0)
`tui-fadeFromOpaque`	Start visible (opacity 1)
`tui-fadeToOpaque`	End visible (opacity 1)
`tui-spin`	Continuous rotation (loading spinners)

Usage

.my-tooltip {
  animation: tui-fadeFromTransparent var(--tui-motion-duration) var(--tui-motion-timing);
}

.my-spinner {
  animation: tui-spin 1s linear infinite;
}

Reduced Motion

All animated components respect prefers-reduced-motion. When enabled, animations are disabled via animation: none.

Customization

Override these tokens on .tui-interface to adjust behavior globally:

.tui-interface {
  /* Slower, more deliberate transitions */
  --tui-motion-duration: 300ms;

  /* Bolder borders */
  --tui-border-width: 2px;

  /* More prominent focus ring */
  --tui-focus-ring-width: 3px;
  --tui-focus-ring-color: #000;

  /* Adjust z-index scale for WordPress admin conflicts */
  --tui-layer-modal: 100000;
  --tui-layer-top: 100001;
}