--- name: action-icon-usage description: > Use when an app needs the @techsio/ui-kit ActionIcon atom — an icon-only, square action button (toolbar/inline actions). Covers tone, size, disabled state, accessible labelling, and token-first styling. metadata: type: "core" library: "@techsio/ui-kit" component: "ActionIcon" component_version: "2.0.0" requires: "ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # ActionIcon usage `ActionIcon` is an icon-only, square action button for compact/inline actions where a full `Button` with a text label would be too heavy (toolbars, table row actions, input adornments). ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `ActionIcon`. **Use it when** - A single, universally understood icon communicates the action: close, edit, delete, more, expand, copy. - Space is constrained: table row actions, toolbars, input adornments, card corners. - The action repeats many times on the screen, so a text label would be noise. **Use something else when** | Need | Use instead | | --- | --- | | The action is the main thing on the surface, or the icon is ambiguous | Button with `icon` and a text label | | Navigation to another page | Link / LinkButton | | Several actions on one row | one ActionIcon that opens a Menu (`More actions`) | | Decorative icon next to text | Icon | **Do** - Always pass `aria-label` as a verb + object: `Delete product`, `Close notification`, `Copy link`. - Pair it with a Tooltip carrying the same text on pointer devices. - Keep the destructive one last in a group and use the danger tone. - Keep hit area ≥ 24×24 CSS px (the kit sizes do); prefer `md` for touch surfaces. **Don't** - Use icon-only actions for the page's primary action. - Invent icons for abstract actions (`Sync`, `Reconcile`) — use a labelled Button. - Put two different actions with similar icons side by side (edit pencil vs rename pencil). - Disable an ActionIcon without explaining why elsewhere — tooltips don't show on disabled controls. **Copy and states** - The `aria-label` and Tooltip text follow button-label rules from ux-guidelines/ux-writing. - Destructive icon actions still confirm or offer Undo (ux-guidelines/feedback-and-actions). **Behaviour (from the UX spec)** - The glyph is a prop: any `icon` that matches the action. The design file's fixed ✕ master and `Table.IconButton` are both this component. - A close (✕) ActionIcon only closes; the host layer resolves unsaved drafts and returns focus. It never saves or deletes. - There is no loading state; show progress on the row or surface the action changes. **Figma → code** | Figma | Code | | --- | --- | | fixed ✕ glyph | `icon` (any `token-icon-*` / `icon-[…]`) | | `size=sm…lg`, `severity=neutral\|danger` | `size`, `severity` (same values) | | — | `disabled` (removed from tab order) | | `state=hover` | not a prop (browser state) | | `Table.IconButton` | `ActionIcon` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/ActionIcon → UX guidelines*. ## Accessibility An icon-only control has no visible text, so it **must** carry an accessible name — pass `aria-label` (or an equivalent labelling mechanism). Never ship an ActionIcon without one. Since v1.1.0 the type enforces it: `ActionIconProps` requires `aria-label` or `aria-labelledby`, so `` without a name no longer compiles. When spreading Zag trigger props (typed with an optional `aria-label`), pass the name explicitly: `aria-label={triggerProps["aria-label"] ?? "Next slide"}`. ## Styling Use the component's own token classes; do not reach for semantic tokens or arbitrary Tailwind values in app code. Size and tone are props, not ad-hoc classes. Resting and disabled defaults sit below caller background utilities, so a parent control can retain its own photo-overlay surface. Explicit disabled background classes remain available for deliberate state overrides. ## Interaction and sizing contract Sizes sm/md/lg use the shared **icon-control hit area**, not the full boxed-field height: they are supporting actions embedded in fields and toolbars. Default md; prefer lg for standalone touch actions. Disabled actions do not take hover or pressed treatments and are removed from keyboard tab order. Every instance must have `aria-label` or `aria-labelledby`; a glyph alone is not a name. ## Supported tone `severity="neutral" | "danger"`, default `neutral`. Use `danger` for a destructive supporting action, not a nonexistent `variant` prop. Sizes are `sm | md | lg`. ```tsx import { ActionIcon } from "@techsio/ui-kit/atoms/action-icon" ``` The pressed danger foreground/background are an explicit paired set of `--color-action-icon-{bg,fg}-danger-active` aliases; override both together.