# Conventions

> The rules every 0xui component follows, so once you know one you know them all.

## Hook, parts, shell

Each component has three layers, and all of them are exported:

1. **Hook**: all wagmi calls and state. Use it alone to build your own UI.
2. **Parts**: small presentational pieces that take plain props.
3. **Shell**: the default composed component. Variants such as popover and dialog are thin shells over the same hook and parts.

## Props

- `variant`, `size` and `className` on the root.
- Icon slots take a component, or `false` to hide the icon. `disableIcons` hides all of them.
- Overlays can be controlled or uncontrolled: `open`, `defaultOpen`, `onOpenChange`.
- Callbacks are named `onX` and receive typed payloads.

## State

Async components export their state as a union type, such as `type TxPhase = "idle" | "confirming" | "pending" | "success" | "error"`, and set it as `data-phase` on the root element. Style or test each state without reaching into internals:

```css
[data-phase="pending"] { opacity: 0.8; }
```

When an action fails, `data-error` says why, as one stable word next to `data-phase`:

| `data-error` | Meaning |
| --- | --- |
| `user-rejected` | The person dismissed the wallet prompt. Not an error. |
| `reverted` | The transaction or call reverted. |
| `insufficient-funds` | Not enough native currency for the value and gas. |
| `wrong-chain` | The wallet is on, or can't switch to, the wrong chain. |
| `no-wallet` | No wallet or connector is available. |
| `unsupported` | The wallet doesn't support the request, like batching. |
| `network` | The RPC failed or timed out. |
| `unknown` | Anything else. Read the message. |

`errorCode(phase, error)` in `0xui-utils` produces it, for your own components too.

## Agents

Buttons that send, sign or approve carry `data-agent-confirm` with a sentence saying what they do, like "Send 0.1 ETH: sends a transaction on Ethereum from your wallet". Browser agents treat it as "a person must approve this first". Override the sentence with `agentConfirm`, or pass `agentConfirm={false}` to drop it.

Together with `data-phase` and `data-error`, an agent can drive a 0xui interface and know what happened without reading the page. [Agent Tools](https://0xui.io/components/agent-tools.md) also gives agents the wallet state directly.

## Web3 rules

- **Amounts are `bigint`** from end to end. Formatting goes through viem `formatUnits` / `parseUnits`, never `Number()`.
- **Amount inputs use text**, `inputMode="decimal"`, never `type="number"`.
- **Addresses** are checksummed, truncated as `0x1234…abcd`, and copyable.
- **Explorer links** come from `chain.blockExplorers`. Nothing is hardcoded.
- **A dismissed wallet prompt is a cancellation, not an error.** It gets a muted note, not red text.
- **SSR-safe**: nothing that depends on the wallet renders until the component has mounted in the browser.

## Accessibility

- Click targets are at least 44px. Every list supports keyboard navigation.
- Icon-only triggers keep an accessible label.
- Phase changes are announced politely. Errors use `role="alert"`.
- Spinners always have a label. Disabled buttons say what is blocking them.
