---
name: button-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Button for
actions, including correct variant, theme, size, loading state, icon props,
and token-first styling rules.
metadata:
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
component: "Button"
component_version: "1.0.0"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: ""
contributor_sources: "libs/ui/src/atoms/button.tsx libs/ui/src/tokens/components/atoms/_button.css libs/ui/stories/atoms/button.stories.tsx libs/ui/src/atoms/button.figma.ts"
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.
# @techsio/ui-kit Button Usage
Use Button for in-place actions. Use `LinkButton` for navigation that should
look like a button.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Button`.
**Use it when**
- Any action that changes state on the current page: save, create, delete, open a dialog, apply filters.
- Form submission and dialog/drawer footers.
- Page-level commands in the page header (`New product`).
**Use something else when**
| Need | Use instead |
| --- | --- |
| Navigate to a URL, styled as a button | LinkButton |
| Inline navigation in text | Link |
| Compact repeated icon action | ActionIcon |
| More than three related commands | Menu behind one Button |
| Toggle a setting on/off | Switch |
**Do**
- One `severity="primary"` per surface; secondary actions use `secondary` / `outline` / `ghost`.
- Order groups `[Cancel] [Primary]` — primary last, at the end of the container (ux-guidelines/feedback-and-actions).
- Use `severity="danger"` only for destructive actions and keep them away from Save.
- Show progress with `isLoading` + `loadingText` (`Saving…`) on the button that started the action.
- Add an `icon` only when it speeds recognition (`+` for New, trash for Delete); keep the text.
**Don't**
- Use `OK`, `Yes`, `Submit`, `Confirm` or `Click here` as labels.
- Put two primary buttons side by side.
- Disable a submit button when the user can't see why (ux-guidelines/states#disabled).
- Fake a link with `onClick={() => router.push()}` — use LinkButton.
- Change the label to a result (`Saved!`); confirm with a Toast instead.
**Copy and states**
- Verb + object in sentence case: `New product`, `Create product`, `Save changes`, `Delete product`, `Discard changes` (full table in ux-guidelines/ux-writing#button-labels).
- `Cancel` leaves a form without saving; `Close` closes something with no pending changes.
**Behaviour (from the UX spec)**
- Set `isLoading` only for real async work that starts after local validation passed; a synchronous action never shows loading.
- A failed action keeps the user's draft and reports the problem on the form or object. There is no error Button.
- Hover and focus never change data; a Button is never a hidden navigation.
**Figma → code**
| Figma | Code |
| --- | --- |
| `severity=primary…danger`, `appearance=solid…ghost`, `size=sm…lg` | `severity`, `appearance`, `size` |
| `state=disabled` | `disabled` |
| `state=loading` | `isLoading` + `loadingText` |
| `state=hover` / `focus` / `active` | not props (browser states) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Button → UX guidelines*.
## Setup
```tsx
import { Button } from "@techsio/ui-kit/atoms/button"
```
Supported visual props from `src/atoms/button.tsx`:
```text
severity: primary | secondary | tertiary | danger | warning
appearance: solid | subtle | outline | ghost
unstyled: boolean
size: sm | md | lg | current
block: boolean
uppercase: boolean
isLoading: boolean
loadingText: string
icon: IconType
iconPosition: left | right
iconSize: xs | sm | md | lg | xl | 2xl | current
```
## Core Patterns
### Component font weight
`--font-weight-button` controls Button and LinkButton, with a default alias to
`--font-weight-medium` (500). Override it in the app's theme or local scope to
change buttons without changing other medium-weight text. No weight prop is
needed. Explicit caller classes such as `font-bold` still override the default.
Migration: an inherited CSS alias resolves where it is declared. A descendant
override of only `--font-weight-medium` no longer changes the default button
weight there. Set `--font-weight-button` in that same scope instead. Global
primitive overrides at the alias declaration scope still apply.
### Choose severity from action semantics
```text
primary -> main positive action in the current scope
secondary -> secondary action with normal emphasis
tertiary -> quiet tertiary action
danger -> destructive action such as delete/remove/cancel order
warning -> risky but not destructive action
```
### Choose appearance from emphasis
```text
solid -> strongest emphasis
subtle -> filled but softer emphasis
outline -> boundary/emphasis without solid fill
ghost -> quiet action without a resting surface
unstyled (boolean) -> only when composing inside another component surface
```
There is no `variant="ghost"`. Use `appearance="ghost"` (formerly `theme="borderless"`).
### Let Button own its visual styling
```tsx
```
Do not add background, foreground, padding, border, radius, or font classes
that duplicate Button tokens. If the app needs different colors or sizing,
change app token overrides first.
### Use loading props instead of custom disabling
```tsx
```
Use the component API for loading and disabled state instead of wrapping the
button in a conditional spinner.
## Common Mistakes
### HIGH Native button
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/button.tsx
### HIGH Hallucinated ghost variant
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/atoms/button.tsx
### HIGH Duplicated component tokens in className
Wrong:
```tsx
```
Correct:
```tsx
```
If Button danger should look different in the app, override
`--color-button-*` or related semantic tokens in CSS.
Source: libs/ui/src/tokens/components/atoms/_button.css
### MEDIUM Navigation rendered as Button
Wrong:
```tsx
```
Correct:
```tsx
Products
```
Use Button for actions and LinkButton for navigation.
## Validation Commands
```sh
rg -n "