# `BB.TUI.Theme`
[🔗](https://github.com/mcass19/bb_tui/blob/v0.3.0/lib/bb/tui/theme.ex#L1)

Color, style, and rich-text constants for the BB TUI dashboard.

Provides a consistent visual palette for the robot dashboard.
All functions are pure and return a color atom, an
`%ExRatatui.Style{}`, an `%ExRatatui.Text.Span{}`, or an
`%ExRatatui.Text.Line{}` — never a side effect.

## Rich text

  * `brand_title/2` - branded title-bar `%Line{}`
    ("🤖 BB.TUI · MyApp.Robot @ remote@host")
  * `safety_badge/1` - color-coded safety pill (`armed` green-bg,
    `disarmed` dim, `disarming` yellow-bg, `error` red-bg)
  * `key_pill/2` - colored "key" pill `%Span{}` for status / help hints
  * `dim_span/1` - dim-text descriptor span between pills
  * `footer_line/1` - assembles a `%Line{}` from a list of `{keys,
    label}` pairs
  * `proximity_color/1` - foreground color for joint position bars
    based on `BB.TUI.State.limit_proximity/2`

# `armed_style`

```elixir
@spec armed_style() :: ExRatatui.Style.t()
```

Bold green style for armed state.

## Examples

    iex> style = BB.TUI.Theme.armed_style()
    iex> style.fg
    :green
    iex> style.modifiers
    [:bold]

# `battery_color`

```elixir
@spec battery_color(integer()) :: ExRatatui.Style.color()
```

Foreground color for a battery charge readout, keyed on the remaining
percentage (`0`..`100`).

| level     | color  |
| --------- | ------ |
| `> 50`    | green  |
| `21`..`50`| yellow |
| `<= 20`   | red    |

## Examples

    iex> BB.TUI.Theme.battery_color(80)
    :green

    iex> BB.TUI.Theme.battery_color(35)
    :yellow

    iex> BB.TUI.Theme.battery_color(20)
    :red

# `blocked_style`

```elixir
@spec blocked_style() :: ExRatatui.Style.t()
```

Style for blocked commands — dark gray.

## Examples

    iex> BB.TUI.Theme.blocked_style().fg
    :dark_gray

# `blue`

```elixir
@spec blue() :: ExRatatui.Style.color()
```

Blue for interactive elements and paths.

## Examples

    iex> BB.TUI.Theme.blue()
    :blue

# `border_style`

```elixir
@spec border_style(boolean()) :: ExRatatui.Style.t()
```

Returns focused or unfocused border style based on boolean.

## Examples

    iex> BB.TUI.Theme.border_style(true) == BB.TUI.Theme.focused_border_style()
    true

    iex> BB.TUI.Theme.border_style(false) == BB.TUI.Theme.unfocused_border_style()
    true

# `brand_title`

```elixir
@spec brand_title(module(), node() | nil) :: ExRatatui.Text.Line.t()
```

Branded title-bar line — `🤖 BB.TUI · MyApp.Robot[ @ node]`.

`BB.TUI` renders bold over `title_fg/0`; the robot module renders
bold cyan; the optional `@ node` segment trails in dim text.

## Examples

    iex> %ExRatatui.Text.Line{spans: spans} =
    ...>   BB.TUI.Theme.brand_title(MyApp.Robot, nil)
    iex> Enum.map(spans, & &1.content)
    [" 🤖 ", "BB.TUI", " · ", "MyApp.Robot"]

    iex> %ExRatatui.Text.Line{spans: spans} =
    ...>   BB.TUI.Theme.brand_title(MyApp.Robot, :"robot@host")
    iex> Enum.map_join(spans, "", & &1.content)
    " 🤖 BB.TUI · MyApp.Robot @ robot@host"

# `cyan`

```elixir
@spec cyan() :: ExRatatui.Style.color()
```

Cyan for timestamps and active panel borders.

## Examples

    iex> BB.TUI.Theme.cyan()
    :cyan

# `dim_border`

```elixir
@spec dim_border() :: ExRatatui.Style.color()
```

Muted border color for inactive panels.

## Examples

    iex> BB.TUI.Theme.dim_border()
    :dark_gray

# `dim_span`

```elixir
@spec dim_span(String.t()) :: ExRatatui.Text.Span.t()
```

Dim span used between key pills.

## Examples

    iex> span = BB.TUI.Theme.dim_span(" panels")
    iex> span.content
    " panels"
    iex> span.style.fg == BB.TUI.Theme.dim_text()
    true

# `dim_text`

```elixir
@spec dim_text() :: ExRatatui.Style.color()
```

Muted text for secondary information.

## Examples

    iex> BB.TUI.Theme.dim_text()
    :dark_gray

# `disarmed_style`

```elixir
@spec disarmed_style() :: ExRatatui.Style.t()
```

Dim style for disarmed state.

## Examples

    iex> style = BB.TUI.Theme.disarmed_style()
    iex> style.fg
    :dark_gray

# `disarming_style`

```elixir
@spec disarming_style() :: ExRatatui.Style.t()
```

Bold yellow style for disarming state.

## Examples

    iex> style = BB.TUI.Theme.disarming_style()
    iex> style.fg
    :yellow
    iex> style.modifiers
    [:bold]

# `error_style`

```elixir
@spec error_style() :: ExRatatui.Style.t()
```

Bold red style for error state.

## Examples

    iex> style = BB.TUI.Theme.error_style()
    iex> style.fg
    :red
    iex> style.modifiers
    [:bold]

# `focused_border_style`

```elixir
@spec focused_border_style() :: ExRatatui.Style.t()
```

Cyan border style for the active/focused panel.

## Examples

    iex> BB.TUI.Theme.focused_border_style().fg
    :cyan

# `footer_line`

```elixir
@spec footer_line([{String.t(), String.t()} | {String.t(), String.t(), atom()}]) ::
  ExRatatui.Text.Line.t()
```

Builds a `%Line{}` of `key_pill/2` + `dim_span/1` pairs from a list
of `{label, description}` entries. Pass a `{label, description,
:quit}` triple for the warning-red pill.

## Examples

    iex> %ExRatatui.Text.Line{spans: spans} =
    ...>   BB.TUI.Theme.footer_line([{"Tab", "panel"}, {"q", "quit", :quit}])
    iex> Enum.map_join(spans, "", & &1.content)
    " Tab  panel  q  quit "

# `gauge_filled_style`

```elixir
@spec gauge_filled_style() :: ExRatatui.Style.t()
```

Style for the gauge filled portion — green.

## Examples

    iex> BB.TUI.Theme.gauge_filled_style().fg
    :green

# `gauge_unfilled_style`

```elixir
@spec gauge_unfilled_style() :: ExRatatui.Style.t()
```

Style for the gauge unfilled portion — dark gray.

## Examples

    iex> BB.TUI.Theme.gauge_unfilled_style().fg
    :dark_gray

# `green`

```elixir
@spec green() :: ExRatatui.Style.color()
```

Green for armed/safe states.

## Examples

    iex> BB.TUI.Theme.green()
    :green

# `highlight_style`

```elixir
@spec highlight_style() :: ExRatatui.Style.t()
```

Highlight style for selected items.

## Examples

    iex> style = BB.TUI.Theme.highlight_style()
    iex> style.fg
    :cyan
    iex> style.modifiers
    [:bold]

# `key_pill`

```elixir
@spec key_pill(String.t(), :default | :quit) :: ExRatatui.Text.Span.t()
```

Colored "key" pill — keys render bold over a colored background,
used in the status bar and help hints.

Pass `:quit` for the warning red pill (used for `q`); any other
atom uses the calm cyan pill.

## Examples

    iex> pill = BB.TUI.Theme.key_pill("Tab")
    iex> pill.content
    " Tab "
    iex> pill.style.bg
    :cyan

    iex> pill = BB.TUI.Theme.key_pill("q", :quit)
    iex> pill.style.bg
    :red
    iex> :bold in pill.style.modifiers
    true

# `magenta`

```elixir
@spec magenta() :: ExRatatui.Style.color()
```

Magenta for parameter values and accents.

## Examples

    iex> BB.TUI.Theme.magenta()
    :magenta

# `panel_badge_spans`

```elixir
@spec panel_badge_spans(pos_integer() | nil) :: [ExRatatui.Text.Span.t()]
```

Returns the solid-pill badge spans for a panel title. The number
renders bold-black over a cyan background, mirroring the footer
keybind pills so the global `1`..`5` shortcuts are unmistakable in
the panel header. Returns an empty list when `n` is `nil`, so
callers can safely splat the result even for panels that aren't on
the cycle ring.

## Examples

    iex> [%ExRatatui.Text.Span{content: " "}, %ExRatatui.Text.Span{content: " 3 ", style: style}, %ExRatatui.Text.Span{content: " "}] =
    ...>   BB.TUI.Theme.panel_badge_spans(3)
    iex> style.bg
    :cyan
    iex> style.fg
    :black
    iex> :bold in style.modifiers
    true

    iex> BB.TUI.Theme.panel_badge_spans(nil)
    []

# `panel_title_style`

```elixir
@spec panel_title_style() :: ExRatatui.Style.t()
```

Bold style for panel title text, so the panel name stands shoulder
to shoulder with the solid number pill rendered by
`panel_badge_spans/1`.

## Examples

    iex> BB.TUI.Theme.panel_title_style().modifiers
    [:bold]

# `path_style`

```elixir
@spec path_style() :: ExRatatui.Style.t()
```

Style for event path labels — blue.

## Examples

    iex> BB.TUI.Theme.path_style().fg
    :blue

# `proximity_color`

```elixir
@spec proximity_color(atom()) :: ExRatatui.Style.color()
```

Foreground color for a joint position bar based on its limit
proximity (the value returned by `BB.TUI.State.limit_proximity/2`).

| proximity  | color  |
| ---------- | ------ |
| `:normal`  | green  |
| `:warning` | yellow |
| `:danger`  | red    |

## Examples

    iex> BB.TUI.Theme.proximity_color(:normal)
    :green
    iex> BB.TUI.Theme.proximity_color(:warning)
    :yellow
    iex> BB.TUI.Theme.proximity_color(:danger)
    :red

# `ready_style`

```elixir
@spec ready_style() :: ExRatatui.Style.t()
```

Bold style for ready commands — green.

## Examples

    iex> BB.TUI.Theme.ready_style().fg
    :green

# `red`

```elixir
@spec red() :: ExRatatui.Style.color()
```

Red for error states.

## Examples

    iex> BB.TUI.Theme.red()
    :red

# `safety_badge`

```elixir
@spec safety_badge(atom()) :: ExRatatui.Text.Span.t()
```

Color-coded safety badge — a single `%Span{}` pill that reads the
current safety state at a glance.

| state        | bg     | fg     |
| ------------ | ------ | ------ |
| `:armed`     | green  | black  |
| `:disarmed`  | none   | dim    |
| `:disarming` | yellow | black  |
| `:error`     | red    | white  |

## Examples

    iex> badge = BB.TUI.Theme.safety_badge(:armed)
    iex> badge.content
    " ● ARMED "
    iex> badge.style.bg
    :green

    iex> badge = BB.TUI.Theme.safety_badge(:error)
    iex> badge.content
    " ✖ ERROR "
    iex> badge.style.bg
    :red

    iex> BB.TUI.Theme.safety_badge(:disarmed).style.bg
    nil

# `sim_style`

```elixir
@spec sim_style() :: ExRatatui.Style.t()
```

Style for simulated joint indicators — yellow.

## Examples

    iex> BB.TUI.Theme.sim_style().fg
    :yellow

# `tab_active_style`

```elixir
@spec tab_active_style() :: ExRatatui.Style.t()
```

Style for the active top-level tab in the tab bar.

## Examples

    iex> BB.TUI.Theme.tab_active_style().modifiers
    [:bold]

# `tab_inactive_style`

```elixir
@spec tab_inactive_style() :: ExRatatui.Style.t()
```

Style for inactive top-level tabs in the tab bar.

## Examples

    iex> BB.TUI.Theme.tab_inactive_style().fg
    :dark_gray

# `title_bg`

```elixir
@spec title_bg() :: ExRatatui.Style.color()
```

Deep Elixir/BB violet used as the title bar background.

The hue is inspired by the Elixir logo and the Beam Bots
hexdocs "purple" badge.

## Examples

    iex> BB.TUI.Theme.title_bg()
    {:rgb, 78, 42, 90}

# `title_fg`

```elixir
@spec title_fg() :: ExRatatui.Style.color()
```

Light lavender foreground used on top of the title bar background.

## Examples

    iex> BB.TUI.Theme.title_fg()
    {:rgb, 230, 210, 245}

# `unfocused_border_style`

```elixir
@spec unfocused_border_style() :: ExRatatui.Style.t()
```

Dim border style for inactive panels.

## Examples

    iex> BB.TUI.Theme.unfocused_border_style().fg
    :dark_gray

# `yellow`

```elixir
@spec yellow() :: ExRatatui.Style.color()
```

Yellow for transitional states (disarming).

## Examples

    iex> BB.TUI.Theme.yellow()
    :yellow

---

*Consult [api-reference.md](api-reference.md) for complete listing*