# 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

```css
.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

```css
.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

```css
.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](https://storybook-tangible-ui.pages.dev/docs/system-border-helpers.md) 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

```css
.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

```css
.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:

```css
.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;
}
```

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/tokens-behavior--docs