# Borders

Tangible UI includes a small set of border utilities for common use cases:

- Consistent rounded corners
- Simple 1px borders on all or specific sides
- Semantic border colors that align with the theme tokens

All utilities are scoped to `.tui-interface` so they only affect Tangible interfaces.

## Border radius utilities

Border radius helpers map directly to the design tokens (for example `--tui-radius-sm`). Prefer consuming the tokens directly (`border-radius: var(--tui-radius-sm)`) when you control the CSS — the helpers exist for markup-only contexts. See the [Primitive Token Index](https://storybook-tangible-ui.pages.dev/docs/reference-primitive-tokens.md).

Available helpers:

- `tui-rounded-none` – square corners
- `tui-rounded-xs` – extra small radius
- `tui-rounded-sm` – small radius
- `tui-rounded-md` – medium radius
- `tui-rounded-lg` – large radius
- `tui-rounded-xl` – extra large radius
- `tui-rounded-full` – fully rounded, typically used for pills and circles

Example:

```html
<div class="tui-interface">
  <div class="tui-rounded-sm tui-border tui-border-contrast-low">
    Small radius
  </div>

  <button class="tui-rounded-full tui-border tui-border-primary">
    Pill button
  </button>
</div>
```

## Border utilities

Border utilities default to `var(--tui-color-border)` and use a shared width token. Naming follows logical axes (block / inline) for RTL safety, matching the margin and padding helpers.

- `tui-border` – apply a 1px border on all sides
- `tui-border-0` – remove border
- `tui-border-block` – top and bottom
- `tui-border-block-start` – top (LTR) / top (RTL)
- `tui-border-block-end` – bottom (LTR) / bottom (RTL)
- `tui-border-inline` – left and right
- `tui-border-inline-start` – left (LTR) / right (RTL)
- `tui-border-inline-end` – right (LTR) / left (RTL)

All borders use `--tui-border-width` (default `1px`) under the hood. Override this token to change border thickness globally.

For emphasised edges — selected options, verdict panels, active cards — use the bold step, `--tui-border-width-bold` (default `2px`), instead of hardcoding a width. The pair keeps emphasis consistent across surfaces and lets hosts retune both weights together.

Example:

```html
<div class="tui-interface">
  <div class="tui-border-block-end tui-border-contrast-low">
    Section header with bottom rule
  </div>

  <div class="tui-border-inline-start tui-border-primary">
    Highlighted side
  </div>
</div>
```

## Border color utilities

Border color helpers are semantic and theme-aware. Each class prefers a `--tui-theme-*-border` token and falls back to `--tui-theme-*-base`.

Available helpers:

- `tui-border-primary`
- `tui-border-secondary`
- `tui-border-info`
- `tui-border-warning`
- `tui-border-danger`
- `tui-border-success`
- `tui-border-contrast-high`
- `tui-border-contrast-low`

Example:

```html
<div class="tui-interface tui-theme-default">
  <div class="tui-border tui-rounded-sm tui-border-info">
    Informational callout
  </div>

  <div class="tui-border tui-rounded-sm tui-border-danger">
    Destructive or error state
  </div>

  <div class="tui-border tui-rounded-sm tui-border-contrast-low">
    Subtle divider or container
  </div>
</div>
```

## When to use

- Use `tui-rounded-*` to match plugin UI designs without redefining border radii per component.
- Use `tui-border` and the axis-specific helpers for lightweight separators and container outlines.
- Use semantic `tui-border-*` color utilities for notices, focus rings, selected states, and validation feedback.

These utilities are intentionally minimal. If you find yourself repeatedly hand-writing custom border rules for plugin frontends, consider whether a new helper belongs here.

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/system-border-helpers--docs