# Buttons - agent guide

> Normative extract of the EchoSistema template for the page
> `/componentes/botoes`. Copy it verbatim: tag names, props, events and classes
> are contract.
>
> Full guide (rules, tokens and every family): `/agents/echosistema-ui.md`

## Rules that apply before any line of code

- Colour only through tokens (`text-fg1`, `bg-panel`, `border-line`, `.es-i--*`); never a hex, never a Tailwind colour.
- Two axes: the intent gives the colour, the variant consumes it. Never combine them by hand.
- Visible text through `t()`; tag names, props and classes stay literal.
- A component does not fetch: it takes props and emits events.
- An icon alone inside a button needs an `aria-label`.

## `<echo-button>`

```vue
<echo-button variant="filled" intent="primary" size="sm" type="submit" @click="save()">
  Save
</echo-button>
```

| Prop | Values | Unset |
| --- | --- | --- |
| `variant` | `filled` `gradient` `outline` `glass` `ghost` | the default lens |
| `intent` | `primary` `secondary` `success` `danger` `warning` `info` `caution` `steel-blue` `navy-blue` `dark` | inherits the context |
| `size` | `sm` `lg` | medium |
| `type` | `button` `submit` `reset` | `button` |

Extra attributes (`disabled`, `aria-*`, `form`) land on the `<button>` through
fallthrough.

## With an icon

The icon goes in the SAME slot as the text; there is no `icon` prop (it would
only take the icons the component knows about, and every derived site brings its
own).

```vue
<echo-button variant="filled" intent="primary">
  <icon-add class="size-4" />
  Create
</echo-button>

<!-- Icon alone: the accessible name is required -->
<echo-button variant="outline" intent="danger" :aria-label="t('remove')">
  <icon-trash class="size-4" />
</echo-button>
```

## A button that navigates

An action that changes route is an ANCHOR, not a button: only an anchor opens in
a new tab and is announced as a destination.

```vue
<NuxtLink :to="localePath('/docs')" class="es-btn es-btn--filled es-i--primary no-underline">
  Read the docs
</NuxtLink>
```

## Submitting a form the button is outside of

```vue
<form :id="uid">…</form>
<echo-button :form="uid" type="submit" variant="filled" intent="primary">Send</echo-button>
```

---

Source: `app/components/echo/Button.vue`