# Component contract · template

Copy this file, rename it after the component and fill in each section. Delete the examples in brackets. If a section does not apply, write "Not applicable" instead of removing it: that shows it was considered.

---

## Identity

- **Name:** [Button]
- **Contract version:** [1.0.0]
- **Status:** [draft | approved | deprecated]
- **Owner:** [person or team that approves changes]
- **Component in Figma:** [exact name and link to the library]
- **Component in code:** [path or package, e.g. `@company/ui/Button`]

## Purpose

- **Use it to:** [start an action in the current view]
- **Do not use it to:** [navigate to another page: use Link for that]

## Properties

| Property | Allowed values | Default | Required | Notes |
|---|---|---|---|---|
| [variant] | [primary, secondary, ghost] | [secondary] | [no] | [only one primary per view] |
| [size] | [s, m, l] | [m] | [no] | |
| [disabled] | [true, false] | [false] | [no] | |

## Content and slots

| Slot | What it accepts | Limits | If exceeded |
|---|---|---|---|
| [label] | [text] | [1–24 characters] | [never truncated: the text is reviewed] |
| [icon] | [system icon] | [optional, one] | |

## States

| State | When it happens | What changes |
|---|---|---|
| [rest] | | |
| [hover / focus] | | |
| [loading] | [action in progress] | [blocked, shows indicator, keeps its width] |
| [disabled] | | |
| [error] | | |

## Tokens it uses

| Decision | Token | Figma variable |
|---|---|---|
| [background, primary] | [color.action.primary] | [action/primary] |
| [horizontal padding] | [space.4] | [space/4] |
| [radius] | [radius.m] | [radius/m] |

Rule: no visual value of the component is written by hand. If a token is missing, propose the token; do not use a loose value.

## Accessibility

- **Role:** [button]
- **Accessible name:** [the label text; if icon only, `aria-label` is required]
- **Keyboard:** [activated with Enter and Space; visible focus]
- **Minimum contrast:** [4.5:1 text, 3:1 border and focus]
- **Minimum target size:** [24 × 24 px]

## Checkable usage rules

Write them so that someone, or an agent, can answer yes or no.

1. [A view has at most one `primary` button.]
2. [The label starts with a verb.]
3. [`disabled` is never used without explaining why next to it.]

## Correct example

[Description or link: primary button "Save changes" at the end of a form, next to a secondary "Cancel".]

## Edge case

[Description or link: label translated into German and twice as long. Expected behaviour: the button grows, it does not truncate; if it does not fit on mobile, it becomes full width.]

## Open questions

What this contract does not decide yet. If an agent or a person has to make one of these decisions, note it here and resolve it in the next version.

- [Is a button with an icon on the right allowed?]

## History

| Version | Date | Change | Approved by |
|---|---|---|---|
| [1.0.0] | | [initial version] | |