> ## Documentation Index
> Fetch the complete documentation index at: https://invoca-5bd45748-mintlify-6c3474a6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Button

> Divergences, open decisions, and undocumented gaps for Button.

See [Button](/invoca-design-system/components/actions/button) for the decided part of this page.

## Known issues

| ID                                                                                | Kind          | What                                                                                            |
| --------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------- |
| [**TITAN-DIV-02**](/invoca-design-system/foundations/divergences#titan-div-02)    | Divergence    | `border-focus` is specified and never implemented — Button inherits its focus ring              |
| [**TITAN-DIV-10**](/invoca-design-system/foundations/divergences#titan-div-10)    | Divergence    | Documentation groups by concept; the package exports by unit                                    |
| [**TITAN-DIV-11**](/invoca-design-system/foundations/divergences#titan-div-11)    | Divergence    | The design vocabulary is prominence; code names the treatment                                   |
| [**TITAN-DIV-23**](/invoca-design-system/foundations/divergences#titan-div-23)    | Divergence    | The theme's naive capitalize-every-word doesn't implement title case's function-word exceptions |
| [**TITAN-GAP-05**](/invoca-design-system/foundations/open-decisions#titan-gap-05) | Open decision | No selection rule where two tokens both apply                                                   |
| [**TITAN-GAP-22**](/invoca-design-system/foundations/open-decisions#titan-gap-22) | Open decision | No component expresses a failed action                                                          |

## Gaps in the current rules

* **The theme's title-case rendering doesn't implement the function-word exception.**
  `textTransform: "capitalize"` capitalizes every word unconditionally; for most short,
  verb-first labels that happens to agree with headline style, but they diverge on any label
  containing a function word like "to" or "of" — "Save Changes To Draft" instead of "Save
  Changes to Draft." See
  [TITAN-DIV-23](/invoca-design-system/foundations/divergences#titan-div-23).
* **The `large` size is reachable and undefined.** See
  [TITAN-BTN-10](#constraints-titan-should-enforce) below.
* **`tertiary` exists as a design term and in no token.** The prominence vocabulary is three
  levels; the token layer names none of them. See
  [TITAN-DIV-11](/invoca-design-system/foundations/divergences#titan-div-11).
* **Icon-only sizing has no rule.** Three icon sizes and two control heights exist; nothing
  states which pairs.
* **`FilterButton`'s applied-state treatment is not specified.** It carries a `count` prop and
  two of its own tokens, and no page states what an active filter should look like.
* **No rule for buttons inside dense table rows** beyond "use a smaller size", which does not
  say which size or what happens in a row that already has three actions.

## Constraints Titan should enforce

These are real, currently-true rules. Nothing in code stops a builder from violating them today —
each is a placeholder for a guardrail Titan hasn't built, not a decision still being made.

| ID               | Constraint                                                          | Would be enforced by                                                                                             |
| ---------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **TITAN-BTN-01** | At most one primary (`variant="contained"`) Button per view region. | Lint scanning a region for more than one `contained` Button.                                                     |
| **TITAN-BTN-04** | Button labels are 1–3 words.                                        | Lint/prop validator counting words in the label.                                                                 |
| **TITAN-BTN-05** | Never more than 3 Buttons in one action group.                      | Lint counting Button descendants of an action-group wrapper.                                                     |
| **TITAN-BTN-06** | A disabled Button is paired with a reachable explanation.           | A required `disabledReason` prop, or a lint rule requiring an adjacent Tooltip/`aria-describedby`.               |
| **TITAN-BTN-09** | An icon-only Button carries an explicit accessible name.            | A required accessible-name prop when no text child is present; standard a11y lint.                               |
| **TITAN-BTN-10** | Size is `small` or `medium`, never `large`.                         | Narrowing the exported `size` type to `'small' \| 'medium'`, or a lint rule flagging `size="large"`.             |
| **TITAN-BTN-11** | Icon comes before the label, never after (needs confirmation).      | Removing `endIcon` from the type, or a lint rule prohibiting it.                                                 |
| **TITAN-BTN-13** | Labels are title case.                                              | A lint rule/formatter enforcing the exact title-case algorithm (with function-word exceptions) on label strings. |