# Arena by Dravensoft, the Angular corpus

> Use this skill to build user interfaces with Arena, a token-driven design system with React and Angular component libraries on a shared Tailwind layer, for production screens or for throwaway prototypes and mocks. Covers design tokens, colour, type, spacing, motion, iconography, and the accessibility pattern each component binds. Arena carries the design language and not the skin: it ships Dravensoft's palette and fonts, and any project declares its own in arena.config.json and answers the kernel's style roles with a style plugin of its own.

Every document Arena hands a builder working in Angular, concatenated in the order the
router reads them. Nothing from the other framework layer is here, because a component ships
under both names and the two documents are not interchangeable.


<!-- skills/design/SKILL.md -->

---
name: design
license: MIT
description: "Use this skill to build user interfaces with Arena, a token-driven design system with React and Angular component libraries on a shared Tailwind layer, for production screens or for throwaway prototypes and mocks. Covers design tokens, colour, type, spacing, motion, iconography, and the accessibility pattern each component binds. Arena carries the design language and not the skin: it ships Dravensoft's palette and fonts, and any project declares its own in arena.config.json and answers the kernel's style roles with a style plugin of its own."
metadata:
  homepage: https://arena.dravensoft.org
---

# Arena

Arena is Dravensoft's design language: a token layer, React and Angular component libraries
built on it, and a shared Tailwind layer. Its identity is warm black under bone text, crimson as
the voice and gold as distinction.

**Arena is a product-application library**: tables, forms, navigation, dialogs, charts, cards and
the states around them, the furniture of an application somebody works in. A media or a consumer
product is a different register, so a photo wall, a feed of posts, a document editor or a game
map is markup you write yourself; the skin travels either way, because a style plugin answers
every role whatever the product is. **When that is your product**, or one screen of it,
[`references/media-register.md`](./references/media-register.md) is what Arena hands you instead
of a component: the pattern your markup binds, the parts the package already ships for it, and
the one rule that bends.

**This file routes. Read only what your task needs.** The rules below bind the code you write;
the table under them routes. Read the rules once rather than per screen.

## Which job is this?

**Building something with Arena** (a screen, a prototype, a skin, an integration): stay here, and
follow the table below. **On a project you have not walked yet**, start at
[`references/cold-start.md`](./references/cold-start.md) instead, whose first question is whether
the project already carries Arena: one that does is a short walk that reads the config and the
plugin it already has, and one that does not is the only page asking what this product looks like
before anything answers.

**Changing Arena itself** (adding a component, moving a token, editing a contract or a gate):
read [`AGENTS.md`](https://github.com/dravensoft-dev/arena/blob/main/AGENTS.md) instead. It is the
root of that branch and this file is not, and it is named by URL because that branch is the
repository's and reaches nothing a package or this site carries.

**A value you answer is not a value you move**, which is what decides the branch when the job is
an appearance: a role your project fills is this branch's whatever it paints, and a scale step
every product reads is the other one's, the type and page rhythm ladders aside. **Every path here outside `references/` is a repository
path**, carried by a clone, by the plugin, and by the copy `arena-to-prod --skill`
installs; read on the repository above otherwise.

**Everything here is one component at a time.**

## In this order

**Before the first screen, and once per project rather than per screen**, settle what this product
is and what it looks like, because a screen written ahead of that is written against decisions
nobody made. [`references/cold-start.md`](./references/cold-start.md) is where that happens, and
it is a tree rather than a list, whose branches reach the four decisions a project settles once,
the interview that comes before them when there is no appearance to read, the catalogue of
measured style plugins a project can start from instead, the identity document every branch
converges on before a file is written, and the two questions that decide an install rather than a
screen: how much of the product has to be found from outside it, and what it is assembled on. Its
last node derives the dependency list from those answers, so nothing has to be guessed at install
time.

Then, per screen:

1. **`frameworks/<layer>/INDEX.md`**: the directory of your framework's components, naming every
   one under the category it is filed under. Read your layer's, and no other. It is short because
   it describes nothing: it tells you which category holds the name you are reaching for.
2. **`frameworks/<layer>/components/<category>/INDEX.md`**, linked from there: every component in
   that category under the names the layer binds them to, with what each one is and what it takes,
   each linking its own prompt. Read the categories you are reaching into, and no others: a screen
   of any size reaches into two or three, and the saving is the four you skip.
3. **The component's own `.prompt.md`**, linked from that index: its members as a table, its
   examples and its Do/Don't. Read one per component you actually write, and no more.

[`frameworks/INDEX.md`](../../frameworks/INDEX.md) is the layer-neutral index beside those three,
and it answers the one question your layer's cannot, which the table below routes. Skip it when
you already know what you are reaching for.

A prompt states every member's type and default, so `contracts/api/components/<Name>.json` is
only for the reasoning behind one, and you will rarely need it.

## The rules, and they are not style preferences

Every one of these is a rule of the language rather than a preference, and most are enforced
inside Arena by a gate over Arena's own tree. **No gate reads your application**, so in your code
these hold because you hold them. What comes closest is `arena-to-prod --audit`, which reads
your sources for the five of these that source text can show: a class of your own on an Arena
component, one wrapped in your router's link, a raw value where a token belongs, an icon as an
element, an emoji. It reports rather than fails unless you add `--strict`, and it decides nothing
about the rest, so breaking one of those is still a defect nothing will report.

- **Tokens are the only styling layer.** A raw colour, or a bare `16px`, is a bug. A hex, a
  channel triple in `rgb()` or `oklch()`, and a colour's own name are the same defect written
  three ways. Read a value through its custom property (`var(--crimson)`, `var(--sp-4)`), derive
  it with `calc()`/`clamp()` over one, or mix it with `color-mix()` over one.
- **Danger is outline, never filled**: transparent background, border and content in
  `--error`/`--danger`. The single filled danger surface in the whole system is the final
  irreversible confirmation inside `ArenaConfirmDialog`.
- **One primary accent per view.** Crimson is the voice; at most one `variant="primary"`
  action on a screen. Gold is distinction and focus, not a second primary.
- **No gradients** on any surface. Depth comes from the `base-100` to `base-200` to `base-300`
  surface scale, the hairline border and the warm shadow. `ArenaSkeleton`'s neutral shimmer is the
  one exception.
- **No emoji**, in product or in copy.
- **Icons are Phosphor class-name strings, never elements and never SVG**:
  `icon="ph-bold ph-plus"`. Install `@phosphor-icons/web`; Arena never bundles it.
- **Two themes, dark first.** Dark is `:root`, light is the `.arena-light` class. Components
  are never rewritten per theme, because they read tokens. `.arena-compact` re-densifies
  and `.arena-comfortable` grows the controls to a 48px touch target; the two are exclusive.
- **A chart carries identity or meaning, never both.** The `--color-cat-*` ramp in fixed order
  is identity; the status colours are meaning. Status colours are never series colours.
- **Copy is English, formal and direct**, concrete action verbs, no boastful adjectives.
  Errors are blame-free and say what to do next.
- **An anchor Arena draws splits its activations.** A primary click with no modifier, and
  Enter, are cancelled and reported through the component's own event, so route from that
  handler and nothing navigates twice. A modified click, a middle click and the context menu
  are the browser's: they open the `href` themselves and report nothing. **Never wrap an Arena
  component in your router's own link**, which nests an anchor inside an anchor, and in Angular
  does not bind at all. `ArenaCard.href`, `ArenaCommand.route`, `ArenaCrumb.href` and `ArenaSideNavItem.href`.
- **A press that starts on a control keeps to that control.** Where Arena draws an activation
  target around content you write, a card or a table row, a click or an Enter that begins on a
  button, a link or a field inside it runs that control and nothing else; a press anywhere else on
  the surface activates the surface. So a card or a row may hold your own controls, and it may also
  hand the press over entirely by not being interactive at all.
- **A required member absent is a caller bug**, not a state to render. Every layer fails hard
  rather than drawing something empty, so an absent one is loud on the first render.
- **No render follows from whether you bound a listener or filled a slot.** A member decides,
  always, because at least one platform cannot ask the question.
- **A few components answer with a method rather than a member**, since no member is
  imperative. The component's own document names them where they exist.

## Where each question is answered

| Question | Read |
|---|---|
| I am starting a project that has no appearance yet. What do I ask, and in what order? | [`references/cold-start.md`](./references/cold-start.md): the tree, its five questions, the catalogue of measured style plugins, and the identity document every branch converges on |
| Which layer, which architecture, and what do I have to install? | the same tree's last three nodes: how much the product has to be found decides the layer and a peer, what it is assembled on is answered per architecture with the evidence for each, and the dependency list follows from both |
| What may I build this with, and how sure is Arena about each answer? | [`references/stack.md`](./references/stack.md): the package manager, the runner, the module format, the bundler and the framework version, each answer carrying the evidence it actually has. Arena is built with bun, React 18 and Angular 22, and none of that is a requirement on you |
| How do I make Arena look like my own product? | [`references/style-kernel.md`](./references/style-kernel.md), once per project and before the first screen |
| Which of those answers actually change how it looks? | the same document's table, measured over eight products built on this kernel |
| Does what I am building have to be found from outside it? | [`references/seo.md`](./references/seo.md), once per project: what Arena writes into the `<head>`, and which layer writes it |
| What questions does the kernel ask? | [`contracts/design/roles.json`](../../contracts/design/roles.json), one entry per role, with a type and a description and no value |
| Does a component like this exist at all, and what if it does not? | [`frameworks/INDEX.md`](../../frameworks/INDEX.md), which also says which layers ship it. A no is one of three: your product is a different register and the markup is yours, [`references/media-register.md`](./references/media-register.md); Arena ships none on purpose, which [`references/surface.md`](./references/surface.md)'s last section states with the reason; or nobody has added one, which is the other branch, named at the top of this page |
| Which category holds the component I am reaching for? | `frameworks/<layer>/INDEX.md`, which names every one of them and describes none |
| What is it called in my framework, what does it take, and where is its prompt? | `frameworks/<layer>/components/<category>/INDEX.md` |
| How do I use this component? | its `.prompt.md`, linked from that index |
| What exactly does this member take? | the members table in that same prompt |
| Why does this member exist at all? | `contracts/api/components/<Name>.json` |
| What else does the package export, besides components? | the layer's `PACKAGE.md`: the theme surface, the two measurements, the chart ramp helpers, and Angular's projection markers |
| How do I size a page layout, or fit a panel to its own box? | the same section: `useArenaViewportBelow` / `arenaViewportBelow` for a page, `useArenaContainerWidth` / `arenaContainerWidth` for a box |
| What do I paint my page and my own markup with? | [`references/page.md`](./references/page.md): the floor, the nineteen colour roles, and why a role follows the skin where an alias follows the palette. **Arena paints no page of yours** |
| How much air goes between two components, and what column does the page sit in? | the same document: the three named steps as classes and as tokens, the four classes the column is made of, and the cut between air you place and air the kernel answers |
| What does Arena ship at all, and how much of it do I have to take? | [`references/surface.md`](./references/surface.md): every part in one table with the document that owns it, and three steps a project can stop at |
| Where does Arena stop? | the same document's last section, which is a list of decisions rather than gaps waiting to close |
| What is the value of a token? | the DTCG JSON for its group in `contracts/design/` (`ls contracts/design/*.json`), which is the machine-readable form and is cheaper than the specification below. Two files hold what DTCG cannot: `contracts/design/colors.css` and `contracts/design/environment.css`, both of which [`references/page.md`](./references/page.md) reads for you |
| What does a value mean, and why is it that? | [`contracts/design/AGENTS.md`](../../contracts/design/AGENTS.md), the normative design specification |
| What must this kind of component do to be accessible, and what does an Arena one promise? | `contracts/behaviour/<pattern>.json`, one file per pattern and shipped inside your package. The page handing you the markup names the file it binds: [`references/media-register.md`](./references/media-register.md) for a feed, a lightbox or a viewer, [`references/seo.md`](./references/seo.md) for structured data. What one of Arena's own components does is its `.prompt.md`; the file recording which pattern it binds is what Arena is held to, not a document you read |
| How do I install Arena in my app? | [`frameworks/react/PACKAGE.md`](../../frameworks/react/PACKAGE.md) or [`frameworks/angular/PACKAGE.md`](../../frameworks/angular/PACKAGE.md) |
| What does every component look like at once? | `frameworks/react/kitchen-sink/`, and the same page in `frameworks/angular/` |
| What does a token look like on screen? | `intro/guidelines/*.html`, the specimen cards |
| Arena itself is wrong, or one of these pages sent me somewhere empty. Where does that go? | [`CONTRIBUTING.md`](https://github.com/dravensoft-dev/arena/blob/main/CONTRIBUTING.md), which takes an issue and a pull request alike, and says what makes either usable. A question this documentation did not answer is one of them |

**Do not read these to build something.** `contracts/api/AGENTS.md`,
`contracts/behaviour/AGENTS.md`, `frameworks/PACKAGING.md`, and each layer's own `AGENTS.md`
are about *changing* Arena, not about using it. They are large, and none of them answers a
question in the table above.

## Two ways to deliver

**A visual artifact** (a slide, a mock, a throwaway prototype): copy the assets you need out
of `assets/`, and write static HTML that links `intro/styles.css`. That one stylesheet pulls
in every token, so the page is on-brand with no build step. It must be served over HTTP rather
than opened from `file://`.

**Production code**: use the component library for the consumer's framework, import from
`@dravensoft/arena-react` or `@dravensoft/arena-angular`, and follow the prompts. **Put no class
of your own on an Arena component**, and write no rule targeting one. A component renders
`arena-<component>__<slot>` class names, so a rule of yours can reach one by specificity;
nothing stops you and nothing supports you either. The name reads like a BEM surface somebody
meant you to target and it is not one: it is compiler output, no contract names it, and a slot
may be renamed in any release. Content you draw yourself is yours, styled through the same tokens.

**How a screen is composed is yours, and the silence is deliberate, and it is about the shape
rather than about the inventory.** Arena ships the pieces and no shape they must make: a console
and a reading view are different pages before they are different components. Start from what the
application is, and take the pieces from [`references/page.md`](./references/page.md), which is
the inventory half and holds every one of them.

Arena keeps the questions and every answer is a style plugin. The reasoning under the appearance
decision above is
[`contracts/design/StylePlugins.md`](../../contracts/design/StylePlugins.md).

## Ask before you build

**A brief names a product and never a palette, so the questions are always the same ones**, and a
one-line brief is the normal case rather than the empty one. Which ones to ask, in what order, and
what each answer unlocks is the tree named above. **Invoked with no guidance at
all**, ask what the user wants to build and then walk that tree from its first node. Then act as an
expert in the Arena language and produce either an HTML artifact or production code, whichever the
answer calls for.


<!-- skills/design/references/media-register.md -->

# When the markup is yours

Arena's component list is the furniture of an application somebody works in. A photo wall, a story
ring, a feed of posts, a slideshow, a document editor and a game map are outside it, and the router
says so before it says anything else. This page is what that sentence owes you.

**The answer is not that Arena is the wrong choice.** The skin travels either way: a style plugin
answers every role whatever the product is, and one of the products measured on this kernel is a
photo feed. What changes is that you write the markup and Arena hands you the parts, so the
question stops being "which component" and becomes "which of Arena's pieces does this element
need". Read this once, when you have found the first screen with no component under it.

## Read the pattern before you write the markup

An element Arena does not ship still owes a user everything Arena's own components owe them.
`contracts/behaviour/` is where each pattern is stated once, normatively, in a form your own
markup can be held to:

- **`contracts/behaviour/feed.json`** for a scrolling list of posts: the `feed` role, an `article`
  per entry, `aria-posinset` and `aria-setsize` on each, `aria-busy` while a page loads, and the
  keys that move between articles. A feed of your own that binds none of this is a feed only a
  mouse can read.
- **`contracts/behaviour/dialog-modal.json`** for a lightbox or a viewer: `aria-modal`, focus taken
  on open, focus restored to the invoker on close, Tab trapped inside, Escape out.

Read the one your element is, and bind what it requires. These files are the same source Arena's
own components are held to, so what you write is held to the standard the components are.

## One of those two is handed over, and the other is not

**You do not write a focus trap.** The package exports the one Arena's own dialogs run on, and
your layer's `PACKAGE.md` names each: the modal contract, the tone-to-colour map for a status
shape you draw, and the visually-hidden style object for a label the design does not show. Reach
for those rather than writing a second copy, and read that page's export table before you reach
for anything else: what it names is what carries a promise.

**The feed pattern has no such export, and it is not an oversight you can wait out.** Arena binds
it once, inside `ArenaActivityFeed`, and that component is not your feed: it is an event log with
a fixed row and no slot for your markup, so reaching for it because the name matches is the
mistake this section exists to stop. What you can do is read how it binds the pattern, in that
component's source, and write the same thing around your own article: the paging keys move focus
between articles rather than scrolling, which is the part a reimplementation from memory gets
wrong. Until an export exists, that reading is the handover.

**`isArenaOwnActivation(target, container)`** is the one to know about by name. A post that opens
on tap and carries a like button inside it is two activations on one surface, and that predicate
is how the outer one keeps its hands off the inner. It is the same rule Arena's own clickable rows
run on.

## The stylesheets are for content you draw

The package ships more than the components' own CSS, and these four are the ones written for
markup that is not a component: `css/rhythm.css` for the vertical stack between your elements,
`css/page.css` for the column the page sits in, `css/numerals.css` for a figure that must not
jitter as it counts, and `css/sr-only.css` for the label a screen reader needs and the design does
not show. Your layer's `PACKAGE.md` has the whole tree and says which depth to pick.

**The frame around a picture is a component, and the grid around the frames usually is not.**
`ArenaFigure` is the cell: its `ratio` defaults to the `aspect-media` role and its overlay slot
paints `overlay-media`, so the two roles below are answered for every picture at once and a wall
reads as a wall rather than as whatever sizes the images happened to be. Use it for a post's image
and for a wall's cell alike.

The grid holding them is the split. `ArenaGrid` auto-fits off the `grid-min` role, which is what
you want when the count is the data's and the plugin decides how dense it looks. A wall that is
**three across because the design says three** is `grid-template-columns: repeat(3, 1fr)` on an
element of your own, one line, and `ArenaGrid`'s own Don't says so: two products measured wanting
a fixed count wrote exactly that line rather than bending a component into it.

## Four roles decide how your media looks

The kernel's role list is where a project answers what Arena looks like, and four of its roles are
about exactly this register rather than about the furniture: `aspect-media`, `fit-media`,
`r-media` and `overlay-media`. Their descriptions in `contracts/design/roles.json` are written
about galleries and shops. If your product is media, those four are not a detail of your style
plugin, they are most of what a viewer will notice, so answer them first and look at the result
before you answer anything else.

`r-media` is also where the boundary is stated in the kernel's own words: a card is a container
the reader looks past, and a figure is the thing being looked at. If your post is the thing being
looked at, it is not a card.

**Two component names will look like your answer and are not.** `ArenaActivityFeed` is an event
log with a fixed row, and `ArenaCard` is the container above. Both are the first thing a search
for your screen returns, and reaching for either is how a product in this register ends up fighting
a component instead of writing six lines.

## The viewer that opens a picture at full size

Arena ships no lightbox, and this is the element of your own that comes up most often. Every value
it needs is already a token, so the only thing you are inventing is the box:

- **The box needs no length of its own, and the one people write is the tell.** As tall as the
  viewport allows is not a token and is not a percentage of one: it is `position: fixed` with
  `inset: 0` on the layer and `max-width: 100%` with `max-height: 100%` on the picture, and the
  layer's own padding is where `--pad-safe-*` and a step of the spacing scale go. A chosen `90vh`
  is the shape this goes wrong in, and it is usually compensating for the second mistake rather
  than for a design: `vh` is the viewport a phone has with its browser chrome retracted, so a
  picture sized in it is taller than the room it has while the chrome is showing. `dvh` is the
  unit that follows the chrome, which is why `.arena-shell` fills the window with `100dvh`, and
  a fixed layer at `inset: 0` needs neither. There is no role here because there is no decision
  here: how tall a full-size picture may get is the viewport's answer and not a style plugin's.
- **The dim is `--scrim` with `blur(var(--scrim-blur))`**, which is the pair Arena's own dialogs
  dim the page with, and the layer is `--z-modal`. A scrim of your own is the one value that makes
  a viewer look like a different product from the dialogs beside it.
- **`object-fit: contain`, not `cover`.** Edge to edge and never cropped pull against each other on
  any viewport whose shape differs from the picture's, and a capture that lost a corner to its
  frame is one somebody has to go and find the original of. What is left over on the short axis is
  the dimmed page rather than a mat you designed.
- **The way out is a control you draw, and `--overlay-media` is what it stands on.** That role is
  the wash a frame draws under anything laid over a picture, and a close control laid over one is
  that case even with no `ArenaFigure` in sight: the picture underneath is one nobody chose, so a
  control tinted by the palette alone is legible over some of them and invisible over the rest.
- **`--pad-safe-top` and `--pad-safe-right`** hold that control off a phone's cutout, composed with
  a step of the spacing scale.
- **Bind `contracts/behaviour/dialog-modal.json`** and take the focus trap your layer exports
  rather than writing one. A viewer with no name, no Tab trap or no focus restored to the control
  that opened it is the same defect in your markup that the contract exists to stop in Arena's.

## One rule bends here, and only one

**One primary accent per view** is written for a screen. A feed is not a screen in that sense: a
follow action on each of twenty posts is not twenty primary accents, it is one repeated element,
and the rule is about the eye having one place to land rather than about a count of buttons. Give
the repeated action a secondary or a ghost weight and keep the single primary for what the screen
as a whole is for. Nothing checks this either way, so it is yours to hold.

Every other rule the router states holds unchanged, and two of them get harder rather than easier
in this register: no gradients on a surface, and a chart carries identity or meaning and never
both. A media product is where both are most tempting.

## What Arena still gives you

**The screen you are writing is mostly components with one element of your own in the middle.**
The banner, the navigation, the states around empty and failed, every field and every button are
furniture whatever the product is, and reaching for them is what keeps a product built this way
from reading as two. Your layer's `INDEX.md` is the directory; work out from your own element
rather than in from a page layout.


<!-- skills/design/references/cold-start.md -->

# Before the first screen

This page is where a project settles what it looks like, and its first node splits the two ways of
arriving: a project with no `arena.config.json`, no style plugin and no screens, where the
appearance is invented by whoever writes the first file, and one already carrying all three, where
it is context to acquire rather than to invent. **Read this before any other page this branch
routes you to**, because every one of them assumes the decisions below have been made.

**It is a tree rather than a list.** Each node asks one question, and the table under it says where
each answer goes. Take the row your answer matches, go to the node it names, and read nothing else:
a node you did not reach holds a decision that is not yours to make yet, and reading it early is how
an agent answers a question nobody asked.

**Two rules hold at every node.** Write no file before the node that writes one. And where a row
costs something, say that cost to the user in their own words and get an explicit yes before going
on, because the cost is the concrete way that answer goes wrong and a warning nobody answered is a
decision the agent made alone.

## 1. Does the project already carry Arena?

| The answer | Go to |
|---|---|
| Yes, it has an `arena.config.json` and screens built on it | 7 |
| No, or it has the package installed and nothing written against it | 2 |

## 2. Where does the appearance come from?

| The answer | Go to | What it costs you |
|---|---|---|
| A document stating the palette, the type and the roles | 5 | nothing, and this is the case the rest of this page exists to reach |
| A public URL to copy | 3, then 5 | every role that lives behind a state, and probably the register |
| A screenshot | 3, then 5 | every role outside the one polarity, density and state it caught |
| One of the registers Arena measured, picked rather than invented | 4 | the palette is still yours to state, and nothing else about the product is settled |
| Nothing yet | 3 | the whole interview, which is the honest price |

**A public site hides its own states.** Hover, focus, disabled, error, empty and loading are behind
interactions a reading never performs, so every role about a state is guessed rather than read. A
marketing page is also a different register from the product behind the login, and copying the first
gives the second a skin it was never designed to wear.

**A screenshot is one polarity, one density, one breakpoint and one state.** Worse, a colour read off
a pixel is the composite of a surface, an opacity level and whatever was laid over it, so it enters
the palette as a literal that no theme can move, and the second polarity inherits it and is wrong.

Neither is a reason to stop. They are reasons to run node 3 first and to show the user what you
concluded before you build on it.

## 3. The minimum interview

Five questions, and they cover the decisions
[`style-kernel.md`](./style-kernel.md) measured as the ones that separate one product from another.
Ask them one at a time. Which colour the TEXT takes is not among them, because eight unrelated
products answered that identically; which surface the page takes is settled by the first question
rather than by a sixth of its own, because it follows from what the screen is. That page's own table
is where both are.

| Ask | What the answer fixes |
|---|---|
| What is being built, and who works in it | the register, whether Arena's component list is the right one, and `aspect-media` and `fit-media` |
| Whose brand is this, which polarity leads, and which colour is the voice | the palettes in `arena.config.json`, both of them |
| Which three faces: display, body, mono | `ff-heading`, `ff-body`, `ff-mono` |
| What character does it have to the eye: soft, drawn, or flat | `r-*`, `bw-*`, `fw-*`, `tt-*` and `track-*`, `shadow-*`, `press-scale` and `lift-control` |
| How dense is it, and how wide does it breathe | `pad-control-*` and `gap-*`, `container-max`, `measure-prose`, `grid-min`, `gutter` |

The fourth is one question rather than four because those roles move together. A product is soft, or
drawn, or flat, and a plugin that rounds the corners while keeping the hard border and the deep
shadow reads as two products sharing a screen.

| The answer | Go to |
|---|---|
| The user answers them | 5 |
| The user will not answer them | 4 |

## 4. Start from a register Arena measured

**Two arrivals reach this node**, one that would rather pick than answer and one that will not
answer at all, and it is a real answer to both. Ask for one thing only: a short description of
the app. Then match that description against the catalogue in `plugin-style-store/catalogue/`,
where each directory is a register measured on a real product and carrying its own `ENTRY.md`.

**Match on one line rather than on the entries themselves.** Every `ENTRY.md` carries a line
beginning `Take this entry when`, which says what that register is for in the terms a description
arrives in. Read those lines, pick the one the description fits, and only then open that entry. Read
it, do not remember it.

**Name the entry you picked and what it decides, and wait.** Say which register it is, what it
answered for shape, air and depth, and what it leaves open. An entry chosen silently is the same
failure as a screenshot read silently, with a better result and the same missing consent.

**An entry is copied rather than cited.** Its `plugin.tokens.json` and its `plugin.css` become
your project's own under `design/<name>/`, and node 10 is where they land.

**The catalogue is in the Arena repository rather than in the package.** From an installed project,
read it there.

| The answer | Go to | What it costs you |
|---|---|---|
| The user confirms an entry | 5 | the palette is still theirs to replace, and nothing else is settled |
| Nothing in the catalogue is close | 5 | the appearance Arena installs with, which every project on that step shares |

## 5. Write the identity document, and stop

Whatever route reached this node, the output is the same: a page stating the palette in both
polarities, the three faces, the character, the air, the media shape and the page shape, with the
reason beside each. `arena-from-scratch/identity.html` in the Arena repository is the template, and
`arena-from-scratch/identity.example.html` beside it is one worked answer to read first.

It is a page rather than a list because a palette described in prose is a palette nobody can
approve. Serve it over HTTP, show it to the user, and change what they change.

**Then stop.** The next node writes files, and files written against an unapproved appearance are
the ones that get rewritten.

| The answer | Go to |
|---|---|
| The user approves the document | 6 |
| The user changes something | 5, again, until they stop |

## 6. The four decisions a project makes once

Each is settled before the first screen and never per screen. They are in this order because each
one asks about something the next one assumes.

| Ask | Read | Skip it when |
|---|---|---|
| What does Arena ship, and how much of it am I taking | [`surface.md`](./surface.md) | never, because the three below ask how much of a thing you have not been shown |
| Is Arena's component list right for this product | [`media-register.md`](./media-register.md) | the register is an application somebody works in and nothing on screen is a wall, a feed, a viewer or a document |
| How does it answer the kernel's roles | [`style-kernel.md`](./style-kernel.md) | node 7 found a plugin that already answers every role |
| Does anybody outside it have to find it | [`seo.md`](./seo.md) | never, because a no that was never chosen is announced by nothing and reaches the install rather than a screen |

Then go to 8, because the last of those four is a yes or a no and the next node is how much.

## 7. Read what is already there

An identity somebody already established is context to acquire, not a step to skip. Before adding
anything:

- Read `arena.config.json`: which palettes, which polarity leads, which fonts, and which plugin is
  named first, since that one is the root and answers every role.
- Read the project's own `plugin.tokens.json`: which roles it answers and with what. A role it does
  not answer is a property that disappears rather than a plainer look.
- Read its `plugin.css`, if it has one, to see which decisions the project paints by hand. Those
  are the ones no role reaches, and they are the ones your new screen has to keep.
- Run `arena-to-prod --audit` and report what it names before you write anything. It reads the
  project's own sources and its declared plugin directories for the rules source text can show.

Say what you found. A project whose plugin answers every role needs no style plugin work, and
saying so is what stops an agent rewriting an appearance somebody already chose.

Then go to 6, and skip the rows it says you may skip. **Stop there rather than going on to 8**,
because the nodes past it decide an install a project carrying Arena has already made: the route
from here is the per-screen one in [`../SKILL.md`](../SKILL.md). Reach 8 only when this screen is
the first that has to be found from outside the product.

## 8. How much does it have to be found?

Node 6 answered whether anybody outside the product has to arrive at it. This asks how much, and it
is a separate question because the answer decides a layer and a peer dependency rather than a
screen. **Both layers draw the same components; only one of them writes the document `<head>`.**

| The answer | Go to | What it takes |
|---|---|---|
| Nothing. It is behind a login, or it is a console | 9 | neither layer, and no metadata anything. This is the honest answer for most tools |
| A title and a description per route | 9 | either layer. Angular has it in the package; React carries it through whatever its own framework offers |
| Everything: canonical, `og:*`, a default that keeps a route out of an index until it says otherwise | 9 | on Angular, `@dravensoft/arena-angular/metadata`, where `@angular/router` stops being optional; on React, your own framework's head, since Arena writes none there |

**The third row is a decision about the framework, and it is worth making while it is still cheap.**
`@dravensoft/arena-react` writes no `<head>` at all, by design, so a React project answering that
way carries the whole of it itself. The Angular entry point is a second one, apart from the one
components come from, and reaching it is what pulls the router in: it is declared an optional peer
for exactly this reason, so a project that never reaches for metadata never installs a router it
does not use.

[`seo.md`](./seo.md) is where the three properties behind that third row are written down, and
node 6 sends every project there whatever it answered here. That is not a contradiction with this
node: a no reached by choosing is a decision the project can defend later, and a no reached by
never asking is announced by nothing. Read it on the third row to learn what you are taking on,
and on the first to learn what you are declining.

## 9. What is it built on?

**Arena takes no position on how an application is assembled**, which is a real property rather than
a slogan: its React layer imports `react`, `react-dom` and its own two bundled styling utilities and
nothing else, and neither layer ships a router, a store or an application shell. What follows is
what that buys per architecture, and where it stops.

| The answer | Go to | What is true, and what you carry |
|---|---|---|
| A single-page application | 10 | the ordinary case, and everything below is a variation on it |
| Server rendering with hydration | 10 | supported. React's own suites server-render, and neither layer reads a browser global at module scope |
| Static generation or prerender | 10 | the components take the same path they take under server rendering. Arena ships no prerender tooling, so producing the pages is your framework's job |
| React Server Components | 10 | **Arena ships no `use client` directive**, so the boundary is yours to draw, and it is one line |
| A microfrontend inside a host | 10 | the components are safe; the stylesheet is document-wide. Read the paragraph below before choosing this |

**Server rendering is the claim with the most evidence behind it.** Much of the React suite renders
through `react-dom/server` on every run, so the layer is exercised rather than merely believed:
there is no `useLayoutEffect` anywhere in it, and the only module-scope touch of `document` is
behind a `typeof document === 'undefined'` guard. Angular reaches the document through the injected
token rather than the global, and its two measurements run after render, which is the same
property arrived at by a different route. One honest asymmetry: React's server rendering is held by
a suite and Angular's is held by its code, so the second is the one to smoke-test first in a project
that depends on it.

**One hydration behaviour to know**, since nothing reports it: the viewport measurement answers
false on a server, so a component branching on it renders its wide branch into the HTML and corrects
after hydration. Branch on a container rather than the viewport where the difference would be seen.

**React Server Components need one line from you.** Arena's components use hooks, and no file in the
package carries `'use client'`, so importing one directly into a server component fails. Put the
directive at the top of your own module that imports Arena and the boundary is drawn where you
meant it, which is better than the package drawing it for you at every leaf.

**A microfrontend is the one where the answer is split.** The JavaScript is genuinely
architecture-neutral. The stylesheet is not: the tokens are declared on `:root`, and the reset sets
the box model on `*` and a line height on `html`, so loading Arena inside a host page changes that
page and not only your subtree. Two different Arena versions on one document collide on `:root`, and
the last stylesheet loaded wins. What does work in your favour is that a palette other than the
default emits as a plain class, so your own subtree can carry its own theme without touching the
host. Take this row knowing the host is being changed, or give the fragment a document of its own.

## 10. Now write it

**What the answers made necessary.** Nothing here is a preference, and no further question about
dependencies is the skill's to ask: past this table the stack is the project's own.

| Always | Which layer | Why |
|---|---|---|
| `@dravensoft/arena-react` **or** `@dravensoft/arena-angular` | one of them, never both | the layer nodes 8 and 9 settled. This is Arena itself; everything under it is a peer, and a list of peers with the package missing installs nothing that draws |
| `@phosphor-icons/web` | both | icons are class-name strings a component renders, and the font is never bundled |
| `@angular/cdk` | Angular only | a peer of that layer, and **not** something a React project installs |
| `@angular/core`, `@angular/common`, `@angular/platform-browser` | Angular only | the peers the layer is built on |
| `react`, `react-dom` | React only | the peers that layer is built on |

| Added by an answer | When | From which node |
|---|---|---|
| `@angular/router` | the third row of node 8, on Angular | it is an optional peer until the metadata entry point is reached, and reaching it makes it required |

**Any of npm, bun or pnpm installs this.** The packages declare their peers rather than assuming a
flat tree, and pnpm's strict layout is the one worth naming because it is the one that would break a
package that assumed otherwise: installed under it, the command below resolves the icon font through
the symlinked store and writes both stylesheets. Nothing here needs a hoisting flag.

Then, in this order, because each file is read by the next.

- `arena.config.json`, with both palettes, the three font slots, and `stylePlugins` naming the
  directory the next two bullets write, as `["./design/<name>"]`. **A plugin the config never
  names is a plugin nothing loads**, and nothing reports it: the build succeeds and the product
  wears the answers Arena installs with, which are Dravensoft's. `["default"]`, or leaving the
  key out, is that same appearance chosen on purpose rather than by omission, and it is a
  finished answer for a first screen or a tool nobody outside the team looks at.
- `design/<name>/plugin.tokens.json`, answering every role. Shapes first, then space, then weight,
  then depth, and leave the colour roles at the answers
  [`style-kernel.md`](./style-kernel.md) reports eight products converged on.
- `design/<name>/plugin.css`, only for a decision no role reaches.
- Run `arena-to-prod`, which writes the stylesheet no package can carry and subsets the icon font
  to the glyphs your screens draw. Import what it wrote.
- Then the first screen, through the per-screen route in [`../SKILL.md`](../SKILL.md).

The identity document from node 5 is what each of these is checked against, and it stays in the
project: the next agent to open it starts at node 2 with the good answer instead of at node 3.


<!-- skills/design/references/stack.md -->

# What you may choose

**Arena is built with bun, React 18, Angular 22 and TypeScript. None of that is a requirement on
you**, and this page exists because the two are easy to read as one thing. What a design system is
built with leaks into its documentation as a default nobody chose, and an agent that inherits it
picks a toolchain for the wrong reason: not because the product needs it, but because the sample
command happened to be written that way.

So this page is the repertoire. Every axis a project settles before its first screen, every answer
Arena supports on that axis, and **how much evidence each answer actually has**. Read this once per
project, beside [`cold-start.md`](./cold-start.md) and before the first screen, and choose each axis
on what the product needs rather than on what Arena happens to be made of.

## The evidence column, and why it is there

A yes with nothing behind it is worth less than an honest maybe, so no row here says yes. Each one
says how it is known.

| Evidence | What it means |
|---|---|
| held by a gate | proved on every run of Arena's own board. If it broke, a build here would fail before a release went out |
| exercised by Arena's own suites | the code path runs here, repeatedly, against this version |
| verified by hand once | somebody installed it that way and it worked. Nothing revalidates it, so it is a record rather than a guarantee |
| allowed by the manifest, not exercised | the declared range resolves it and nothing is known against it. Nobody has run it |
| does not work | with the reason, so you can plan around it instead of discovering it |

**A row is never promoted without being exercised.** "Allowed by the manifest, not exercised" is a
finished answer, and reading it as a soft yes is the mistake this column exists to prevent. If you
need one of those rows to be certain, run it early and small rather than late and whole.

## The repertoire

<!-- @support matrix GENERATED by bun run generate:support. Edit that script, not this copy. -->

**Which package manager installs this?**

| You may choose | Evidence | What is true |
|---|---|---|
| npm | verified by hand once | the packages declare their peers rather than assuming a flat tree, so no hoisting flag is needed |
| pnpm | verified by hand once | the strict layout is the one worth naming, because it is the one that would break a package assuming otherwise: installed under it, the command still resolves the icon font through the symlinked store |
| bun | verified by hand once | the same install. Bun is also what Arena is built with, which is a fact about Arena rather than a requirement on you |
| yarn | allowed by the manifest, not exercised | nothing here works against it: the peers are declared, there is no install script to trust, and no flat tree is assumed. Nobody has run it, which is why it says allowed rather than yes |

**What runs the command?**

| You may choose | Evidence | What is true |
|---|---|---|
| Node >=22 | held by a gate | the command is a Node program, and that floor is the oldest line Node still supports rather than a capability the command needs |
| any runner that reaches a Node program | allowed by the manifest, not exercised | npx and bunx both reach the same file. No runner is required: the command imports three node modules and no runtime API of its own |

**How is the package loaded?**

| You may choose | Evidence | What is true |
|---|---|---|
| an ES module import | held by a gate | the package is a module, and every target its exports name resolves to a file that is there |
| a CommonJS require | does not work | there is no require condition and no second build. A project that cannot load a module cannot load this one, and it fails at the first import rather than somewhere later |

**How does the stylesheet reach the page?**

| You may choose | Evidence | What is true |
|---|---|---|
| an import from a module of yours | verified by hand once | the idiom this page shows. It is an instruction to a bundler rather than to TypeScript, which is why a project may need a declaration before it typechecks |
| an @import from a stylesheet of yours | allowed by the manifest, not exercised | what the package hands you is a barrel of relative imports, so whatever resolves those resolves all of it |
| the global styles list a framework CLI takes | allowed by the manifest, not exercised | the same file named as a global style rather than imported from a module, which is how a CLI-driven workspace usually takes one |
| a link element | allowed by the manifest, not exercised | this one needs the package directory served as it stands, because the barrel reaches its parts by relative path |

**What assembles it?**

| You may choose | Evidence | What is true |
|---|---|---|
| any bundler that resolves exports and imports CSS | allowed by the manifest, not exercised | nothing in the package is written for one: no raw-text import, no build-time environment global, and nothing compiled at install time |
| a framework CLI | allowed by the manifest, not exercised | where a layer ships in the package format its framework defines, partially compiled, the consumer build finishes it the way it finishes any library it depends on |
| no bundler at all | allowed by the manifest, not exercised | the stylesheets are compiled already and the components are plain modules, so what a project needs is something that resolves a module specifier |

**Which layer, and which version of it?**

| You may choose | Evidence | What is true |
|---|---|---|
| React 18 | exercised by Arena's own suites | the version Arena builds and renders against on every run, server rendering included |
| React 19 | allowed by the manifest, not exercised | inside the range the package declares, and not exercised here. Nothing is known against it |
| Angular 22 | exercised by Arena's own suites | the version the layer is compiled and tested against, shipped partially compiled so your own build finishes it |
| Angular 20 or 21 | allowed by the manifest, not exercised | at or above the floor the package declares, and not exercised here |
| neither layer | allowed by the manifest, not exercised | the tokens, the stylesheets for markup of your own, the behaviour contracts and the command are framework-neutral. What you do not get is a component, so every element is yours to write and yours to hold to a pattern |

<!-- @support matrix end -->

## What each layer requires

Peer dependencies are declared rather than bundled, so your project installs them and your project
decides their versions inside the ranges below. **A list of peers with the Arena package missing
installs nothing that draws**, and an Arena package with a peer missing fails at the first import.

<!-- @support peers GENERATED by bun run generate:support. Edit that script, not this copy. -->

| Package | Peer | Range | Required |
|---|---|---|---|
| `@dravensoft/arena-react` | `react` | `^18 \|\| ^19` | always |
| `@dravensoft/arena-react` | `react-dom` | `^18 \|\| ^19` | always |
| `@dravensoft/arena-react` | `@phosphor-icons/web` | `^2.1.2` | always |
| `@dravensoft/arena-angular` | `@angular/core` | `>=20` | always |
| `@dravensoft/arena-angular` | `@angular/common` | `>=20` | always |
| `@dravensoft/arena-angular` | `@angular/platform-browser` | `>=20` | always |
| `@dravensoft/arena-angular` | `@angular/cdk` | `>=20` | always |
| `@dravensoft/arena-angular` | `@angular/router` | `>=20` | until you reach what needs it |
| `@dravensoft/arena-angular` | `@phosphor-icons/web` | `^2.1.2` | always |

<!-- @support peers end -->

Two of those rows carry more than a number.

**The icon font is a peer in both layers.** Icons are Phosphor class-name strings a component
renders, and no package bundles the font, so a project that skips this peer renders components with
empty squares where the icons go and nothing reports it.

**One peer is conditional.** The router is required only once a project reaches the entry point that
writes the document head, which is why it is declared optional: a project that never reaches for
metadata never installs a router it does not use. [`seo.md`](./seo.md) is where that decision is
made, and node 8 of [`cold-start.md`](./cold-start.md) is where it is reached.

## What this page does not decide

**Which layer you take, and how the application is assembled.** Those are questions with their own
nodes, and duplicating them here would give a project two places to answer one thing. Node 8 of
[`cold-start.md`](./cold-start.md) decides the layer, because how much of the product has to be
found from outside it is what settles both the layer and one peer. Node 9 of the same tree answers
the render architecture, a single-page application, server rendering with hydration, static
generation, server components or a microfrontend, with what is true of each and what you carry.

**How much of Arena you take.** [`surface.md`](./surface.md) is the whole offer in one table, with
three steps a project may stop at and the line where Arena stops on purpose.

**What your product looks like.** Nothing on this page touches appearance.
[`style-kernel.md`](./style-kernel.md) is that decision, and it is independent of every axis here:
the same style plugin travels whatever installs it and whatever assembles it.

## Where the repertoire stops

- **No matrix is installed on every run.** The package-manager and bundler rows are claims about
  somebody else's tool, and nothing here revalidates them per release. That is why they carry the
  evidence they carry rather than a stronger word.
- **No version is pinned upward for you.** The React range is closed at the majors that have been
  rendered, because an open range would promise a major nobody has seen. The Angular floor is open
  above it, so a version past the exercised one resolves and is untested: that is a permission, not
  a promise.
- **No project of yours is read.** No gate here opens your application, so every rule of the
  language holds because you hold it. The closest thing is the command's own audit, which reads your
  source text for the five rules source text can show and reports rather than fails unless you ask
  it to.


<!-- skills/design/references/style-kernel.md -->

# Making Arena look like your product

Arena keeps the questions and a repertoire of values. **Every answer is a style plugin**, and the
appearance Arena installs with is one of them, so replacing it is the ordinary case rather than an
escape hatch.

**Eight registers are already measured, and picking one is a way to answer this page rather than
a way around it.** `plugin-style-store/catalogue/` holds a directory each, and the fourth node
of [`cold-start.md`](./cold-start.md) is where a product is matched against them.

Read this once per project, before the first screen. The rules of the language are in
[`../SKILL.md`](../SKILL.md) and hold whatever your appearance is.

## The three files you write

**`arena.config.json`, in your project root.** The palettes, the fonts and the plugins, and
nothing about components. **The shape, abridged, and not a file to copy**: every palette answers
the whole colour set rather than the three shown, and a config carrying three keys is refused
rather than defaulted.

```json
{
  "stylePlugins": ["./design/notion"],
  "palettes": [
    { "name": "light", "default": true, "polarity": "light",
      "colors": { "base-100": "#ffffff", "base-content": "#37352f", "primary": "#0b6bcb" } }
  ],
  "fonts": { "display": { "family": "Inter", "src": "..." } }
}
```

**`"stylePlugins": ["default"]` is a legitimate answer**, and it is the right one for a first
screen or a tool nobody outside the team will look at: it keeps the appearance Arena installs
with, and a project moves off it when the appearance starts mattering rather than before. What
this page costs you is paid when you decide to look like yourself, not to start.

Arena ships two themes and is dark first, so a real config carries a dark palette as well as the
light one above. The full colour list, the font slots and the rest of the config are on your
package's own page, and the file to copy is there rather than here: [`../../../frameworks/react/PACKAGE.md`](../../../frameworks/react/PACKAGE.md)
or [`../../../frameworks/angular/PACKAGE.md`](../../../frameworks/angular/PACKAGE.md).

**`design/<name>/plugin.tokens.json`.** One entry per role, and the directory name becomes the
plugin's name:

```json
{
  "r-surface":   { "$type": "dimension",  "$value": "{r.xs}" },
  "fw-heading":  { "$type": "fontWeight", "$value": "{fw.bold}" },
  "fill-field":  { "$type": "color",      "$value": "{color.base-200}" },
  "press-scale": { "$type": "number",     "$value": 0.98 },
  "container-max": { "$type": "dimension", "$value": { "value": 920, "unit": "px" } }
}
```

**`design/<name>/plugin.css`, optional.** CSS of your own, selecting the part hooks:

```css
[data-arena-part="side-nav.item"] {
  color: color-mix(in oklab, var(--color-base-content) 82%, transparent);
  font-weight: var(--fw-control);
}
```

The eight products measured for this document write between two and sixteen such rules each. If
yours is running to hundreds, the answer is almost always a role you have not moved.

## The two rules that decide everything else

**The first entry in `stylePlugins` is the root plugin, and it answers every role.** It emits on
`:root`, and a custom property with no value is invalid at computed-value time: the declaration
reading it is dropped and the property disappears. A partial root plugin is not a plainer
appearance, it is a page with no borders. Every later entry emits under `.arena-<name>`, taken from
its directory, and is a difference sitting over the root plugin, so it answers only what it changes.

**A colour role takes one of your palette colours as a `{color.*}` alias, and never a literal.**
The palette is yours and what a role says is WHICH of your colours a surface takes. It is
mechanical as well: a bare colour alias is restated under every palette, and anything else resolves
to one theme's value and inherits it into the other, so a hex here is a light-mode colour showing
through your dark theme.

## What an answer may be

- **A scale alias**, `{r.xs}`, `{sp.4}`, `{fw.bold}`, `{dur.fast}`, `{ease.out}`. This is the
  ordinary answer.
- **A `{color.*}` alias**, for every colour role.
- **A literal**, where the scale has nothing you want: `{ "value": 920, "unit": "px" }`, or a bare
  number for a ratio such as `press-scale`. **Two of the loudest decisions need one**, because the
  scale has no step for them: a square corner is `{ "value": 0, "unit": "px" }`, and no shadow at
  all is a shadow object whose every length is zero and whose colour is fully transparent.
- **A unit the type does not carry**, through `$extensions`. Four roles need it and the rest do
  not: `track-heading`, `track-eyebrow` and `track-label` take `em`, and `measure-prose` takes
  `ch`. A tracking role that forgets it emits a bare number, which is not a valid letter spacing,
  and the declaration silently resolves to `normal`.
  ```json
  "measure-prose": { "$type": "number", "$value": 86,
    "$extensions": { "com.dravensoft.arena": { "cssUnit": "ch" } } }
  ```

**The type of a role does not tell you which scale its answer comes from**, so here is the map. A
`dimension` role draws from four different places depending on what it is for:

| Roles | Scale | Where the steps are |
|---|---|---|
| `r-*` | `r` | [`effects.json`](../../../contracts/design/effects.json) |
| `bw-*` | `bw` and `bw-strong`, a pair rather than a ladder, so the alias carries no step | the same |
| `shadow-*` | `shadow` | the same |
| `dur-*`, `ease-*` | `dur`, `ease` | the same |
| `pad-*`, `gap-*`, `gutter` | `sp` | [`spacing.json`](../../../contracts/design/spacing.json) |
| `step-eyebrow`, `step-label` | `dz` | the same |
| `fw-*` | `fw` | [`typography.json`](../../../contracts/design/typography.json) |
| `ff-*` | `font`, which resolves to the families your config declares | the same |
| `track-*` | `ls` | the same |
| `lh-*` | `lh` | the same |
| `step-title-*` | `fs` | the same |
| `container-max`, `grid-min`, `measure-prose`, `lift-control`, `press-scale`, `aspect-media` | none | a literal is the only answer |

[`Scales.md`](../../../contracts/design/Scales.md) beside them is the reasoning for the ladders
that have one, which is not all of them.

**What an answer may never be is a scale itself.** A scale step is shared by every use that wants
that value, so moving one is not a style plugin but a different Arena. **The type and page-rhythm
ladders are the one exception**, because they reach a page through classes you apply rather than
through any role, and you answer them in the plugin beside the roles: a key named `fs-<step>` or
`rhythm-<step>` is read as that step rather than as a role nothing ships. Both are dimensions and
both carry a `$description`, because a step a plugin moves is a decision rather than a value. Move
one step or every one of them, as the product needs: completeness binds a role, which disappears
unanswered, and never a step, which keeps the value Arena ships. Every other scale key is refused
by name, so a different type scale is answered here or it is not answered.

The questions themselves are in
[`../../../contracts/design/roles.json`](../../../contracts/design/roles.json): a name, a type, a
description and, for a keyword role, its closed set. No values, because the values are yours.

## Where the appearance actually comes from

Eight unrelated products were built on this kernel, one each in the register of a project tracker,
a language course, a photo feed, a document workspace, a storefront, an inbox, an observability
console and a booking flow. **Every one of them answered these identically**, and a plugin that
spends its first day on them spends it on nothing:

| Answered the same way by all eight | What they said |
|---|---|
| `ink-heading`, `ink-body`, `ink-muted` | `{color.base-content}` |
| `ink-eyebrow` | `{color.neutral-content}` |
| `edge-surface`, `edge-surface-floating`, `edge-control-quiet`, `edge-separator` | `{color.base-300}` |
| `ff-heading` | the display face the config declares |
| `lh-heading`, `dur-hover`, `ease-hover` | one step each, the same one every time |

**Which colour the text takes is a constant, and which colour a surface takes is not.** The ink
roles and the four quiet edges are what eight brands converged on, and starting from them costs
nothing. The fills are the opposite, and it took the wider catalogue to show it: a console puts its
panels on the second surface step and its page on the first, a booking page does the reverse, and
the other six leave both at the page colour. **That answer follows from the page shape rather than
from the palette**, so settle what the screen is before assigning any of it.


Those are not the answers the appearance Arena installs with gives. That one is a design of its
own and assigns several of these differently, so it is a plugin to read rather than a baseline to
inherit: a plugin you write answers every role itself, and nothing is inherited from it.
It is [`plugin-style-store/default/plugin.tokens.json`](../../../plugin-style-store/default/plugin.tokens.json)
in the Arena repository, and
[`plugin-style-store/complete/`](../../../plugin-style-store/complete/plugin.tokens.json) beside
it is a second one answering the same roles differently. Read one of them before writing yours:
answering every role from a list of role names is the hardest instruction on this page, and a
worked answer is worth more than the list. **Both are in the repository rather than in the
package**, so from an installed project read them on the Arena repository, or start from
`"stylePlugins": ["default"]` and replace one role at a time against something that already runs.

**These are where a product lives**, and the eight measured products disagree on every one of
them:

| Role | What moving it decides |
|---|---|
| `r-control`, `r-field`, `r-media` | how round the product is, which is the loudest single decision |
| `bw-surface`, `bw-control`, `bw-field`, `bw-separator`, `bw-marker` | whether an edge is a hairline, a drawn line, or absent |
| `fw-heading`, `fw-eyebrow`, `fw-control` | how loud type is before any size changes |
| `tt-label`, `tt-eyebrow`, `track-label`, `track-eyebrow` | whether small text shouts in capitals or reads as a word |
| `pad-control-x`, `pad-control-y`, `gap-inline`, `gap-items`, `gap-control` | how tight the product is to the hand |
| `container-max`, `measure-prose`, `grid-min`, `gutter` | how wide it breathes, and it ranges from a dense console to a reading column |
| `shadow-surface-rest`, `shadow-surface-floating`, `shadow-surface-deep`, `shadow-control-raised` | whether depth is a soft blur, a hard offset or nothing at all, and whether a surface has any at rest |
| `press-scale`, `lift-control`, `dur-state`, `ease-state` | how the product answers a hand |
| `aspect-media`, `fit-media` | what shape an image is, before any of it is cropped |
| `fill-page`, `fill-surface`, `fill-surface-sunken`, `fill-field` | which surface is the page and which is the thing standing on it |
| `edge-control`, `edge-field`, `edge-marker` | whether a control, a field and a marker are outlined at all, and in what |
| `ff-eyebrow`, `ff-label` | whether small text is the body face or the mono one, which is the difference between a shopfront and a console |

**So the order of work is: shapes, then space, then weight, then depth.** Leave the colour roles
where they are until those read as your product, because a plugin that starts by reassigning
colours changes the least and costs the most to undo.

## The part hooks

Every element drawing a slot carries `data-arena-part="<component>.<slot>"`, and that is what your
`plugin.css` selects. **The hook is an attribute on the element, so the page you are looking at is
the list**: serve the application, inspect the element you want to paint, and take the value.
Nothing enumerates the hooks in prose, and a name guessed from a component's member list is a
selector that matches nothing and reports nothing.

**You never write `@layer`**: the build wraps your sheet in a reserved layer
declared after the compiled component rules, so an ordinary selector wins with no `!important`
anywhere, and the sheet restates the layer order at its own head so a bundler cannot reorder it
into losing every contest silently.

Your application's own unlayered CSS still beats the plugin layer, and that order is right: your
application is the last word. It is also why reaching into an Arena slot from application CSS is
reported. It works, and working is what makes it debt rather than an error.

## Gotchas

Each of these was measured on a product, not reasoned about.

- **A rule that restates what the slot already paints changes no pixel.** It also inflates the
  count of parts your plugins paint, which is the number a request for a new role is argued from.
  The report names a restatement.
- **Arena's own colour aliases are a step of Arena's ramp under another name.** A rule reading
  `var(--mute)` assigns a colour without answering any role, and the raw-colour rule stays quiet
  because an alias is a token. Answer the role instead, or compose the shade out of your own
  palette: `color-mix(in oklab, var(--color-base-content) 62%, transparent)`.
- **A level is not a colour.** A colour role names which of your colours, never how far back it is
  held, and a slot that carries no opacity modifier cannot be held back by any answer to any role.
  Composing it in your own CSS is the route.
- **The charts that draw geometry from the data carry no part hook at all**, because their
  coordinates are the data and they have no slots to hook. A plugin reaches the frame around a
  chart and nothing inside the plot; the palette is what skins a plot.
- **A brand whose mark IS a gradient declares it once**, with `"gradientMark": true` in
  `arena.config.json`. The alternative is a marker on every line that draws the mark, and a marker
  suppresses every rule on its line rather than the one it is about.
- **Holding the report in CI takes kinds, not a switch.** A brand under 4.5:1 is a decision you
  already made and measured, and one switch over every kind would make that the price of holding
  the rest.
- **A part that exists in a slot and never in the rendered page passes every check there is**,
  because every check over a part reads text. Open the page and look at it.
- **The screen-reader-only idiom ships as a class**, so a rule selecting a part cannot compose it.
  A part you want hidden visually and kept for a reader is hidden by hand.

## What the kernel does not reach

Stated so you can plan around it rather than discover it.

- **Press travel and a resting edge have no role.** A control that stands on a hard bottom edge
  and drops into it when pressed is one product's whole identity, and it paints that by hand.
  `lift-control` and `press-scale` are the near miss and do not cover it.
- **A size ramp is not yours to re-answer**, the type and page rhythm ladders aside. Where a component's own
  ramp runs out, the exit is your own CSS on your own element, not a step moved under the kernel.
- **A document block family is markup you write.** Paragraph, heading, quote, callout, toggle,
  code and figure are the register of a document editor, and Arena is a product-application
  library.

## The loop

**Some of this is refused rather than reported, and knowing which is which saves you an
afternoon.** A role left unanswered by the root plugin, a value of the wrong type, a colour role
answered with anything but a `{color.*}` alias, an alias that resolves to nothing, and a broken
reading floor are all **hard failures of the plain command**: it writes nothing and exits non-zero.
Everything the audit says is a **report**, and stays one until you pass `--strict`.

The reading floors are the trap in that list, because an ordinary-looking scale step can break one.
Prose leading holds at 1.5 or more, heading leading at 1 or more, and the prose measure between 45
and 90. `{lh.tight}` is a perfectly normal step of the leading scale and it is under the heading
floor, so answering `lh-heading` with it refuses the build.

Beyond those, no gate reads your application, so the last step is the only one that checks the
thing you care about.

- [ ] Answer every role in `plugin.tokens.json`, starting with the shapes.
- [ ] Run `arena-to-prod --audit`. Your plugin directory is in scope because the config
      declares it, so the audit measures your application and your plugin together.
- [ ] Read the report. Fix what it names, and re-run it until it names nothing.
- [ ] Import the three files it writes, `arena.generated.css`, `icons.generated.css` and, when your
      plugin carries CSS, `plugin.generated.css`.
- [ ] Serve the application and look at it, in both polarities.

## How a role gets added

Paint the decision by hand through the part. The report names every part your plugins paint, and
that note is the evidence: **a role is added when several style plugins are measured painting the
same decision through the same part.** What one product paints is its own.

Two things that look like evidence and are not. A rule that restates the slot's own answer raises
the count without changing a pixel. And an ask whose whole content is a difference between two
states of one part cannot become a role at all, because a plugin selects by part and never by the
value of a variant: the component renders one part in both states, and a plugin paints it once.


<!-- skills/design/references/seo.md -->

# When it has to be found

Arena writes the document `<head>` in Angular, and whether your product needs that is a decision
about the product rather than about a screen.

Read this once per project, before the first screen. The rules of the language are in
[`../SKILL.md`](../SKILL.md) and hold whichever way this one is answered.

## The question, and no is a real answer

Ask whether somebody who is not already using this product has to arrive at it from outside. A
console, an admin tool and anything behind a login are a legitimate no, and it is because no is so
often the true answer that Arena publishes nothing until it is told to. A catalogue, a landing
page, a public listing and a documentation site are a yes, and a yes has consequences before the
first component.

## Arena writes the head in one layer, and the router is why

`@dravensoft/arena-angular/metadata` is a second entry point of the Angular package, apart from the
one every component comes from. It is apart because reaching it means reaching `@angular/router`,
declared as an optional peer for exactly this reason: a project that reaches only for components
never installs a router it does not use.

**`@dravensoft/arena-react` has no counterpart.** It writes no `<head>` at all, so a React project
carries that itself, through whatever its own framework offers, and a React framework picked to be
found generally offers one already. **What this decides is one piece rather than the stack**: on
Angular Arena supplies it and on React your own framework does, so a yes here costs a dependency on
one side and a wiring you were going to have anyway on the other. How the application is assembled
stays the project's answer, in the ninth node of [`cold-start.md`](./cold-start.md), which is also
where the asymmetry this page's reader is most exposed to is written down: a product that has to be
found is a product that server-renders, and the two layers do not hold that claim with the same kind
of evidence. Read it on the day the choice is still cheap.

## Three properties to know before you write a route

**Every route is private until one of them says otherwise.** A screen that should be found says so
itself, and the rest stay out of an index without anybody remembering to keep them out. Nothing
announces the default, so the first evidence of forgetting it is a page missing from a result nobody
thought to check.

**A canonical needs an address you supply.** Arena refuses to derive one from the document, because
such a value disagrees between a server render and the client that hydrates it, and a disagreement
there is invisible to whoever introduced it. Say where the application lives, once, and the
canonical and the `og:url` beside it both appear.

**A title composes rather than competes.** Angular's own `title` on a route keeps meaning what it
means and gains the suffix and the description beside it, so nothing already written gets rewritten
to suit Arena.

The exports carrying all three, with what each one takes, are on your package's own page:
[`../../../frameworks/angular/PACKAGE.md`](../../../frameworks/angular/PACKAGE.md), under the
heading about the `<head>`. Open it when the answer is yes.

## What both layers publish

`ArenaBreadcrumbs` describes the trail it draws in `schema.org` terms beside the markup, under both
frameworks, and it changes nothing a person sees. Pass it `origin` and every crumb is published at
an absolute address; without one the addresses go out as written, which readers support less well.
Its own prompt is where that member is documented.

`contracts/behaviour/structured-data.json` is that pattern stated on its own, and it is what markup
of yours binds when it describes a structure worth handing to a reader rather than only to a
person: a script of type `application/ld+json` next to the markup, the same structure in
`schema.org` terms, and `<` escaped in the serialisation so no value you supply can close the tag.
It is the one pattern in `contracts/behaviour/` that is not an accessibility requirement.

## What Arena does not decide

Arena renders no page and lists none. It writes the `<head>` of whatever page your application
renders and describes the structures it draws; how that page reaches a reader, and what a
crawler is handed when it asks for one, stay yours to answer. Which architecture produces it,
and the evidence behind each, is the ninth node of [`cold-start.md`](./cold-start.md). The three
properties above are the part Arena holds, and they are not the whole of the job.


<!-- skills/design/references/surface.md -->

# What Arena hands over

Arena is larger than the component list it is known for, and the parts that are not components
are the ones a project discovers late or never. This page is the whole offer in one place, the
line where it stops, and the one document that owns each part.

Read this first, before the three project questions the router asks next, because those three ask
how much of a thing you have not been shown yet. Nothing here teaches a part: every row names
where the part is written down, and that document is where you go once you know you want it.

## Everything Arena ships

| what it is | what you get | where it is written down |
|---|---|---|
| **The palette and the polarity** | The colours a build carries, declared by you: the base surface scale, the two accents, the four status colours, each of those with the colour that goes legibly on top of it, and the eight ramp slots. One palette reaches `:root` and every other becomes a class you put on `<html>`, so a build carries as many skins as it declares. Each one states whether it is dark or light, and that answer is what a first visit is matched against. | your layer's `PACKAGE.md`, the section about declaring a skin |
| **The token layer** | Every value the components read, as custom properties you may read too: the spacing scale `--sp-*` in thirteen steps, the type ladder `--fs-*` with `--fw-*`, `--lh-*` and `--ls-*` beside it, the corners `--r-*`, the borders `--bw-*`, the shadows, the scrims, the durations `--dur-*` and curves `--ease-*`, the stacking order `--z-*`, the three breakpoints `--bp-*`, the control and row sizes `--dz-*` that the density classes
re-answer, and the avatar and logo sizes. | the DTCG JSON per group in `contracts/design/`, with [`contracts/design/Scales.md`](../../../contracts/design/Scales.md) for what each step is for |
| **The colour aliases and the ink levels** | Short names over the palette for markup of your own: `--crimson`, `--gold`, `--danger`, `--success`, `--warning`, `--info`, `--bone`, `--mute`, `--bg`, and the soft washes beside each accent. The percentages the held-back text registers stand at are tokens rather than literals, so a palette moves them. | [`contracts/design/colors.css`](../../../contracts/design/colors.css) |
| **The style kernel** | Seventy-two questions about shape, space, weight, depth and which colour a surface takes, answered by a style plugin your project writes. This is the part that decides whether the product looks like yours, and it is not the palette. | [`style-kernel.md`](./style-kernel.md), over [`contracts/design/roles.json`](../../../contracts/design/roles.json) |
| **Two themes and two densities** | Dark and light without a component being rewritten, because a component reads roles. `.arena-compact` re-densifies the controls and the rows for a screen that has to hold more; `.arena-comfortable` grows them to a 48px touch target for a screen a thumb drives. The two are exclusive, and either is a class on an ancestor rather than a prop on anything. Density is an axis of its own rather than part of the style plugin, because how large a control is answers who is pointing at it and not what register the product speaks in: a shop on a phone and a console on a desk can want the same style plugin and opposite densities. Each re-answers the control and row sizes and nothing else, so the rhythm between two components stays where you spent it, and a screen that wants one on the desk and the other in the hand swaps the class from the breakpoint helper its layer exports, since a media query can add no class. | the rules section of [`../SKILL.md`](../SKILL.md) |
| **The components** | The furniture of an application somebody works in, filed under seven categories: `brand`, `charts`, `display`, `feedback`, `forms`, `layout` and `navigation`. Every one ships under both frameworks from one API declared once, and every one names the accessibility pattern it binds. | [`frameworks/INDEX.md`](../../../frameworks/INDEX.md) for whether one exists and which layers ship it, then your own layer's index |
| **Stylesheets for markup that is not a component** | The air between two of your elements, the column a page sits in, the measure of a reading column, a figure that does not jitter as it counts, and a label only a screen reader gets. These are what you build a page out of, and none of them is a component. | [`page.md`](./page.md) |
| **Exports that carry a promise** | The focus trap Arena's own dialogs run on, the two activation predicates, the notice queue and its dismissal rule, the chart ramp helpers, the tone-to-colour map, the two measurements, the visually-hidden style and the id the main landmark writes. Reach for these instead of writing a second copy: what your layer's page names is what carries a compatibility promise, and a symbol found by autocomplete is not. | the export table on your layer's `PACKAGE.md` |
| **The head, in one layer only** | A title that composes with the router's own, a description, a canonical and the `og:*` pair beside it, and a default that keeps a route out of an index until it says otherwise. Angular alone, behind a second entry point. | [`seo.md`](./seo.md) |
| **The command** | `arena-to-prod`, which turns your config into the stylesheet no package can carry, subsets the icon font to the glyphs your screens actually draw, reports where your own sources break a rule of the language, and names the components you have not used yet. | the build section of your layer's `PACKAGE.md` |
| **The behaviour contracts** | Each accessibility pattern stated once, normatively, in a form markup of your own can be held to: the roles it carries, the keys it answers, where focus goes and what dismisses it. Plus one that is not an accessibility pattern, for a structure worth handing to a reader rather than only to a person. | `contracts/behaviour/<pattern>.json`, and [`media-register.md`](./media-register.md) for when yours is the markup |

## How much of it you take

**Three steps, and each one is a place to stop.** A project on the first step is using Arena
correctly and is not waiting to finish; what the later steps buy is stated so you can decide
against them on purpose rather than by not knowing.

**The first step, take the language as it comes.** Install the package, write
`arena.config.json` with one palette and the three font slots, leave `stylePlugins` out or set
it to `default`, import the whole stylesheet, and compose with components. Put the air between
them on containers of your own with the classes [`page.md`](./page.md) names, and paint the page
through its role rather than a palette colour. This is the shortest honest route and the right
one for a first screen, a prototype or a tool nobody outside the team will look at. **What it
leaves unresolved is the appearance**: the product wears the answers Arena installs with, which
are Dravensoft's, and every project on this step looks like every other one.

**The second step, make it look like yours.** Write a style plugin, which is a directory holding
one entry per role, and name it first in `stylePlugins`. Your palettes and your fonts go in the
same config. From here the corners, the weights, the borders, the depth, the internal air and
which colour each surface takes are the product's own, and no component is rewritten to get
there. [`style-kernel.md`](./style-kernel.md) is where that decision is made and which answers
carry the visible difference.

**The third step, hold it.** Run the command's audit with `--strict` over the kinds you have not
already decided against, so a raw value or a class of your own on an Arena component stops being
something only a reader notices. Trim the stylesheet to what you render. Reach the metadata
entry point if [`seo.md`](./seo.md) answered yes. Bind the pattern from
`contracts/behaviour/` for any element you draw yourself, and take the export instead of the
reimplementation wherever one exists.

## Where Arena stops

Every line here is a decision rather than a gap waiting to close, so a project can plan around
it instead of waiting for it.

- **No page shape.** Arena ships the floor, the column, the air and the components, and no shape
  they must make. A console and a reading view are different pages before they are different
  components, so the composition is yours and the silence about it is deliberate.
- **No `<head>` in React.** That layer renders no title, description or canonical at all, and a
  React project carries its own through whatever its framework offers.
- **No prerender tooling and no sitemap.** How an application is assembled is the project's
  answer rather than Arena's, and both layers are written for a server render;
  [`cold-start.md`](./cold-start.md)'s ninth node answers each architecture with the evidence
  behind it. What Arena ships no tooling for is producing the pages or listing them, and it
  writes into the head of whatever page your application renders.
- **No gate reads your application.** The audit reads source text, and only for what source text
  can show. One primary accent per view, a filled danger surface, and every rule about meaning
  are held because you hold them and by nothing else.
- **The component list ends at the register.** A photo wall, a feed of posts, a slideshow, a
  document editor and a game map are markup you write, and the skin still travels;
  [`media-register.md`](./media-register.md) is what Arena hands you instead of a component.
- **No date picker and no time picker.** The native `type="date"`, `"time"` and
  `"datetime-local"` are the sanctioned controls: keyboard accessible, localized, and already
  known to whoever drives a phone. Arena's job is to make them look like Arena, which it does
  in both themes, and `ArenaInput`'s prompt in your layer is where they are written.
- **No route into a component's own box.** No component takes a class or a style of yours, and
  the class names one renders are compiler output that no contract names. Your layout goes on a
  container you own.
- **No icon font bundled.** Icons are Phosphor class-name strings a component renders, and the
  font arrives as a peer dependency rather than inside the package.
- **No runtime dependency and no CSS toolchain.** Every component's CSS ships compiled against
  Arena's own class names and tokens, so a project running its own utility framework cannot
  collide with it in either direction.
- **One pattern has no export.** The feed pattern is bound inside a component that is an event
  log with a fixed row, so it is not a feed of yours to reuse. Read how it binds the pattern and
  write the same thing around your own article.


<!-- skills/design/references/page.md -->

# The page you paint

Arena paints no page of yours. It draws the components, declares the floor they stand on, and
ships the column and the air as classes you put on your own markup, which leaves the page itself
a thing you write and gives you every value to write it with.

Read this before the first screen and again while you write one, because it is the half of a page
that is never a component: what colour your own markup takes, how wide the content column gets,
and how much space goes between one component and the next.

## The floor, and Arena does not paint it

**`--fill-page` is the floor of the page**, and it is yours to apply. Put it on the element that
owns the whole viewport, because a page with no floor shows the browser's own canvas below the
first screenful, which is white under a dark palette and is the most common way a correctly built
Arena screen looks broken.

**What Arena does declare is `color-scheme`, from the palette's polarity.** The scrollbars, the
native controls and the autofill the browser draws point the way the palette does without you
asking, which is why a palette states whether it is dark or light rather than leaving it inferred.

## Which colour your own markup takes

**Reach for a role when the thing you are drawing is furniture, and an alias when it is voice.**
Both are legitimate, and the difference is what happens when the skin changes: a role is what a
style plugin re-answers, so markup painted through one follows the appearance it is handed; an
alias resolves to a palette colour and follows the palette instead.

**Nineteen of the kernel's roles are colours**, and these are the ones a page of yours reaches
for. Their full descriptions are one entry each in
[`contracts/design/roles.json`](../../../contracts/design/roles.json).

| what you are drawing | the role |
|---|---|
| the page itself | `--fill-page` |
| a surface belonging to the page: a panel, a tile, a block of yours that reads as a card | `--fill-surface` |
| a surface floating over it: a popover, a layer of your own | `--fill-surface-floating` |
| a region recessed into a surface: a code block, a well | `--fill-surface-sunken` |
| a box somebody types into | `--fill-field` |
| what a row or a cell of yours takes under the pointer | `--fill-hover` |
| the ground a value runs along, or the box a set of segments sits in | `--fill-track` |
| a heading | `--ink-heading` |
| text somebody reads, and the default answer for any text slot | `--ink-body` |
| the small line above a title that says what kind of thing this is | `--ink-eyebrow` |
| text held back: a caption, a hint, a timestamp | `--ink-muted` |
| the line enclosing a surface, and the default ground line | `--edge-surface` |
| the line around a floating surface | `--edge-surface-floating` |
| the line around a control, a quiet control, a field, a marker | `--edge-control`, `--edge-control-quiet`, `--edge-field`, `--edge-marker` |
| the rule dividing one thing from the next inside a surface | `--edge-separator` |
| the wash a media frame draws under anything laid over it | `--overlay-media` |

Each edge role has a width beside it, `--bw-surface`, `--bw-control`, `--bw-field`,
`--bw-separator` and `--bw-marker`, so a border of yours is a role for the colour and a role for
the thickness and never a length you chose.

**A role says which colour the text takes, and a level says how far it is held back**, and text
needs both. Under the default style plugin `--ink-muted` and `--ink-body` resolve to the same
colour: what makes the held-back register held back is the level mixed into it, which is why a
bare `var(--ink-muted)` paints a caption at the strength of body copy and nothing reports it.
Spend one the way every Arena component spends it:

```css
color: color-mix(in oklab, var(--ink-muted) var(--level-ink-muted), transparent);
```

`--level-ink-body`, `--level-ink-quiet` and `--level-ink-muted` are the three, in
[`contracts/design/colors.css`](../../../contracts/design/colors.css). They are floors rather than
constants, and `arena-to-prod` raises one for a palette whose ink has too little room to clear its
contrast bar, so a percentage of your own is the one value on this page that cannot follow the
palette it was written against.

**The aliases are in [`contracts/design/colors.css`](../../../contracts/design/colors.css)**:
`--crimson` and `--gold` for the two accents with a soft wash beside each, `--danger`,
`--success`, `--warning` and `--info` for the four status colours with the same, and `--bone` and
`--mute` for text at full strength and held back. The percentages the held-back registers stand
at are tokens rather than numbers frozen into a rule, so raising one is a palette decision and
not an edit in a hundred places.

## Meaning and identity are two different colour sets

**A status colour means something and a ramp slot identifies something, and neither does the
other's job.** This is the rule the components hold, and markup of yours holds it the same way or
a reader learns that green is sometimes a category.

- **Meaning** is the four status colours. `arenaToneColor(tone)` from your package resolves the
  one a tone stands for, so a shape you draw yourself keeps meaning what the components mean by
  it.
- **Identity** is the eight ramp slots, `--color-cat-1` through `--color-cat-8`, in fixed order.
  The order is the identity, so slot three is slot three in every chart on the screen.
  `arenaCatColor(slot)` and `arenaCatTint(colour)` are there for a legend or a chip you draw.

## The column the page sits in

`css/page.css` and `css/prose.css` carry four classes, and each goes on markup you wrote.

- **`.arena-shell`** fills the window, so a short page's footer sits at the bottom rather than
  floating halfway up.
- **`.arena-shell__main`** goes on the one child of the shell that should take the slack. It is a
  class rather than something the shell distributes because a shell with a header, a main and a
  footer has exactly one child that should grow and no rule can know which. **If the child that
  should grow is an Arena component, wrap it in a `<div>` of your own and put the class on the
  div.** Refusing to put a class on an Arena element is right and stopping there is not: a
  component's own element may declare `display: contents` and carry no box, so a shell whose
  growing child is a component and has no wrapper distributes its slack to nothing and the footer
  floats halfway up the page, which is the same failure the shell exists to prevent.
- **`.arena-band`** centres its contents at the page width with a gutter either side. Put it
  inside anything that spans the viewport so the contents line up with the page above and below.
- **`.arena-prose`** holds a reading column to a measure in `ch` rather than a pixel width, so it
  tracks the font size the way a measure has to. Put it on an article or a section you wrote.

**All three lengths are roles**: `container-max`, `gutter` and `measure-prose`. A style plugin
written for reading narrows the column, and every page you already shipped follows without an
edit. Narrowing the column while keeping the gutter says the page is a document; widening both
says it is a console.

**The band carries the width and the gutter and no block air.** The space above and below a page's
content is yours, and it is a `padding-block` on a container of your own spent on the `--sp-*`
scale below. It is not a rhythm step: the classes in the next section answer the gap between two
siblings, and this is the padding of the box that holds them, which is a different question with a
different answer.

**The gutter is a ceiling and not a fixed inset**, so the band stands off by the whole of it at or
above the page width and by the same share of the space it has below that. A length answered for a
page that reaches its full width is the wrong length on a phone, where a fixed inset either side
leaves the content narrower than the air around it, and a class that only works at one width is a
class a screen has to override. Nothing on your side answers this: the band already does it, and
what you write is the same one class at every width.

## The air between two components

**Arena draws no outer margin on anything**, so the space between one component and the next is
always yours to place. `css/rhythm.css` is that half, as three named steps rather than a number
you pick.

| the class | the step | when |
|---|---|---|
| `.arena-stack` | `--rhythm-component` | a column of peers: a card and the next card, a chart and the table under it |
| `.arena-stack--group` | `--rhythm-group` | a column of things that read as one unit: a label and its field, a card's own stacked children |
| `.arena-stack--section` | `--rhythm-section` | between two sections of a page, which answer different questions |
| `.arena-row` | `--rhythm-group` | two or more things side by side that read as one unit: a mark beside a name, a label beside its badge |
| `.arena-row--component` | `--rhythm-component` | things side by side that are separate things: a bar's links, a toolbar's buttons |

**The three lengths are also custom properties**, `--rhythm-group`, `--rhythm-component` and
`--rhythm-section`, so a grid of your own or a rule the classes do not cover spends the same step
rather than a fresh number. Reach for the class first: it carries the display and the direction
with the gap, and a `gap` you write yourself is a rule that can drift off the step.

**The miss this replaces has one shape, and it is small enough to look like nothing.** A column of
your own carrying `display: flex`, `flex-direction: column` and a `gap`, holding a title over its
identifier inside a table cell, or a label over the value under it, written inline because reaching
for a class felt like more than two lines were worth. `.arena-stack--group` is exactly that block,
and the step a group is spent at is the same step wherever it is spent.

**The row is missed the same way and more often, because a short strip does not look like a
layout.** A mark and the product's name in an app bar, two links beside each other, an icon and
the word after it, a status label next to the badge it describes: each of those is a row, each is
usually written as a `display: flex` with a gap somebody chose, and each is a step off the scale
that no gate on your side reports. `.arena-row` is the horizontal half of the three steps above
and it answers all of them, whatever the line holds and however short it is. That it wraps when
the line runs out is a property it has, never the test for whether it applies: two elements side
by side are already a row.

**Five modifiers carry no length and line the items up instead**: `.arena-stack--start`,
`.arena-stack--end`, `.arena-row--start`, `.arena-row--baseline` and `.arena-row--between`. They
answer a question about your content, a trailing figure against a wrapping name, which is why
they are here rather than in the kernel.

**These classes go on an element you wrote, and they are useless on an Arena element.** A
component's own element may declare `display: contents` and carry no box, and one component
renders no element of its own at all, so an Arena element is never a layout target. **When the
element you need to lay out is a component, the answer is a `<div>` of your own around it**, not
dropping the class: refusing the class and writing no wrapper leaves the layout unstated, which
looks like restraint and reads on the screen as a bug.

**The air inside a component is not this.** `gap-control`, `gap-inline`, `gap-items`,
`pad-surface`, `pad-control-x` and `pad-control-y` are kernel roles, and you move them by
answering them differently in your style plugin rather than by writing a rule against a
component. That is the whole cut: between is yours and comes from here, inside is the kernel's
and comes from [`style-kernel.md`](./style-kernel.md).

## The rest of the scale, and the edges of the device

**`--sp-*` is the spacing scale in thirteen steps**, and it is what everything the rhythm classes
do not cover reads: `--sp-0` through `--sp-6` one step at a time, then `--sp-8`, `--sp-10`,
`--sp-12`, `--sp-16`, `--sp-20` and `--sp-24`. A bare length is a bug and this is the scale that
makes it unnecessary. [`contracts/design/Scales.md`](../../../contracts/design/Scales.md) says
what each step is for.

**`--pad-safe-top`, `--pad-safe-right`, `--pad-safe-bottom` and `--pad-safe-left`** compose the
device's own insets with that scale, in
[`contracts/design/environment.css`](../../../contracts/design/environment.css). Use them on a
shell you draw around Arena, so a bar pinned to the bottom of a phone screen clears the home
indicator without you measuring one.

**Two more classes are for markup rather than components.** `.arena-num` from `css/numerals.css`
puts a figure on the mono face with tabular figures and no colour, so a column of them aligns by
digit and does not jitter as it counts. `.arena-sr-only` from `css/sr-only.css` is a label a
screen reader announces and nothing paints, which is where the name of an icon-only control you
drew yourself goes.

## Taking the least of this, and taking all of it

**The least is the classes and the roles as they stand.** Paint the floor with `--fill-page`,
your text with `--ink-body` and `--ink-muted`, your own surfaces with `--fill-surface` and
`--edge-surface`, put `.arena-shell` and `.arena-band` around the page and `.arena-stack` between
things. Nothing here needs a style plugin, and a screen built this way already follows whatever
appearance the project adopts later.

**All of it is the same page with the roles re-answered.** Every name above that is a role rather
than an alias is a question your own style plugin answers, so the page you already wrote takes
the new corners, the new borders, the new column width and the new air without one of its rules
being edited. That is the reason to reach for the role over the alias in the first place, and
[`style-kernel.md`](./style-kernel.md) is where the answers are written.


<!-- frameworks/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena components

Every component Arena ships, by the category it is filed under. **This page answers one question:
whether a component exists at all, and which layers ship it.** It is not a stop on the way to
writing one: what a member is called where you are building, and how to write it, is your own
layer's index and then the component's own prompt, and reading this page first buys nothing when
you already know what you are reaching for.

**The rules of the language every component below answers to are stated in
[`../skills/design/SKILL.md`](../skills/design/SKILL.md) before any component on this page.**
Nothing here restates them, so a screen built from this page alone breaks the rules where nothing
will report it.

| Layer | Index | Package |
|---|---|---|
| Angular | [`angular/INDEX.md`](./angular/INDEX.md) | `@dravensoft/arena-angular` |
| React | [`react/INDEX.md`](./react/INDEX.md) | `@dravensoft/arena-react` |

- **Takes** is the members its API contract declares, in contract order, under the neutral names
  the contract gives them. A member marked `*` is required. Your layer's index gives the name
  each one binds to there, and the component's own prompt gives its type and its default.
- **Behaviour** is the accessibility pattern the component binds. `none` means no pattern
  applies, which is a claim the binding argues rather than an omission.
- **Layers** is which layers ship the component today.

## brand

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaAppLogo` | Brand lock-up: a mark beside or above a product name. | `mark*` `name*` `dim` `size` `orientation` | none | angular, react |

## charts

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaBarChart` | Categorical bars on one axis. Dependency-free SVG that reads the token layer directly, with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `stack` `valueSuffix` `valuePrefix` `valueFormat` `height` `minPointSpacing` | figure-with-data-table | angular, react |
| `ArenaChartCard` | A titled card frame around a chart, with an optional actions slot in its head. | `title` `headingLevel` `actions` `content` | none | angular, react |
| `ArenaDoughnutChart` | Parts of one whole, as a ring with a legend beside it. Identity only: a slice is a category by definition, so there is no tone. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `valueSuffix` `valuePrefix` `shape` `legendLayout` `sliceActivate` `valueFormat` | figure-with-data-table | angular, react |
| `ArenaHorizontalBarChart` | Categorical bars running across the plot, with the categories down its left edge. The same data and the same table as ArenaBarChart with the axes transposed, which is a different component rather than an orientation flag because transposing changes what four of its members mean: the cursor answers the vertical arrows, the category gutter is its own token, height becomes the axis the data grows along, and there is no scrolling rail. | `labels*` `series*` `label*` `stack` `valueSuffix` `valuePrefix` `valueFormat` `height` | figure-with-data-table | angular, react |
| `ArenaLineChart` | One series over an ordered sequence, on one axis. Dependency-free SVG with a crosshair that snaps to the nearest point, and a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `area` `curve` `valueSuffix` `valuePrefix` `valueFormat` `height` `minPointSpacing` | figure-with-data-table | angular, react |
| `ArenaPyramidChart` | A population pyramid: two counts per band, mirrored about a shared centre line, with the band names down the left edge. Diverging from a centre is the whole point rather than an option, which is why the two-series rule and the mirrored axis are the component instead of a flag on a bar chart. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `valueSuffix` `valuePrefix` `valueFormat` `height` | figure-with-data-table | angular, react |
| `ArenaRadarChart` | Several measures on one shape: an axis per label around a polar grid, one closed polygon per series. Reads a profile rather than a magnitude, which is what makes it a different chart from bars over the same numbers. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `fill` `valueSuffix` `valuePrefix` `valueFormat` `height` | figure-with-data-table | angular, react |
| `ArenaScatterChart` | Two quantities against each other, one mark per pair, and a third as the mark's size when a series carries one. The first chart here whose horizontal axis carries a value rather than a position, which is why it takes a series of parallel measurements and names every axis it draws. Dependency-free SVG with a visually-hidden table of the same numbers. | `series*` `label*` `xLabel*` `yLabel*` `sizeLabel` `sizeLegend` `valueSuffix` `valuePrefix` `valueFormat` `height` | figure-with-data-table | angular, react |

## display

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaActivityFeed` | An event feed: someone did something to something, then. Arena draws every row. | `label*` `items*` `busy` | feed | angular, react |
| `ArenaAvatar` | A person or entity mark: the image when `src` is set, initials from `name` otherwise, with an optional presence dot. | `src` `name` `size` `shape` `status` | none | angular, react |
| `ArenaBadge` | Status label: mono, uppercase, short. Carries an object's actual state or an editorial emphasis, never decoration. | `content` `tone` `dot` | none | angular, react |
| `ArenaCalendar` | Week or day schedule on a time grid. Colour is identity, never state. | `content` `timeZone` `anchorDate` `view` `dayStart` `dayEnd` `weekStartsOn` `hideEmptyWeekend` `dayInteractive` `dateClick` `rangeChange` `actions` | grid | angular, react |
| `ArenaCalendarEvent` | One event on an ArenaCalendar's schedule. Times are ISO datetimes read in the calendar's timeZone, never the reader's. ArenaCalendar draws the chip; the consumer writes one of these per event and ArenaCalendar settles where it goes. | `id*` `title*` `start*` `end*` `colorId` `interactive` `actionsEnabled` `actions` `disabled` `click` | button, none | angular, react |
| `ArenaCard` | Surface container. Hairline border on the base surface scale; depth comes from the shadow, never a gradient. | `content` `interactive` `disabled` `href` `action` `title` `headingLevel` `eyebrow` `floating` `accent` `click` | button, none | angular, react |
| `ArenaKeyValue` | A list of terms and the values against them, with an optional summed row ruled off at the bottom: a basket summary, an order, an invoice, a panel of facts about a resource. It renders a real definition list, so the association between a term and its value is the platform's rather than a class name's. | `rows*` `total` | none | angular, react |
| `ArenaPeopleList` | A list of people, each row a face with a name and, where the list is about a quantity, a figure beside it. Standings, assignees, members, suggestions. The list owns the semantics and the row size; a row owns what it says. | `label*` `ordered` `size` `content` | none | angular, react |
| `ArenaPersonRow` | One person in an ArenaPeopleList: a face, a name, an optional line under it, an optional position in front and an optional figure behind. Its size comes from the list rather than from here. | `name*` `src` `secondary` `rank` `figure` `current` `action` | none | angular, react |
| `ArenaSkeleton` | A loading placeholder that reserves the space real content will take. | `variant` `width` `height` `lines` `radius` | status | angular, react |
| `ArenaStatCard` | One metric on a card surface: a micro-label, the number, an optional delta pill and a sub-line. | `label*` `value*` `tone` `delta` `sub` `icon` | none | angular, react |
| `ArenaTable` | Data table on the density tokens. ArenaTable draws the header row from `columns`, owns the grid and its keyboard, and decides where each row sits; the consumer writes one ArenaTableRow per row and one ArenaTableCell per cell, so a cell's content is a value or one of Arena's own components rather than something returned from a per-item render function. Below --bp-md it becomes one card per row, measured on its own container rather than the viewport. | `label*` `columns*` `content` `empty` `sort` `sortChange` `page` `slice` `pageChange` `pageControl` `sortControl` `responsive` | grid, none | angular, react |
| `ArenaTableCell` | One cell of an ArenaTableRow. It draws the cell box (the padding, the alignment and the mono/gold treatment its column asks for, and in card mode the label/value pair or the full-width block), and shows whatever the consumer put in it. Its column config, its layout and its place in the grid's keyboard order come from ArenaTable and ArenaTableRow and are members of no contract. | `content` `href` `navigate` | none | angular, react |
| `ArenaTableRow` | One row of an ArenaTable. The consumer writes one per row and one ArenaTableCell inside it per cell. Where the row sits, the columns its cells are set against and how the keyboard reaches them are ArenaTable's, not this component's, and are members of no contract: the same shape, and for the same reason, as an ArenaRadioGroup and its Radios sharing which one is checked. | `content` `interactive` `disabled` `click` | button, none | angular, react |
| `ArenaTag` | A pill for filters, technologies and statuses. A tone for what state a thing is in or a ramp slot for which thing it is, and an optional dismiss. | `content` `tone` `colorId` `removable` `disabled` `remove` | button, none | angular, react |
| `ArenaUnauthCard` | The panel a signed-out screen needs: sign in, check your inbox, this link expired, a two-factor code. It knows nothing about credentials on purpose; the fields are composed inside it. | `brand` `eyebrow` `title` `headingLevel` `content` `footer` | none | angular, react |

## feedback

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaAlert` | A tone-coloured message with an optional icon, a single action, and optional dismissal. | `tone` `title` `content` `icon` `actionLabel` `action` `dismissible` `close` | alert, status | angular, react |
| `ArenaConfirmDialog` | Confirmation of a high-consequence action. Never closes on click-outside. `requireText` locks the confirm button until a word is typed. | `open*` `title*` `eyebrow` `content` `confirmLabel` `cancelLabel` `destructive` `requireText` `cancel` `confirm` | alertdialog | angular, react |
| `ArenaDialog` | Modal dialog over a blurred scrim. Takes the whole interaction until dismissed. | `open*` `title*` `eyebrow` `width` `content` `footer` `close` | dialog-modal | angular, react |
| `ArenaEmptyState` | A placeholder for an empty collection: an icon, a title, a message, and an optional action. | `icon` `title*` `headingLevel` `message` `action` | none | angular, react |
| `ArenaErrorState` | Section/screen-level failure, with recovery and an optional diagnostic code. | `icon` `title` `headingLevel` `message` `code` `retryLabel` `retry` `secondaryAction` | alert | angular, react |
| `ArenaOnboarding` | Guided coachmark tour (H10): presents features within the product with progress dots, Skip and Next. Controlled: the host owns index and answers the four events. | `open*` `steps*` `index` `anchor` `next` `back` `skip` `done` | dialog-modal | angular, react |
| `ArenaProgressBar` | Determinate progress by default; indeterminate for a wait with no percentage. A bar along a row, or a ring with the figure inside it. | `content` `progressPercentage` `indeterminate` `tone` `label*` `showLabel` `showPercentage` `size` `shape` | progressbar | angular, react |
| `ArenaSheet` | A non-modal panel anchored to one edge of the page: a cart, a filter drawer, a detail pane. It carries no scrim, traps no focus and takes nothing away from the page behind it, which is the whole difference from a dialog. Its header stays on screen while its body folds away, so a reader keeps the panel without keeping its bulk. | `open*` `placement` `title*` `collapsed` `collapsedChange` `dismissible` `close` `content` `footer` | disclosure | angular, react |
| `ArenaSpinner` | Indeterminate wait indicator. For a measurable process use ArenaProgressBar instead. | `size` `tone` `label` | progressbar | angular, react |
| `ArenaToast` | Ephemeral notification with a tone-coloured side bar and one optional action. | `title` `message` `tone` `actionLabel` `action` `persist` `dismissible` `close` | alert, status | angular, react |
| `ArenaToastHost` | The fixed box a stack of notices renders into. It decides where the stack sits, how far it stands off the viewport edges and how much air separates two notices, and it decides nothing else: it reads no notice, counts none, and owns no clock. | `placement` `content` | none | angular, react |
| `ArenaTooltip` | A short label revealed on pointer intent. Bone over dark for contrast. It waits before appearing and before withdrawing, so a pointer crossing a toolbar reveals nothing. | `label*` `content*` | tooltip | angular, react |

## forms

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaButton` | Action button. One primary per view; danger stays outline. | `content` `variant` `size` `icon` `iconRight` `loading` `full` `disabled` `type` `name` `value` `autoFocus` `form` `tabStop` `click` | button | angular, react |
| `ArenaCheckbox` | A single checkbox. Checked shows a crimson fill with a check. | `checked` `label` `disabled` `required` `name` `value` `change` | checkbox | angular, react |
| `ArenaIconButton` | Icon-only button. Carries an accessible name in every state, not only on hover. | `icon*` `label*` `size` `variant` `showLabel` `pressed` `disabled` `type` `name` `value` `autoFocus` `form` `tabStop` `click` | button | angular, react |
| `ArenaInput` | Text field with validation. Focus is a gold ring; error crimson; valid green with a check. The four states are ordered and the order is normative: error, then focus, then valid, then neutral: an errored field stays crimson while it has focus, because the validation signal must not disappear at the moment the user acts on it. | `label` `id` `hint` `error` `valid` `required` `validate` `validateOn` `type` `icon` `prefix` `value` `disabled` `readOnly` `placeholder` `name` `autoComplete` `min` `max` `step` `maxLength` `pattern` `change` `blur` | textbox | angular, react |
| `ArenaRadio` | One option inside an ArenaRadioGroup. Selected shows a crimson dot inside the ring. | `value*` `label` `hint` `disabled` | radiogroup | angular, react |
| `ArenaRadioGroup` | Single-selection group. Governs the value and distributes it to its child Radios. | `ariaLabel*` `content` `value` `name` `change` | radiogroup | angular, react |
| `ArenaSelect` | Styled native dropdown selector, with the same validation vocabulary ArenaInput carries. The four states are ordered and the order is the same normative one: error, then focus, then valid, then neutral -- an errored control stays crimson while it has focus, because the validation signal must not disappear at the moment the user acts on it. A form that mixes ArenaInput and ArenaSelect is a form whose fields must report a failure the same way, or it gets validated by hand or not at all. | `label` `placeholder` `options` `value` `disabled` `required` `hint` `error` `valid` `icon` `name` `change` | select | angular, react |
| `ArenaSwitch` | A controlled on/off switch showing an icon per state. `confirm` gates a high-impact change through an ArenaConfirmDialog before it applies. | `state` `orientation` `size` `iconOn` `iconOff` `label*` `disabled` `confirm` `funcOn` `funcOff` `requestChange` | switch | angular, react |
| `ArenaTextarea` | Multi-line text field with validation and an optional counter. | `label` `id` `hint` `error` `required` `counter` `autoResize` `value` `disabled` `readOnly` `placeholder` `name` `maxLength` `rows` `change` | textbox | angular, react |

## layout

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaBoard` | The frame of a board: columns side by side, as wide as the room allows and never narrower than one column's minimum, scrolling sideways when they no longer fit. It is one tab stop carrying a group role and a name, which is what a scrolling region needs to be reachable by keyboard at all. It draws no card and moves nothing: what a column holds is the consumer's, and reordering is theirs too. | `label*` `content*` `minColumn` | scrollable-region | angular, react |
| `ArenaBoardColumn` | One column of an ArenaBoard: a named head with a count and a control, a stack of whatever the consumer puts in it, and a footer for the one action that adds to it. The cards are the consumer's own, because a card on a board carries that product's fields and nothing general is left once they are removed. | `title*` `headingLevel` `count` `summary` `colorId` `action` `content` `footer` | none | angular, react |
| `ArenaFigure` | A framed piece of media with an optional caption: an image, a video, or a stand-in for the one that has not arrived. The frame is a shape and a corner a style plugin answers, and it clips whatever is put in it, so a wall of figures reads as a wall rather than as whatever sizes the pictures happened to be. | `media` `fallback` `overlay` `caption` `ratio` | none | angular, react |
| `ArenaGrid` | A grid that decides its own column count from the room it is given, rather than from a breakpoint anyone had to pick. Cells are as wide as they can be at or above a minimum, and the count falls as the room does, all the way to one. | `min` `gap` `maxWidth` `content` | none | angular, react |
| `ArenaHero` | The opening of a landing page: one line the page is built around, what sits above and below it, the actions it asks for, and a figure beside or behind it. Its title takes the hero register, which is the top rung of the title ladder and the only one above the page head. | `title*` `headingLevel` `eyebrow` `lede` `actions` `figure` `layout` `align` | none | angular, react |
| `ArenaMain` | The page's main landmark, and nothing else. Arena requires a name on both of its nav bars because what a nav is FOR is editorial, and then shipped no way to say where the content itself begins, which is the one region of a page it had not kept its own decision about. This draws no box: no display of its own beyond the block a landmark already is, no width, no grid, no padding. Where things go stays the container the consumer owns, and this says only what the region IS. It is also the target an ArenaSkipLink jumps to, so it is focusable programmatically: an anchor pointing at a container the platform will not focus scrolls the page and leaves focus behind, which is the failure that makes most skip links look like they work. | `content` | main | angular, react |
| `ArenaScroller` | A row that scrolls sideways because it holds more than fits, with no arrows pretending to be a slideshow. It is one tab stop carrying a group role and a name, which is what a scrolling region needs to be reachable by keyboard at all: without it, everything past the right edge belongs to the pointer alone. Each child is laid out at one width so the row reads as a rail rather than as a line of whatever the children happened to measure. | `label*` `content*` `itemWidth` `behaviour` | scrollable-region | angular, react |
| `ArenaScrollerItem` | One cell of an ArenaScroller: the box that carries the width the row decided and the point the row settles on. It exists because a row cannot reach inside its children to size them, and a child that is an Arena component may render no box of its own at all, so a rule aimed at the row's direct children lands on nothing in one layer and on the card in the other. The item is the box both layers agree about. | `content` | none | angular, react |
| `ArenaSection` | A named region of a page: a heading, optionally an eyebrow above it, a line under it and an action beside it, over whatever the region holds. It wraps what the consumer wrote and never replaces it. The title register is the section one, a step above a card's and a step below a page's, so a style plugin re-pitching the hierarchy moves this with the other two rather than leaving a page with three heads that disagree. | `title*` `headingLevel` `content*` `eyebrow` `description` `action` `rhythm` | none | angular, react |
| `ArenaSiteFooter` | The band across the bottom of every screen: what a page says about itself once it has finished. It is the contentinfo landmark, so there is one per page, and like the bar at the top its contents line up with the page above them. | `content` `note` | contentinfo | angular, react |
| `ArenaSkipLink` | The link that lets a keyboard reader step over everything repeated on every screen and land in the content. It is four details and almost nobody gets all four: it has to be the first focusable thing in the document, invisible until it takes focus and visible the moment it does, and its target has to be focusable programmatically or focus never moves. Arena owns all four, and the consumer owns only the words. It points at the ArenaMain on the page, by an id Arena writes on both sides, so nothing is coordinated at the call site: a page has one main landmark, which is what makes a fixed id right here and wrong almost everywhere else. Place it first in the shell, above the header and the nav bars it exists to skip, which is the one thing it cannot do for itself. | `label*` | none | angular, react |

## navigation

| Component | What it is | Takes | Behaviour | Layers |
|---|---|---|---|---|
| `ArenaAppBar` | The band across the top of every screen: the site's identity, the way through it, and the controls that follow the reader everywhere. It is the banner landmark, so there is one per page, and its contents line up with the page under it because the bar spans the viewport and the band inside it does not. | `brand` `nav` `actions` `sticky` | banner | angular, react |
| `ArenaBottomNav` | The bar of destinations pinned to the bottom edge of a phone screen. A compound component: the consumer writes one ArenaBottomNavItem per destination, and the coordination that tells each child which id is active and how to report `nav` is the parent's. That coordination is a member of no contract and each layer wires it in its own idiom. It is a row of equal columns with the glyph above the label, which is what separates it from a sidebar's stack of indented rows. | `active` `ariaLabel*` `content` `nav` | navigation | angular, react |
| `ArenaBottomNavItem` | One destination in an ArenaBottomNav. The consumer writes one per destination; which id is currently active and how it reports `nav` are settled between it and its parent, and none of that is a member of this contract, the same shape and the same reason as ArenaSideNavItem and as the name an ArenaRadioGroup settles with each ArenaRadio. It draws its glyph above its label and takes an equal share of the bar's width, however many destinations there are. | `id*` `label*` `icon*` `badge` `href` `disabled` | button, none | angular, react |
| `ArenaBreadcrumbs` | A trail of ancestor locations ending at the current one. An explicit return path for hierarchies deeper than tabs. | `ariaLabel*` `items*` `separator` `origin` `navigate` | navigation | angular, react |
| `ArenaBulkActionBar` | Appears when rows are selected and operates on the selection as a set. Renders nothing at a count of zero. | `count*` `noun` `actions*` `run` `layout` `clearable` `clear` | toolbar | angular, react |
| `ArenaCommandPalette` | Power-user accelerator (Cmd/Ctrl+K): search and run actions without a mouse. Controlled: the host owns whether it is open. | `open*` `commands*` `placeholder` `maxResults` `close` `run` | combobox | angular, react |
| `ArenaMenu` | Dropdown menu of actions on a trigger -- overflow, more actions, context. | `trigger*` `items*` `align` `select` | menu-button | angular, react |
| `ArenaPageHead` | A page heading: a required title, an optional subtitle, and an optional actions slot. | `title*` `headingLevel` `subtitle` `actions` `align` | none | angular, react |
| `ArenaPagination` | Page selector for a paged list. Renders a windowed range, never every page. | `page*` `pageCount*` `ariaLabel*` `change` | navigation | angular, react |
| `ArenaSegmentedControl` | A compact inline filter over mutually exclusive options. A real radio group, never a tab list, and it carries no crimson. | `options*` `value` `defaultValue` `size` `ariaLabel*` `name` `change` | radiogroup | angular, react |
| `ArenaSideNav` | The sidebar's navigation list -- the list alone, not the frame around it. A compound component: the consumer writes one ArenaSideNavItem per destination, and the coordination that tells each child where it sits, which id is active and how to report `nav` is the parent's. That coordination is a member of no contract and each layer wires it in its own idiom. | `active` `ariaLabel*` `content` `indentStep` `nav` | navigation | angular, react |
| `ArenaSideNavCollapsible` | A named group inside an ArenaSideNav that shows and hides its own contents. It may contain items, sections and further collapsibles to any depth; the indent compounds with depth, which is why ArenaSideNav.indentStep is a step rather than a total. It binds the `disclosure` pattern and deliberately does NOT claim to be a treeview: there is no aria-level, no roving tab stop and no arrow navigation, because each collapsible is an independent disclosure. Its expanded state lives in the component, seeded by defaultExpanded, and it additionally opens itself when it COMES TO HOLD ArenaSideNav.active -- a transition, not a standing condition, which is what leaves a user free to collapse a group again while the route stays inside it. Implicit behaviour, stated here and in its .prompt.md rather than left to be discovered. | `id*` `label*` `icon` `defaultExpanded` `content` `toggle` | disclosure | angular, react |
| `ArenaSideNavItem` | One destination in an ArenaSideNav. The consumer writes one per destination; the nesting depth it sits at, which id is currently active and how it reports `nav` are settled between it and its parent, and none of that is a member of this contract -- the same shape, and the same reason, as the name, checked state and selection callback an ArenaRadioGroup settles with each ArenaRadio. It used to be api/types/side-nav-item.json, a predefined object Arena read out of an array; it is an element the consumer writes now, which is what makes a section, a collapsible and arbitrary nesting expressible at all. | `id*` `label*` `icon` `disabled` `badge` `href` | button, none | angular, react |
| `ArenaSideNavSection` | A named group of navigation items inside an ArenaSideNav. It wraps what the consumer wrote and never replaces it; its accessible name is the same heading a sighted user reads. A section always has children -- a childless one is guarded against at runtime, because two shapes would be one more thing a single behaviour binding cannot describe. Having sections at all is optional: loose SideNavItems at the root are legal and may sit beside them. | `label*` `content*` | none | angular, react |
| `ArenaTab` | One tab in an ArenaTabs strip, and the panel it shows. ArenaTab draws the button; its content fills the tabpanel ArenaTabs renders beside the tablist. | `value*` `label*` `content` | none | angular, react |
| `ArenaTabs` | A row of tabs and the one panel they switch between. Write one `ArenaTab` per view; ArenaTabs renders the tablist, the panel, and the keyboard. | `content` `value` `defaultValue` `change` | tabs | angular, react |

73 components across 7 categories.


<!-- frameworks/angular/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena components, the Angular layer

Every component this layer ships, under the category it is filed under. **This page is a
directory, not an index.** Find the name you are reaching for in the middle column, open that
category's index for what the component takes, and its own prompt for how to write it. The
components are named here rather than described so that finding yours costs one page instead of
a guess.

**Read [`../../skills/design/SKILL.md`](../../skills/design/SKILL.md) before you write anything
from here.** It carries the one thing no page below it does: the rules of the language, which hold
in your code because you hold them and which no gate reads your application to enforce. A screen
built from this tree alone breaks them where nothing will report it.

- Installing the package, declaring your skin, and what it exports besides components:
  [`PACKAGE.md`](./PACKAGE.md).
- Whether a component exists at all, including any this layer does not ship:
  [`../INDEX.md`](../INDEX.md).

| Category | The components it holds | Index |
|---|---|---|
| `brand` | `ArenaAppLogo` | [`components/brand/INDEX.md`](./components/brand/INDEX.md) |
| `charts` | `ArenaBarChart` `ArenaChartCard` `ArenaDoughnutChart` `ArenaHorizontalBarChart` `ArenaLineChart` `ArenaPyramidChart` `ArenaRadarChart` `ArenaScatterChart` | [`components/charts/INDEX.md`](./components/charts/INDEX.md) |
| `display` | `ArenaActivityFeed` `ArenaAvatar` `ArenaBadge` `ArenaCalendar` `ArenaCalendarEvent` `ArenaCard` `ArenaKeyValue` `ArenaPeopleList` `ArenaPersonRow` `ArenaSkeleton` `ArenaStatCard` `ArenaTable` `ArenaTableCell` `ArenaTableRow` `ArenaTag` `ArenaUnauthCard` | [`components/display/INDEX.md`](./components/display/INDEX.md) |
| `feedback` | `ArenaAlert` `ArenaConfirmDialog` `ArenaDialog` `ArenaEmptyState` `ArenaErrorState` `ArenaOnboarding` `ArenaProgressBar` `ArenaSheet` `ArenaSpinner` `ArenaToast` `ArenaToastHost` `ArenaTooltip` | [`components/feedback/INDEX.md`](./components/feedback/INDEX.md) |
| `forms` | `ArenaButton` `ArenaCheckbox` `ArenaIconButton` `ArenaInput` `ArenaRadio` `ArenaRadioGroup` `ArenaSelect` `ArenaSwitch` `ArenaTextarea` | [`components/forms/INDEX.md`](./components/forms/INDEX.md) |
| `layout` | `ArenaBoard` `ArenaBoardColumn` `ArenaFigure` `ArenaGrid` `ArenaHero` `ArenaMain` `ArenaScroller` `ArenaScrollerItem` `ArenaSection` `ArenaSiteFooter` `ArenaSkipLink` | [`components/layout/INDEX.md`](./components/layout/INDEX.md) |
| `navigation` | `ArenaAppBar` `ArenaBottomNav` `ArenaBottomNavItem` `ArenaBreadcrumbs` `ArenaBulkActionBar` `ArenaCommandPalette` `ArenaMenu` `ArenaPageHead` `ArenaPagination` `ArenaSegmentedControl` `ArenaSideNav` `ArenaSideNavCollapsible` `ArenaSideNavItem` `ArenaSideNavSection` `ArenaTab` `ArenaTabs` | [`components/navigation/INDEX.md`](./components/navigation/INDEX.md) |

73 components across 7 categories in this layer.


<!-- frameworks/angular/PACKAGE.md -->

# @dravensoft/arena-angular

[![npm](https://img.shields.io/npm/v/@dravensoft/arena-angular?style=flat-square&color=c5a059&label=npm)](https://www.npmjs.com/package/@dravensoft/arena-angular)
[![downloads](https://img.shields.io/npm/dm/@dravensoft/arena-angular?style=flat-square&color=c5a059)](https://www.npmjs.com/package/@dravensoft/arena-angular)
[![license](https://img.shields.io/npm/l/@dravensoft/arena-angular?style=flat-square&color=c5a059)](https://github.com/dravensoft-dev/arena/blob/main/LICENSE)

![The same Angular component under three style plugins, with the contracts that decide what it is](https://arena.dravensoft.org/hero.png)

Arena is Dravensoft's design system. This package is its Angular layer: 73 components, standalone
and `OnPush`, with signal inputs and outputs, styled by a shared Tailwind recipe per
component, and shipped in Angular Package Format.

**The package carries the language. It does not carry a skin.** Your palettes and your fonts
are yours, declared in one JSON file, and the `arena-to-prod` command that ships here turns
that file into the stylesheets Arena reads.

**What comes down with it.** `@angular/core`, `@angular/common` and `@angular/platform-browser`,
which you already have; `@angular/cdk`, because a primitive that anchors a surface to a trigger uses its overlay, and `arena-tabs` its roving-focus key manager
to position themselves, and for position only, since the roles, the keys and the focus are
Arena's own; and `@phosphor-icons/web`, which you may not have: Arena's icons are Phosphor class
names a component renders, never SVGs it bundles, so the font is installed alongside the package
rather than bundled inside it. `tslib` is the only runtime dependency this package declares.

**You do not need to run Tailwind, and running your own cannot collide with this one.** Every
component's CSS ships compiled, so one `@import` is enough and you compile nothing. The rules
are written against Arena's own class names and read Arena's own tokens: Tailwind is how they
were authored and nothing more, so a `--spacing` of your own moves nothing here.

<!-- @shared offer GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## What Arena gives a project

**Components whose API is a contract.** Every member of every component is declared once, in one
place both layers are generated from and held to, so a name, a type, a default and what it means
are the same under either framework, and the table documenting a component is emitted from that
declaration rather than written beside it.

**Behaviour each component binds rather than an audit somebody runs.** A component names the
accessibility pattern it implements, most of them a
[WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) one: the roles it
carries, the keys it answers, where focus goes and what dismisses it. The pattern is recorded per
component, and so is anything a component does not yet meet, with its reason.

**A style kernel, which is how Arena stops looking like Arena.** Arena keeps the questions about
shape, space, weight and depth and ships one set of answers; a project writes its own as a style
plugin, which is the ordinary case rather than an escape hatch. A palette is not an appearance,
so the config below is the smaller half of that decision.

**Every member documents itself where you already are.** The members of every component, each with
the paragraph saying what it is for, ship as this package's type declarations, so an editor shows
them on hover and the file the `types` entry resolves to is the same reference in one place. That
is the member-level answer; what it does not carry is the language above it, which is the next
section.

**What a machine reads off a screen is part of what a component draws.** `ArenaBreadcrumbs`
describes the trail it draws in `schema.org` terms, so a crawler reads the same trail a person
does. Whether this package also writes your `<head>` is a thing only this package can answer,
and it answers it below.

<!-- @shared offer end -->

**A `<head>` for a product that has to be found from outside it, and it is optional.** This
package writes one, at `@dravensoft/arena-angular/metadata`: a title composed with Angular's own,
a description, a canonical and the `og:*` pair, and every route private until it says otherwise.
It sits behind a second entry point because reaching it means reaching the router, an optional
peer nothing else here asks for.

<!-- @shared register GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## The screens it is for

Arena is a **product-application library**: its components are the furniture of an application
somebody works in, tables and their rows, forms and their fields, navigation, dialogs, charts,
cards and the empty, loading and error states around them. A media or a consumer product is a
different register, so a photo wall, a story ring, a feed of posts, a slideshow, a document
editor and a game map are markup you write yourself.

**The skin travels either way.** A style plugin answers every role whatever the product is, so
what Arena does draw wears your appearance rather than Arena's. What runs out first is the
component list.

**When the answer is that the markup is yours, the pattern is still not.** This package ships
`contracts/behaviour/`, one file per accessibility pattern, stating normatively what markup of
yours has to do to carry it: the roles it takes, the keys it answers, where focus goes on open,
what it returns to on close and what dismisses it. `dialog-modal.json` is the one a lightbox or a
viewer of yours binds; `feed.json` a scrolling list of posts. Read the file for the pattern you
are drawing, and take the exported helper named in the table below rather than writing a second
copy of either half.

<!-- @shared register end -->

<!-- @shared repository GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## This package ships the components and not the language

See it before you install it: **https://arena.dravensoft.org** has the guidelines, a kitchen sink
and a playground for every component. Source and full documentation:
**https://github.com/dravensoft-dev/arena**

**An agent building with Arena needs the repository, and this is a prerequisite rather than a
recommendation.** The rules every component answers to, the usage document of each one, and the
style kernel a project answers to make Arena look like its own product are all there and none of
them is in this tarball. Install the **Claude Code plugin**, or clone the repository and point your
agent at `skills/design/SKILL.md`, before you ask for the first screen. Over HTTP the same route
starts at **https://arena.dravensoft.org/llms.txt**.

Without them an agent guesses, and **no gate reads your application**, so nothing reports the
difference: the screen renders, and the rules it breaks are the ones only a reader notices.

The package is the code. The repository is the language.

<!-- @shared repository end -->

## Install

```bash
bun add @dravensoft/arena-angular      # or: npm i / pnpm add
```

**npm, bun and pnpm all install this**, and pnpm is the one worth naming because its layout is
the strict one: nothing here is hoisted into place by accident, since every peer is declared
rather than assumed, and the command below resolves the icon font through the symlinked store
like any other dependency. No hoisting flag is needed under any of the three.

That is the whole install. Angular, the CDK and `@phosphor-icons/web` are peer dependencies, so
your package manager brings down whichever of them the project does not already have. **The package declares `engines: { node: ">=22" }`**, and Angular's own floor is the stricter of the two, so it is the one that decides which Node your project runs. Arena never refuses a Node your framework accepts: the command it ships is plain JavaScript over `node:fs`, `node:path` and `node:url`, and a higher floor here would buy an engine warning on every install and nothing else.

**An icon is a class name, not an element.** Every `icon` input takes a Phosphor class list,
`"ph-bold ph-bell"`, and the component renders it. The stylesheet that turns those classes into
glyphs is not the one Phosphor ships: it is the subset `arena-to-prod` writes for you, below.

<!-- @shared support GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## What this works with

**Arena is built with bun, and bun is required nowhere.** The command below is a Node program
reading three node modules, so whatever runs a Node program runs it. These are the two axes that
decide whether this package fits a project at all; the rest of the repertoire, the bundler, the
stylesheet route and the framework versions, each carrying the evidence behind it, is at
[the repertoire page](https://arena.dravensoft.org/skills/design/references/stack.md).

**What runs the command?**

| You may choose | Evidence | What is true |
|---|---|---|
| Node >=22 | held by a gate | the command is a Node program, and that floor is the oldest line Node still supports rather than a capability the command needs |
| any runner that reaches a Node program | allowed by the manifest, not exercised | npx and bunx both reach the same file. No runner is required: the command imports three node modules and no runtime API of its own |

**How is the package loaded?**

| You may choose | Evidence | What is true |
|---|---|---|
| an ES module import | held by a gate | the package is a module, and every target its exports name resolves to a file that is there |
| a CommonJS require | does not work | there is no require condition and no second build. A project that cannot load a module cannot load this one, and it fails at the first import rather than somewhere later |


<!-- @shared support end -->

## One name everywhere

Every element carries the `arena-` prefix and every exported class carries `Arena`, which are
the same name in two spellings: `<arena-button>` is the element, `ArenaButton` is the class you
put in an `imports` array, and `kebab('ArenaButton')` is what turns one into the other.

```ts
import { ArenaButton, ArenaCard } from '@dravensoft/arena-angular';

@Component({ imports: [ArenaButton, ArenaCard], template: `<arena-button>Save</arena-button>` })
```

Every type carries it as well, so a tone is an `ArenaTone`, and the projection markers carry it
already: `ArenaAction`, `ArenaActions`, `ArenaBrand`, `ArenaFooter`, `ArenaSecondaryAction`,
`ArenaFigureSlot`, `ArenaMedia`, `ArenaFallback`, `ArenaOverlay` and `ArenaNav`.

**The class names carry it too, and they carry it once.** A component renders
`.arena-button__root`, spelt from the component's own name, so a rule of yours written against
that class is a rule about this component and nothing else. Every sheet is named the same way,
which is why `css/components/arena-button.css` is the file and `arena-button` is what you write
in a `stylesheet` list.

**An optional value binds straight through.** Every input that carries a default resolves an absent value back to it, so a field of yours that may be unset needs no `?? '...'` at the call site: `[tone]="toast.tone"` is enough, and the default stays stated in one place, the component. It is the members' own defaults that the prompt tables carry.

## Your layout goes on a container you own

**Put your spacing and sizing on an element you wrote, and let the Arena element be its child.**
Arena draws no outer margin on anything, so the air between two components is always yours to
place. Where you place it matters: `<arena-button>`, `<arena-card>` and `<arena-tabs>` are three
of the components that take their host out of layout with `display: contents`, because their
real root has to be a `<button>`, an `<a>` or a `<div role="tablist">`. That host carries no box,
so a `margin`, a `flex`, a `min-width` or a `.row > * { ... }` rule aimed at one of them is
discarded and nothing reports it. The rule parses and the selector matches; there is simply no
box for the declaration to land on. Which components do this moves between releases, so write
the rule above everywhere rather than checking it component by component.

**Your own routed components need that same declaration, for the mirror-image reason.** Angular
puts your component's element between `<router-outlet>` and your content, so a `gap` on the
container around the outlet reaches that one element and stops there:

```ts
@Component({
  selector: 'app-overview',
  host: { style: 'display: contents' },   // without this, the parent's gap stops here
  template: `<arena-page-head ... /><arena-grid ... />`,
})
export class Overview {}
```

With it, your sections are children of the container again and the gap reaches each of them.
Carrying the layout class on the host instead works as well. Either beats finding out as a page
whose spacing collapsed everywhere at once with nothing in the stylesheet to blame.

**`<router-outlet>` is a flex item too, and it draws nothing.** The routed component is inserted
as its sibling, so the outlet element is an empty box that still takes a slot in your stack and
spends one whole gap of it, pushing every page down by one step. `router-outlet { display: none }`
in your global stylesheet ends it.

**When you wrap a component to size it, give the wrapper a display.** The wrapper is the flex or
grid item now, so it is what stretches, and a component sitting inside it as a plain block will
not grow with it: the width lands and the height does not. `display: grid` on a wrapper with one
child passes the full cell to it.

<!-- @shared page GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## The page around the components

**The floor is yours, and this package paints none of it.** `--fill-page` is the role the page
itself takes, and it goes on the element that owns the whole viewport. A page with no floor shows
the browser's own canvas below the first screenful, which is white under a dark palette and is the
most common way a correctly built screen looks broken. What the package does declare is
`color-scheme`, from the palette's polarity, so the scrollbars, the native controls and the
autofill the browser draws point the way the palette does without you asking.

**Markup of your own takes a role the same way a component does.** `--fill-surface` and
`--edge-surface` for a panel or a block of yours that reads as a card, `--fill-surface-sunken`
for a well or a code block, `--fill-field` for a box somebody types into, `--fill-hover` for a
row of yours under the pointer, and `--ink-heading`, `--ink-body` and `--ink-muted` for a
heading, for text somebody reads and for text held back. A role is what a style plugin answers, so
a page painted through one wears the appearance the project adopts later without a rule of yours
being edited. `contracts/design/roles.json` in the repository is one entry per role.

**The short names in `css/colors.css` are aliases over the palette**: `--crimson` and
`--gold` for the two accents with a soft wash beside each, `--danger`, `--success`,
`--warning` and `--info` for the four status colours with the same, and `--bone` and
`--mute` for text at full strength and held back. Both are legitimate, and the difference is what
happens when the appearance changes: a role follows the style plugin and an alias follows the
palette. Reach for a role when the thing you are drawing is furniture, and an alias when it is
voice.

**A role says which colour text takes, and a level says how far it is held back.** They are two
values and both are needed: under the appearance this package installs with, `--ink-muted` and
`--ink-body` resolve to the same colour, and what makes the held-back register held back is the
level mixed into it. Write it the way every component here writes it,
`color: color-mix(in oklab, var(--ink-muted) var(--level-ink-muted), transparent)`, with
`--level-ink-body` and `--level-ink-quiet` beside it. The levels are floors rather than
constants, and `arena-to-prod` raises one for a palette whose ink has too little room to clear its
contrast bar, so a percentage of your own is the one value here that cannot follow the palette. A
bare `var(--ink-muted)` paints at full strength, which is body copy wearing the name of a caption.

**The column is three classes and the air between two things is a named step.** `.arena-shell`
fills the window, `.arena-shell__main` goes on the one child that should take the slack, and
`.arena-band` centres the content at the page width with a gutter either side. Inside it,
`.arena-stack` is the step between two peers, `.arena-stack--group` the one for things that read
as one unit, `.arena-stack--section` the one between two sections, and `.arena-row` all three
laid across instead of down. Every one of them goes on a container of your own, and none of them
does anything on a component this package draws.

**`.arena-row` is for ANY two things side by side, and most of the misses are small ones.** A
mark beside the product's name, two links in a bar, a label next to the badge it describes, an
icon and the word after it: each is a row at the group step, and each is where a
`display: flex` with a gap of somebody's choosing gets written instead, because a pair of
elements does not look like it needs a class. It wraps when the line runs out, which is a
property of the class rather than the reason to reach for it.

**When the child that should take the slack IS a component this package draws, put a `<div>` of
your own around it and `.arena-shell__main` on the div.** A component's own element may declare
`display: contents` and carry no box, so the class lands on nothing and the shell distributes
its slack to an element that cannot hold it. The wrapper is not a workaround: these classes go on
markup you wrote, and that is as true of the one that grows as it is of the rest.

**The miss those replace has one shape, and it is small enough to look like nothing.** A column of
your own carrying `display: flex`, `flex-direction: column` and a gap, or two blocks with a
margin between them, holding a title over its service inside a table cell, or a label over the
value under it, written inline because reaching for a class felt like more than two lines were
worth. `.arena-stack--group` is exactly that block, and the step a group is spent at is the same
step wherever it is spent.

**The band carries the width and the gutter and no block air**, so the space above and below a
page's content column is yours, spent on the `--sp-*` scale. The rhythm classes answer the gap
between two siblings, and this is the padding of the box that holds them. The gutter is a CEILING
rather than a fixed inset: at or above the page width the band stands off by the whole of it, and
below that width it holds the same share of the space it has, so a phone keeps a content column
instead of spending two fifths of the screen on margin.

**Two densities, and each is a class on an ancestor rather than a member on anything.**
`.arena-compact` re-densifies the controls and the rows for a screen that has to hold more.
`.arena-comfortable` grows them to a 48px touch target for a screen a thumb drives. Both answer
the same keys, so a container wearing both gets whichever the stylesheet emits last, which is why
the two are exclusive. Each re-answers the control and row sizes and nothing
else: the rhythm above does not re-densify, so the air between two components stays where you
spent it.

<!-- @shared page end -->

<!-- @shared skin GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## Declare your skin

**A palette is not an appearance.** Arena keeps 72 questions about shape, space, weight and depth,
and the answers are a style plugin your project writes: the config below decides which colours a
surface takes and none of how round, how tight or how heavy the product is. That decision is paid
once per project and belongs before the first screen, and
`skills/design/references/style-kernel.md` in the repository is where it is made.

Write `arena.config.json` in your project root. This is the whole file, with one palette and
three fonts served by Google Fonts, and it is enough to start:

```json
{
  "palettes": [
    {
      "name": "dark",
      "default": true,
      "polarity": "dark",
      "colors": {
        "base-100": "#141010",
        "base-200": "#1d1715",
        "base-300": "#241c19",
        "base-content": "#f3ede5",
        "primary": "#b52a20",
        "primary-content": "#ffffff",
        "secondary": "#c5a059",
        "secondary-content": "#141010",
        "neutral": "#2c221e",
        "neutral-content": "#d8cfc4",
        "info": "#3182ce",
        "info-content": "#141010",
        "success": "#38a169",
        "success-content": "#141010",
        "warning": "#ecc94b",
        "warning-content": "#141010",
        "error": "#e85151",
        "error-content": "#ffffff",
        "error-fill": "#ce3838",
        "cat-1": "#3c7b0a",
        "cat-2": "#3b63be",
        "cat-3": "#0a924b",
        "cat-4": "#6a59bc",
        "cat-5": "#00a3c0",
        "cat-6": "#884da9",
        "cat-7": "#00a99a",
        "cat-8": "#984697"
      }
    }
  ],
  "fonts": {
    "display": { "family": "Archivo", "src": "https://fonts.googleapis.com/css2?family=Archivo:wght@400;500;600;700;800;900&display=swap" },
    "body": { "family": "Familjen Grotesk", "src": "https://fonts.googleapis.com/css2?family=Familjen+Grotesk:wght@400;500;600;700;800;900&display=swap" },
    "mono": { "family": "Spline Sans Mono", "src": "https://fonts.googleapis.com/css2?family=Spline+Sans+Mono:wght@400;500;600;700;800;900&display=swap" }
  },
  "stylePlugins": ["default"]
}
```

`arena.config.example.json` in this package is the same file with both Dravensoft palettes in
it, ready to copy and edit.

**`stylePlugins` is in that block because leaving it out is a decision and not a blank.** The
value above is the appearance this package installs with, which is Dravensoft's, and a project
that means to look like itself replaces it with the path to a plugin directory of its own. Both
are finished answers; only one of them is one somebody made.

What each part means:

- **`palettes`** is an array, so declare as many as you want. Exactly one is the `default` and
  reaches `:root`; every other one becomes a class, `.arena-<name>`, that you put on
  `<html>` to switch skin.
- **`polarity`** is `dark` or `light`. It decides the native date picker's colour and it is
  what a first visit matches `prefers-color-scheme` against.
- **`colors`** takes all 27 keys above. `error-fill` is the only optional one: leave it out and
  Arena darkens `error` in oklab for the single filled danger surface it has.
- **`cat-1`** through **`cat-8`** are the chart ramp. Their order is their identity, so slot 3
  is always slot 3, and they are never used to mean anything, only to tell series apart.
- **`fonts`** fills the three families Arena reads. `src` takes either a stylesheet URL, as
  above, or a font binary you host yourself, which becomes an `@font-face`:
  `{ "family": "Archivo", "src": "/fonts/archivo.woff2", "weight": "400 900" }`.
- **`stylesheet`** is optional and names what you render, so you send nothing else. See
  Build to production, below.
- **`stylePlugins`** names the appearance. **`["default"]`, or leaving the key out, is a
  finished answer** rather than a step somebody has not taken yet, and it is the right one for a
  first screen, for a prototype and for a tool nobody outside the team looks at. What it leaves
  unresolved is the appearance: the product wears the answers this package installs with, and every
  project stopping there looks like every other one. Writing one of your own is what makes the
  corners, the weights, the borders, the depth and the internal air the product's own, with no
  component rewritten to get there.
  It is a list, because a build can carry more than one register, and the first entry is what a page with no class on it looks
  like; every later one emits under `.arena-<name>` and is a difference. An entry is the word
  `default`, which is the appearance this package installs with, or a path to a directory of
  your own holding `plugin.tokens.json` and optionally `plugin.css`. The first entry answers
  every role Arena declares, and the command refuses one that does not: a custom property with no
  value is invalid at computed-value time, so an unanswered role is a missing border rather than
  a plainer look. Declare a list without `default` and you do not receive its stylesheet, the
  same way the preflight can already be dropped.
- **`gradientMark`** is optional, a boolean, and says the mark your product is drawn with is a
  gradient. Arena ships no element that is one, so yours lives in your own CSS, where `--audit`
  reports it: the scope reads which directory a line sits in, which is right for a part hook and
  wrong for a brand. Declare it once and that rule goes quiet in your sources; the colours inside
  the gradient are still reported, since they are the skin. It replaces an `arena-audit allow`
  marker, which silences every rule on its line and is repeated wherever the mark is drawn.

**A plugin carrying a `plugin.css` gets a third generated file**, `plugin.generated.css`, and
you import it beside the other two. It declares the cascade layer order itself and then opens
the reserved layer, so where your bundler places it among your other stylesheets cannot change
what wins.

<!-- @shared skin end -->

# Build to production

```bash
npx arena-to-prod                    # or: bunx / pnpm exec / yarn dlx
```

One command and no arguments. It reads `arena.config.json`, your `src` tree and every style
plugin directory that config declares, wherever those sit, and writes two files into `src`:

- **`arena.generated.css`**, your palettes and your `@font-face` rules, led by an `@import` of
  the package's own stylesheet. **This file is where every colour comes from**: the package
  declares no `--color-*` of its own, only the rules that read them, so the config and this
  command are how Arena gets a palette at all rather than a way to override one. The font roles
  are the half that is an override: the package declares them and your file, coming later at
  equal specificity in `:root`, wins.
- **`icons.generated.css`**, the class rules in `woff2` alone for every glyph your sources draw
  and every glyph Arena draws for you. It exists because Phosphor's own stylesheet declares a rule
  for every icon it has in every format it ships, and a screen draws a handful, which makes that
  sheet the largest stylesheet an Arena project would send that nothing on it reads. **The font
  binary is not cut down**: the `@font-face` it writes points at the weight Phosphor ships, so what
  a bundler copies is that whole file. Host a subset of your own there if the bytes matter, and the
  glyph list this file names is what to cut it to. Counting what Arena draws is the part you cannot
  do by hand: a component renders icons you never wrote, and leaving those out is an empty box
  in a menu you did not know had one. **The two halves are answered differently.** Your sources are
  read as text, because there is nothing else to read them by. Arena's half is not: the package
  ships `icons.json`, the list its own components draw, computed when the package was built from
  the renders themselves, so the command reads a list instead of searching this package for
  anything that looks like a class name. A search cannot tell a render from a sentence about one,
  and it is the glyph list that a self-hosted subset gets cut to. **Every glyph you name also reaches the filled weight**,
  whichever weight you wrote it beside, because a navigation item draws its active destination
  filled and asks for a rule you never wrote: name the glyph the way its member documents it,
  `icon="ph-bold ph-receipt"`, and the sheet has both.

A style plugin carrying a `plugin.css` gets a third file, **`plugin.generated.css`**, holding
that CSS wrapped in the reserved cascade layer. It leads with the layer order itself, so where
a build places it among your other stylesheets cannot change what wins.

Import them from `src/styles.css`, **last**:

```css
@import './icons.generated.css';
@import './arena.generated.css';
@import './plugin.generated.css';   /* only when a style plugin of yours carries CSS */
```

**The CDK overlay sheet comes with them.** `arena.css` imports `css/arena-cdk.css` itself, and a
`stylesheet` block carries it too, so there is no third line to add: it re-bases the CDK overlay
onto Arena's `--z-*` scale, without which a menu opened inside a dialog paints behind it. Write it
yourself only under `--no-import`, where you are importing the package sheet by hand.

| flag | what it does |
| --- | --- |
| `--audit` | Report where your own sources break a rule of the language: a class of yours on a component Arena draws, a stylesheet rule reaching an `arena-` slot, or one reaching a `data-arena-part` hook from outside a style plugin; an Arena component wrapped in your router's own link; a raw colour, a bare pixel length or a gradient where a token belongs, raw meaning a hex, channels or a name; an icon passed as an element; an emoji. **Every rule is read in a scope**: inside a directory your `stylePlugins` declares, a part hook is what you are meant to select and a gradient is yours to paint, so neither is reported there; the compiled `arena-` class name and a raw value are reported in both, because the hook is the contract and the class is output. The run also names the parts your plugins paint, which is where the evidence for promoting one into a role comes from. **No gate reads your application**, so this is the only automatic signal there is, and it is a report rather than a failure until you pass `--strict`. It decides only what source text shows, so it never claims to have checked one primary per view or a filled danger surface. **A comment is prose** and declares nothing, so a note about a value costs no allowance. Exempt a line it is wrong about with an `arena-audit allow` comment on that line, and it reports the allowance once there is nothing left on the line to exempt.  Reported for the templates it can read, the same way it reads your TypeScript. |
| `--undrawn` | Name the components this package ships that your sources draw nowhere. It is the answer to "which of them have I not used yet", and it walks your sources a second time to answer it, which is the only flag here that costs a pass of its own. A component Arena draws on your behalf counts as undrawn, because you never wrote it. |
| `--strict` | Exit 1 on a report rather than writing anyway. Bare, it holds every kind; `--strict=contrast,audit` holds the kinds you name, out of `components`, `contrast`, `ramp`, `weight`, `glyph`, `markers`, `audit`, `environment` and `restated`. **Name them when one of them is a decision you already made**: a brand under 4.5:1 is measured and deliberate, and one switch over all of them would make it the price of holding the rest in CI. `environment` says the run is outside an Arena package, so Arena's own icons went uncounted; `weight` says a role asks for a weight the face you loaded does not carry, so the browser draws it by smearing the nearest one; `wash` is the one kind `--strict` never holds: a token on a wash of its own colour clears AA at no percentage, and a build nobody can fix is not a gate; `restated` says a plugin rule restates the value that part's slot already paints, so it changes nothing. |
| `--skill`, `--skill-check` | Write the discovery record every IDE agent scans for, `.agents/skills/arena/SKILL.md`, and do nothing else: no config is read and no stylesheet is written, because a project that wants the language has no reason to own an `arena.config.json` yet. **The record is not a copy of the language**: the corpus travels inside this package and the record routes into it, so an agent reads the rules, the style kernel and every component's usage document with no clone and no network. `--skill=.github/skills` writes a different scanned location, `--global` writes one for every project you open, and `--vendor` copies the documents beside the record for a tree where `node_modules` is not checked out. `--skill-check` reads it back and reports that it is absent, that another version of this package wrote it, that it was edited by hand, or that a document it routes to is not there; `--strict=skill` makes any of those fatal. **It is the only thing in Arena that reads your project**, and it reads only this one file. |
| `--no-import` | Omit the `@import` of the package stylesheet, for when you would rather import `@dravensoft/arena-angular/arena.css` yourself. |
| `--config`, `--src`, `--out` | The config file, the trees to scan and where the two files go. They default to `arena.config.json`, `src` and `src`. **`--src` is repeatable and names the trees of your own**, and a style plugin is not one of them: a directory your `stylePlugins` declares is resolved from the config and walked wherever it lives, so every scope rule in the `--audit` row reaches it whether or not it sits under `src`. One command and no arguments is the whole of it, and a plugin in `design/` costs nothing to remember. |

**One report needs no flag, because it runs on every pass: a projection marker you write and do
not import.** A slot such as `[footer]` or `[actions]` is gated on a query for its directive, so a
template that writes the attribute without listing `ArenaFooter` in its own `imports` renders
nothing there, and neither the build nor `ngc --strictTemplates` says a word. It is named on
stderr. This is the one defect a component cannot report about itself.

**It reports rather than refuses.** If a text colour lands under 4.5:1, if two ramp slots are
too close to tell apart with a common colour vision deficiency, or if you name a glyph Phosphor
does not have, it says so on stderr and writes the files anyway. Your brand is yours; Arena's
job is to tell you what it costs. A malformed config is a different matter and always fails,
naming the key.

**`stylesheet` in `arena.config.json` is how you pay for only what you render.** Set
`"components": "auto"` and the command reads your templates and works the list out:

```json
{ "stylesheet": { "components": "auto", "preflight": false } }
```

It counts a component as drawn when its element appears in a template, and it adds what Arena
draws on your behalf, because `<arena-table>` renders a pagination and a select you never wrote.
It prints both counts, and names on stderr any `arena-` element it saw and could not place.
`preflight: false` is separate: set it when your project already ships an equivalent browser
reset.

**What a scan cannot see, it cannot send.** A component reached only through a value your code
computes is a component this misses, and a missing sheet renders with no border, no padding and
no colour, with nothing to tell you. Naming the sheets yourself is still there, and is the honest
choice for a project that renders through indirection:

```json
{ "stylesheet": { "components": ["arena-button", "arena-page-head", "arena-side-nav", "arena-stat-card", "arena-table"] } }
```

A name this package does not ship fails the command and lists the ones it does, so a typo stops
the build instead. That list is then yours to keep current.

## Run it before your build

```json
{
  "scripts": {
    "prebuild": "arena-to-prod",
    "prestart": "arena-to-prod"
  }
}
```

Both bun and npm run a `pre<name>` script ahead of the script it names, so wiring it once is
what keeps the two files from ever going stale. They are build products of your config and your
sources, so ignore them in version control the way you ignore the rest of your build.

## Switch palettes

```ts
import { provideArenaThemes, ArenaThemeService } from '@dravensoft/arena-angular';

bootstrapApplication(App, {
  providers: [
    provideArenaThemes({
      palettes: [
        { name: 'dark', polarity: 'dark' },
        { name: 'light', polarity: 'light' },
      ],
      default: 'dark',
    }),
  ],
});
```

Pass the same palettes your config declares. Then inject `ArenaThemeService` and call `set('light')`,
or `toggle()` to walk them in order. `theme` is a signal, so a template reads it directly. With
no providers the service answers `dark` and `light`.

To avoid a flash on first paint, apply the class in `index.html` before your stylesheet:

```html
<script>
  (function () {
    var PALETTES = [               // every palette your arena.config.json declares, in its order
      { name: 'dark', polarity: 'dark' },
      { name: 'light', polarity: 'light' }
    ];
    var DEFAULT = 'dark';          // the palette your arena.config.json marks default
    try {
      var name = localStorage.getItem('arena-theme');
      if (!name) {
        var wants = window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
        for (var i = 0; i < PALETTES.length; i++) {
          if (PALETTES[i].polarity === wants) { name = PALETTES[i].name; break; }
        }
      }
      if (name && name !== DEFAULT && /^[a-z][a-z0-9-]*$/.test(name)) {
        document.documentElement.classList.add('arena-' + name);
      }
    } catch (e) {}
  })();
</script>
```

Set the list to your own palettes and `DEFAULT` to the one your config marks default. Those are the
same two values the theme surface takes, so a build carrying three or four palettes states them once
and the snippet cannot drift from the app. The default reaches `:root` and wears no class, so a
snippet naming the wrong one puts a class on the very palette that must not have it. **The media query is
the half a stored-value-only snippet gets wrong**: on a first visit nothing is stored, the theme
surface falls back to the first palette whose polarity matches the device, and a snippet that
reads only storage paints the default first and is corrected after the app boots, which is the
flash it exists to prevent.

## What the package ships besides the components

Every component is standalone, so import the ones a template uses. **A parent does not bring its
children with it**: a table wants `ArenaTableRow` and `ArenaTableCell` in the same `imports` array,
and so does every other family whose parts are separate elements. Everything else that reaches the
package root is below, each answering a question a consumer cannot answer from outside.

**The projection markers, and they are not optional.** Ten directives stand behind ten
attributes: `ArenaAction` behind `[action]`, `ArenaActions` behind `[actions]`, `ArenaBrand`
behind `[brand]`, `ArenaFooter` behind `[footer]`, `ArenaSecondaryAction` behind
`[secondaryAction]`, `ArenaFigureSlot` behind `[figure]`, `ArenaMedia` behind `[media]`,
`ArenaFallback` behind `[fallback]`, `ArenaOverlay` behind `[overlay]` and `ArenaNav` behind
`[nav]`. **`ArenaFigureSlot` is the one whose name is not its attribute capitalised**, because
`ArenaFigure` is the component that holds the slot. **Put the marker your
template writes in that component's own `imports`.** A component detects a projected slot with a
`contentChild` on the directive, so an un-imported marker leaves the query null and the slot
silently unrendered: no error and no template diagnostic, because a bare `footer` attribute on a
`<div>` is valid HTML whether or not a directive matches it. The component cannot tell an
un-imported marker from an unfilled slot, so nothing can warn you.

| export | what it is |
| --- | --- |
| `provideArenaThemes`, `ArenaThemeService`, `arenaThemeClass`, `ArenaPalette`, `ArenaThemeConfig` | the theme surface above |
| `arenaContainerWidth(target?)` | `Signal<number \| null>` over the host's own box, or the `ElementRef` you pass. For a component or a panel that has to fit the room it was given. **The width is `null` until the first measurement**, so render the wide branch while it is: a panel that flashes into its phone shape on every mount is worse than one that settles into it |
| `arenaViewportBelow(name)` | `Signal<boolean>` over `not all and (min-width: N)`, where `name` is `'sm' \| 'md' \| 'lg'` and resolves the same `--bp-*` token Arena's own components branch on. For a page's own layout, and **never for a component**: that is wrong the first time somebody puts it in a narrow column. Call `forgetArenaBreakpoints()` if your app swaps its stylesheet at runtime |
| `arenaCatColor(slot)`, `arenaCatSurface(slot)`, `arenaCatTint(colour)`, `arenaCatSlotFor(key)`, `ARENA_CAT_SLOTS` | the chart ramp, for a legend or a chip you draw yourself. The ramp's order is its identity, so a slot means the same thing in every chart on the screen. `arenaCatTint` is the soft surface an identity colour stands on, over whatever answers `fill-surface`; it takes a colour, not a slot, and fills `arenaCatSurface` |
| `ArenaToastQueue` | the notice queue, provided in root: it holds their identity and their order, and runs the clock `arena-toast-host` deliberately does not own. `raise(notice)` returns an id, `dismiss(id)` takes one away, and `toasts` is the signal you render into the host. The three-branch dismissal rule is inside it, including the one invisible in a signature: a `danger` notice is never put on a timer, and it ignores a `persist` of false |
| `arenaToastDelay(notice, dismiss)` | that rule on its own, for a queue of your own: the interval a notice runs on, or `null` when it must not be taken away |
| `isArenaPrimaryActivation(event)` | the predicate behind the anchor rule: true for a primary click with no modifier, false for every modified click, middle click and context menu |
| `isArenaOwnActivation(target, container)` | true when an activation landed on the container itself rather than on a link, a button, a field or any other interactive element inside it: the predicate that lets a clickable row hold a checkbox and a row action without taking their presses |
| `arenaFocusableElements(container)`, `arenaFocusFirstFocusable(container)`, `arenaTrapTabKey(container, event, activeElement)`, `arenaHandleOpenTransition(state, isOpen, panel, activeElement)` | the modal contract, for an overlay Arena does not ship. Arena's own dialogs run on these, so a lightbox or a viewer of yours traps Tab, takes focus on open and restores the invoker on close by the same code rather than by a second one written from memory. This is the surface to reach for whenever the answer is that the markup is yours |
| `arenaToneColor(tone)` | the colour a status tone resolves to, for a shape you draw yourself and want to keep meaning what the components mean by it. Status colours are meaning and the chart ramp is identity, so this is never a series colour |
| `ARENA_MAIN_ID` | the id `arena-main` writes on its landmark and `arena-skip-link` points at, as a string. A page has one main region, so the id is a constant rather than something coordinated at the call site: read it when you write a second route into the content, an anchor of your own or a test that has to find the region |
| `ARENA_SR_ONLY` | the style object that hides an element from sight and keeps it for a screen reader, for markup of yours that needs a label the design does not show. `css/sr-only.css` is the same thing as a class |

### The `<head>` is a second entry point, and the router is why

`provideArenaMetadata()` is the one thing this package does not ship from `@dravensoft/arena-angular`.
It lives at `@dravensoft/arena-angular/metadata`, because reaching it means reaching
`@angular/router`, which is an **optional** peer: a project that never imports that subpath never
installs it and nothing else here moves.

```ts
import { provideArenaMetadata, arenaRouteMeta } from '@dravensoft/arena-angular/metadata';

bootstrapApplication(App, {
  providers: [
    provideRouter(routes),
    provideArenaMetadata({ suffix: 'Andina', origin: 'https://andina.example', siteName: 'Andina' }),
  ],
});

export const routes: Routes = [
  { path: 'orders', title: 'Orders', component: Orders,
    data: arenaRouteMeta({ description: 'Every order in the system.', robots: 'index,follow' }) },
  { path: 'cash', title: 'Cash', component: Cash },
];
```

It composes on Angular's own `title:` rather than competing with it, through the `TitleStrategy`
Angular defines for exactly this, so `title: 'Orders'` keeps meaning what it meant and gains a
suffix, a description, a canonical and the `og:*` pair beside it.

**A route is not indexed until it says it is.** `robots` defaults to `noindex`, so `cash` above is
private without anybody remembering to make it so and `orders` is public because it said so. Its
absence does not announce itself until a cash-register screen turns up in a search result. The
same key on `provideArenaMetadata` moves the default for the whole application, and a route still
outranks it.

**Without `origin` there is no canonical and no `og:url`, deliberately.** An origin read off
`window.location` differs between a server render and the client that hydrates it, which is the
one hazard a `<head>` writer can introduce and never see, so a project that wants a canonical says
where it lives. The fragment is dropped from it, and a route whose canonical is not the url it was
reached by says so with `canonical`.

| export | what it is |
| --- | --- |
| `provideArenaMetadata(config?)` | the provider, returning `EnvironmentProviders` because a `TitleStrategy` is the application's and not one component's. Takes `suffix`, `separator`, `origin`, `robots`, `description`, `image` and `siteName`, each a default a route can outrank |
| `arenaRouteMeta(meta)` | a route's own `description`, `robots`, `image`, `type` and `canonical`, under one key of the `data` that is yours. Typed, because `Route.data` is not: written flat, a misspelled `descripton` is a metadatum that never appears and nothing that fails. A deeper route wins a key and keeps what it did not name, so a layout route sets what its section shares |
| `ArenaMetadataService` | the writer itself, one method, `apply(page)`. Call it for a page whose metadata is not a fact about the route: a detail screen described by the record it just loaded |
| `ArenaTitleStrategy` | the strategy the provider installs, exported so one of your own extends it rather than replaces it |

Call either measurement from an injection context, a field initializer or the constructor:
`DestroyRef` disconnects the observer and `afterNextRender` decides when there is a box to
measure at all. Every other symbol reaching the root is an internal of this layer, exported
because the barrel is not curated, and carries no compatibility promise. It carries the prefix
too, since the convention is about the name and not about the promise, so reading `Arena` on a
symbol tells you where it comes from and never that it is yours to depend on.

The stylesheets are a tree, and you pick your depth. `arena.css` is all of it and the
zero-friction path:

| stylesheet | what it is |
| --- | --- |
| `css/base.css` | Tailwind's preflight and nothing of Arena's. Arena needs one: without `button, input, select, textarea { font: inherit }` a control falls back to the browser's 13.33px Arial and every control in the library is 20% off, with nothing to tell you. Keep yours or keep this one, but keep one |
| `css/components.css` | every component Arena draws |
| `css/components/<name>.css` | one component, named for its sheet as `arena-button.css` or `arena-stat-card.css`. Each imports the prelude it needs itself, so importing one alone is safe |
| `css/numerals.css` | `.arena-num`, the mono face and `tabular-nums` and no colour. Put it on a figure you draw yourself and a column of them aligns by digit the way a table's does |
| `css/sr-only.css` | `.arena-sr-only`, a label a screen reader announces and nothing paints. Put it on the name of an icon-only control you drew yourself. It is here so the one-pixel clip box is never written into a sheet of yours, where a raw length is what it looks like |
| `css/page.css` | `.arena-shell` and `.arena-band`, the column your page sits in: a shell that fills the window so a footer never floats halfway up it, `.arena-shell__main` on the one child that should take the slack, and a band that centres its contents at the page width with a gutter either side. Both lengths are the same pair a style plugin re-answers, so one written for reading narrows the page you already shipped |
| `css/prose.css` | `.arena-prose`, the width of a reading column as a measure in `ch` rather than a pixel width, so it tracks the font size the way a measure has to. Put it on an article or a section you wrote; a style plugin written for reading narrows it and every page you already shipped follows |
| `css/rhythm.css` | `.arena-stack` and `.arena-row`, the air between components as named steps rather than a number you pick. A stack is a column: `.arena-stack` alone is the step between two peers, `.arena-stack--group` the one for things that read as one unit, `.arena-stack--section` the one between two sections of a page. A row is a wrapping line, grouped by default, and `.arena-row--component` opens it to the wider step. The modifiers that carry no length line the items up instead: `.arena-stack--start`, `.arena-stack--end`, `.arena-row--start`, `.arena-row--baseline` and `.arena-row--between`. Put one on a container of your own, which is where your layout goes anyway |
| `css/arena-cdk.css` | the CDK overlay, re-based onto Arena's layering |

**The rest of what ships under `css/` is not a choice.** The token layer is six sheets,
`css/reset.css`, `css/typography.css`, `css/spacing.css`, `css/effects.css`, `css/colors.css` and
`css/environment.css`, which `arena.css` imports in the order they have to be in, and
`css/prelude.css` is what a single component sheet pulls in for itself. The one that IS a decision
is `css/style-plugin-default.css`, the appearance this package installs with: it arrives through
`arena.css` like the rest, and a `stylePlugins` list of your own that does not name `default` does
not receive it, which is the point of writing one.

Importing the halves rather than `arena.css` makes **order** yours: Arena's components have to
come before your own rules if you want yours to win. There is nothing to compile either way: no
file in this package carries a Tailwind class, so pointing a `@source` at it produces an empty
sheet.

<!-- @shared tail GENERATED by bun run generate:npm-pages. Edit that script, not this copy. -->

## Why might this package's latest version not match Arena's latest version?

[Why are the published package versions not identical?](https://github.com/dravensoft-dev/arena/blob/main/.github/workflows/AGENTS.md#why-are-the-published-package-versions-not-identical)

## License

MIT. See the repository.

<!-- @shared tail end -->


<!-- frameworks/angular/components/brand/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena brand components, the Angular layer

Every brand component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaAppLogo` | Brand lock-up: a mark beside or above a product name. | `mark*` `name*` `dim` `size` `orientation` | [`ArenaAppLogo.prompt.md`](./arena-app-logo/ArenaAppLogo.prompt.md) |

1 brand components in this layer.


<!-- frameworks/angular/components/charts/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena charts components, the Angular layer

Every charts component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaBarChart` | Categorical bars on one axis. Dependency-free SVG that reads the token layer directly, with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `stack` `valueSuffix` `valuePrefix` `valueFormat` `height` `minPointSpacing` | [`ArenaBarChart.prompt.md`](./arena-bar-chart/ArenaBarChart.prompt.md) |
| `ArenaChartCard` | A titled card frame around a chart, with an optional actions slot in its head. | `title` `headingLevel` `actions` `content` | [`ArenaChartCard.prompt.md`](./arena-chart-card/ArenaChartCard.prompt.md) |
| `ArenaDoughnutChart` | Parts of one whole, as a ring with a legend beside it. Identity only: a slice is a category by definition, so there is no tone. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `valueSuffix` `valuePrefix` `shape` `legendLayout` `sliceActivate` `valueFormat` | [`ArenaDoughnutChart.prompt.md`](./arena-doughnut-chart/ArenaDoughnutChart.prompt.md) |
| `ArenaHorizontalBarChart` | Categorical bars running across the plot, with the categories down its left edge. The same data and the same table as ArenaBarChart with the axes transposed, which is a different component rather than an orientation flag because transposing changes what four of its members mean: the cursor answers the vertical arrows, the category gutter is its own token, height becomes the axis the data grows along, and there is no scrolling rail. | `labels*` `series*` `label*` `stack` `valueSuffix` `valuePrefix` `valueFormat` `height` | [`ArenaHorizontalBarChart.prompt.md`](./arena-horizontal-bar-chart/ArenaHorizontalBarChart.prompt.md) |
| `ArenaLineChart` | One series over an ordered sequence, on one axis. Dependency-free SVG with a crosshair that snaps to the nearest point, and a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `area` `curve` `valueSuffix` `valuePrefix` `valueFormat` `height` `minPointSpacing` | [`ArenaLineChart.prompt.md`](./arena-line-chart/ArenaLineChart.prompt.md) |
| `ArenaPyramidChart` | A population pyramid: two counts per band, mirrored about a shared centre line, with the band names down the left edge. Diverging from a centre is the whole point rather than an option, which is why the two-series rule and the mirrored axis are the component instead of a flag on a bar chart. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `valueSuffix` `valuePrefix` `valueFormat` `height` | [`ArenaPyramidChart.prompt.md`](./arena-pyramid-chart/ArenaPyramidChart.prompt.md) |
| `ArenaRadarChart` | Several measures on one shape: an axis per label around a polar grid, one closed polygon per series. Reads a profile rather than a magnitude, which is what makes it a different chart from bars over the same numbers. Dependency-free SVG with a visually-hidden table of the same numbers. | `labels*` `series*` `label*` `fill` `valueSuffix` `valuePrefix` `valueFormat` `height` | [`ArenaRadarChart.prompt.md`](./arena-radar-chart/ArenaRadarChart.prompt.md) |
| `ArenaScatterChart` | Two quantities against each other, one mark per pair, and a third as the mark's size when a series carries one. The first chart here whose horizontal axis carries a value rather than a position, which is why it takes a series of parallel measurements and names every axis it draws. Dependency-free SVG with a visually-hidden table of the same numbers. | `series*` `label*` `xLabel*` `yLabel*` `sizeLabel` `sizeLegend` `valueSuffix` `valuePrefix` `valueFormat` `height` | [`ArenaScatterChart.prompt.md`](./arena-scatter-chart/ArenaScatterChart.prompt.md) |

8 charts components in this layer.


<!-- frameworks/angular/components/display/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena display components, the Angular layer

Every display component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaActivityFeed` | An event feed: someone did something to something, then. Arena draws every row. | `label*` `items*` `busy` | [`ArenaActivityFeed.prompt.md`](./arena-activity-feed/ArenaActivityFeed.prompt.md) |
| `ArenaAvatar` | A person or entity mark: the image when `src` is set, initials from `name` otherwise, with an optional presence dot. | `src` `name` `size` `shape` `status` | [`ArenaAvatar.prompt.md`](./arena-avatar/ArenaAvatar.prompt.md) |
| `ArenaBadge` | Status label: mono, uppercase, short. Carries an object's actual state or an editorial emphasis, never decoration. | `content` `tone` `dot` | [`ArenaBadge.prompt.md`](./arena-badge/ArenaBadge.prompt.md) |
| `ArenaCalendar` | Week or day schedule on a time grid. Colour is identity, never state. | `content` `timeZone` `anchorDate` `view` `dayStart` `dayEnd` `weekStartsOn` `hideEmptyWeekend` `dayInteractive` `dateClick` `rangeChange` `actions` | [`ArenaCalendar.prompt.md`](./arena-calendar/ArenaCalendar.prompt.md) |
| `ArenaCalendarEvent` | One event on an ArenaCalendar's schedule. Times are ISO datetimes read in the calendar's timeZone, never the reader's. ArenaCalendar draws the chip; the consumer writes one of these per event and ArenaCalendar settles where it goes. | `id*` `title*` `start*` `end*` `colorId` `interactive` `actionsEnabled` `actions` `disabled` `click` | [`ArenaCalendarEvent.prompt.md`](./arena-calendar-event/ArenaCalendarEvent.prompt.md) |
| `ArenaCard` | Surface container. Hairline border on the base surface scale; depth comes from the shadow, never a gradient. | `content` `interactive` `disabled` `href` `action` `title` `headingLevel` `eyebrow` `floating` `accent` `click` | [`ArenaCard.prompt.md`](./arena-card/ArenaCard.prompt.md) |
| `ArenaKeyValue` | A list of terms and the values against them, with an optional summed row ruled off at the bottom: a basket summary, an order, an invoice, a panel of facts about a resource. It renders a real definition list, so the association between a term and its value is the platform's rather than a class name's. | `rows*` `total` | [`ArenaKeyValue.prompt.md`](./arena-key-value/ArenaKeyValue.prompt.md) |
| `ArenaPeopleList` | A list of people, each row a face with a name and, where the list is about a quantity, a figure beside it. Standings, assignees, members, suggestions. The list owns the semantics and the row size; a row owns what it says. | `label*` `ordered` `size` `content` | [`ArenaPeopleList.prompt.md`](./arena-people-list/ArenaPeopleList.prompt.md) |
| `ArenaPersonRow` | One person in an ArenaPeopleList: a face, a name, an optional line under it, an optional position in front and an optional figure behind. Its size comes from the list rather than from here. | `name*` `src` `secondary` `rank` `figure` `current` `action` | [`ArenaPersonRow.prompt.md`](./arena-person-row/ArenaPersonRow.prompt.md) |
| `ArenaSkeleton` | A loading placeholder that reserves the space real content will take. | `variant` `width` `height` `lines` `radius` | [`ArenaSkeleton.prompt.md`](./arena-skeleton/ArenaSkeleton.prompt.md) |
| `ArenaStatCard` | One metric on a card surface: a micro-label, the number, an optional delta pill and a sub-line. | `label*` `value*` `tone` `delta` `sub` `icon` | [`ArenaStatCard.prompt.md`](./arena-stat-card/ArenaStatCard.prompt.md) |
| `ArenaTable` | Data table on the density tokens. ArenaTable draws the header row from `columns`, owns the grid and its keyboard, and decides where each row sits; the consumer writes one ArenaTableRow per row and one ArenaTableCell per cell, so a cell's content is a value or one of Arena's own components rather than something returned from a per-item render function. Below --bp-md it becomes one card per row, measured on its own container rather than the viewport. | `label*` `columns*` `content` `empty` `sort` `sortChange` `page` `slice` `pageChange` `pageControl` `sortControl` `responsive` | [`ArenaTable.prompt.md`](./arena-table/ArenaTable.prompt.md) |
| `ArenaTableCell` | One cell of an ArenaTableRow. It draws the cell box (the padding, the alignment and the mono/gold treatment its column asks for, and in card mode the label/value pair or the full-width block), and shows whatever the consumer put in it. Its column config, its layout and its place in the grid's keyboard order come from ArenaTable and ArenaTableRow and are members of no contract. | `content` `href` `navigate` | [`ArenaTableCell.prompt.md`](./arena-table-cell/ArenaTableCell.prompt.md) |
| `ArenaTableRow` | One row of an ArenaTable. The consumer writes one per row and one ArenaTableCell inside it per cell. Where the row sits, the columns its cells are set against and how the keyboard reaches them are ArenaTable's, not this component's, and are members of no contract: the same shape, and for the same reason, as an ArenaRadioGroup and its Radios sharing which one is checked. | `content` `interactive` `disabled` `click` | [`ArenaTableRow.prompt.md`](./arena-table-row/ArenaTableRow.prompt.md) |
| `ArenaTag` | A pill for filters, technologies and statuses. A tone for what state a thing is in or a ramp slot for which thing it is, and an optional dismiss. | `content` `tone` `colorId` `removable` `disabled` `remove` | [`ArenaTag.prompt.md`](./arena-tag/ArenaTag.prompt.md) |
| `ArenaUnauthCard` | The panel a signed-out screen needs: sign in, check your inbox, this link expired, a two-factor code. It knows nothing about credentials on purpose; the fields are composed inside it. | `brand` `eyebrow` `title` `headingLevel` `content` `footer` | [`ArenaUnauthCard.prompt.md`](./arena-unauth-card/ArenaUnauthCard.prompt.md) |

16 display components in this layer.


<!-- frameworks/angular/components/feedback/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena feedback components, the Angular layer

Every feedback component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaAlert` | A tone-coloured message with an optional icon, a single action, and optional dismissal. | `tone` `title` `content` `icon` `actionLabel` `action` `dismissible` `close` | [`ArenaAlert.prompt.md`](./arena-alert/ArenaAlert.prompt.md) |
| `ArenaConfirmDialog` | Confirmation of a high-consequence action. Never closes on click-outside. `requireText` locks the confirm button until a word is typed. | `open*` `title*` `eyebrow` `content` `confirmLabel` `cancelLabel` `destructive` `requireText` `cancel` `confirm` | [`ArenaConfirmDialog.prompt.md`](./arena-confirm-dialog/ArenaConfirmDialog.prompt.md) |
| `ArenaDialog` | Modal dialog over a blurred scrim. Takes the whole interaction until dismissed. | `open*` `title*` `eyebrow` `width` `content` `footer` `close` | [`ArenaDialog.prompt.md`](./arena-dialog/ArenaDialog.prompt.md) |
| `ArenaEmptyState` | A placeholder for an empty collection: an icon, a title, a message, and an optional action. | `icon` `title*` `headingLevel` `message` `action` | [`ArenaEmptyState.prompt.md`](./arena-empty-state/ArenaEmptyState.prompt.md) |
| `ArenaErrorState` | Section/screen-level failure, with recovery and an optional diagnostic code. | `icon` `title` `headingLevel` `message` `code` `retryLabel` `retry` `secondaryAction` | [`ArenaErrorState.prompt.md`](./arena-error-state/ArenaErrorState.prompt.md) |
| `ArenaOnboarding` | Guided coachmark tour (H10): presents features within the product with progress dots, Skip and Next. Controlled: the host owns index and answers the four events. | `open*` `steps*` `index` `anchor` `next` `back` `skip` `done` | [`ArenaOnboarding.prompt.md`](./arena-onboarding/ArenaOnboarding.prompt.md) |
| `ArenaProgressBar` | Determinate progress by default; indeterminate for a wait with no percentage. A bar along a row, or a ring with the figure inside it. | `content` `progressPercentage` `indeterminate` `tone` `label*` `showLabel` `showPercentage` `size` `shape` | [`ArenaProgressBar.prompt.md`](./arena-progress-bar/ArenaProgressBar.prompt.md) |
| `ArenaSheet` | A non-modal panel anchored to one edge of the page: a cart, a filter drawer, a detail pane. It carries no scrim, traps no focus and takes nothing away from the page behind it, which is the whole difference from a dialog. Its header stays on screen while its body folds away, so a reader keeps the panel without keeping its bulk. | `open*` `placement` `title*` `collapsed` `collapsedChange` `dismissible` `close` `content` `footer` | [`ArenaSheet.prompt.md`](./arena-sheet/ArenaSheet.prompt.md) |
| `ArenaSpinner` | Indeterminate wait indicator. For a measurable process use ArenaProgressBar instead. | `size` `tone` `label` | [`ArenaSpinner.prompt.md`](./arena-spinner/ArenaSpinner.prompt.md) |
| `ArenaToast` | Ephemeral notification with a tone-coloured side bar and one optional action. | `title` `message` `tone` `actionLabel` `action` `persist` `dismissible` `close` | [`ArenaToast.prompt.md`](./arena-toast/ArenaToast.prompt.md) |
| `ArenaToastHost` | The fixed box a stack of notices renders into. It decides where the stack sits, how far it stands off the viewport edges and how much air separates two notices, and it decides nothing else: it reads no notice, counts none, and owns no clock. | `placement` `content` | [`ArenaToastHost.prompt.md`](./arena-toast-host/ArenaToastHost.prompt.md) |
| `ArenaTooltip` | A short label revealed on pointer intent. Bone over dark for contrast. It waits before appearing and before withdrawing, so a pointer crossing a toolbar reveals nothing. | `label*` `content*` | [`ArenaTooltip.prompt.md`](./arena-tooltip/ArenaTooltip.prompt.md) |

12 feedback components in this layer.


<!-- frameworks/angular/components/forms/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena forms components, the Angular layer

Every forms component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaButton` | Action button. One primary per view; danger stays outline. | `content` `variant` `size` `icon` `iconRight` `loading` `full` `disabled` `type` `name` `value` `autoFocus` `form` `tabStop` `click` | [`ArenaButton.prompt.md`](./arena-button/ArenaButton.prompt.md) |
| `ArenaCheckbox` | A single checkbox. Checked shows a crimson fill with a check. | `checked` `label` `disabled` `required` `name` `value` `change` | [`ArenaCheckbox.prompt.md`](./arena-checkbox/ArenaCheckbox.prompt.md) |
| `ArenaIconButton` | Icon-only button. Carries an accessible name in every state, not only on hover. | `icon*` `label*` `size` `variant` `showLabel` `pressed` `disabled` `type` `name` `value` `autoFocus` `form` `tabStop` `click` | [`ArenaIconButton.prompt.md`](./arena-icon-button/ArenaIconButton.prompt.md) |
| `ArenaInput` | Text field with validation. Focus is a gold ring; error crimson; valid green with a check. The four states are ordered and the order is normative: error, then focus, then valid, then neutral: an errored field stays crimson while it has focus, because the validation signal must not disappear at the moment the user acts on it. | `label` `id` `hint` `error` `valid` `required` `validate` `validateOn` `type` `icon` `prefix` `value` `disabled` `readOnly` `placeholder` `name` `autoComplete` `min` `max` `step` `maxLength` `pattern` `change` `blur` | [`ArenaInput.prompt.md`](./arena-input/ArenaInput.prompt.md) |
| `ArenaRadio` | One option inside an ArenaRadioGroup. Selected shows a crimson dot inside the ring. | `value*` `label` `hint` `disabled` | [`ArenaRadio.prompt.md`](./arena-radio/ArenaRadio.prompt.md) |
| `ArenaRadioGroup` | Single-selection group. Governs the value and distributes it to its child Radios. | `ariaLabel*` `content` `value` `name` `change` | [`ArenaRadioGroup.prompt.md`](./arena-radio-group/ArenaRadioGroup.prompt.md) |
| `ArenaSelect` | Styled native dropdown selector, with the same validation vocabulary ArenaInput carries. The four states are ordered and the order is the same normative one: error, then focus, then valid, then neutral -- an errored control stays crimson while it has focus, because the validation signal must not disappear at the moment the user acts on it. A form that mixes ArenaInput and ArenaSelect is a form whose fields must report a failure the same way, or it gets validated by hand or not at all. | `label` `placeholder` `options` `value` `disabled` `required` `hint` `error` `valid` `icon` `name` `change` | [`ArenaSelect.prompt.md`](./arena-select/ArenaSelect.prompt.md) |
| `ArenaSwitch` | A controlled on/off switch showing an icon per state. `confirm` gates a high-impact change through an ArenaConfirmDialog before it applies. | `state` `orientation` `size` `iconOn` `iconOff` `label*` `disabled` `confirm` `funcOn` `funcOff` `requestChange` | [`ArenaSwitch.prompt.md`](./arena-switch/ArenaSwitch.prompt.md) |
| `ArenaTextarea` | Multi-line text field with validation and an optional counter. | `label` `id` `hint` `error` `required` `counter` `autoResize` `value` `disabled` `readOnly` `placeholder` `name` `maxLength` `rows` `change` | [`ArenaTextarea.prompt.md`](./arena-textarea/ArenaTextarea.prompt.md) |

9 forms components in this layer.


<!-- frameworks/angular/components/layout/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena layout components, the Angular layer

Every layout component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaBoard` | The frame of a board: columns side by side, as wide as the room allows and never narrower than one column's minimum, scrolling sideways when they no longer fit. It is one tab stop carrying a group role and a name, which is what a scrolling region needs to be reachable by keyboard at all. It draws no card and moves nothing: what a column holds is the consumer's, and reordering is theirs too. | `label*` `content*` `minColumn` | [`ArenaBoard.prompt.md`](./arena-board/ArenaBoard.prompt.md) |
| `ArenaBoardColumn` | One column of an ArenaBoard: a named head with a count and a control, a stack of whatever the consumer puts in it, and a footer for the one action that adds to it. The cards are the consumer's own, because a card on a board carries that product's fields and nothing general is left once they are removed. | `title*` `headingLevel` `count` `summary` `colorId` `action` `content` `footer` | [`ArenaBoardColumn.prompt.md`](./arena-board-column/ArenaBoardColumn.prompt.md) |
| `ArenaFigure` | A framed piece of media with an optional caption: an image, a video, or a stand-in for the one that has not arrived. The frame is a shape and a corner a style plugin answers, and it clips whatever is put in it, so a wall of figures reads as a wall rather than as whatever sizes the pictures happened to be. | `media` `fallback` `overlay` `caption` `ratio` | [`ArenaFigure.prompt.md`](./arena-figure/ArenaFigure.prompt.md) |
| `ArenaGrid` | A grid that decides its own column count from the room it is given, rather than from a breakpoint anyone had to pick. Cells are as wide as they can be at or above a minimum, and the count falls as the room does, all the way to one. | `min` `gap` `maxWidth` `content` | [`ArenaGrid.prompt.md`](./arena-grid/ArenaGrid.prompt.md) |
| `ArenaHero` | The opening of a landing page: one line the page is built around, what sits above and below it, the actions it asks for, and a figure beside or behind it. Its title takes the hero register, which is the top rung of the title ladder and the only one above the page head. | `title*` `headingLevel` `eyebrow` `lede` `actions` `figure` `layout` `align` | [`ArenaHero.prompt.md`](./arena-hero/ArenaHero.prompt.md) |
| `ArenaMain` | The page's main landmark, and nothing else. Arena requires a name on both of its nav bars because what a nav is FOR is editorial, and then shipped no way to say where the content itself begins, which is the one region of a page it had not kept its own decision about. This draws no box: no display of its own beyond the block a landmark already is, no width, no grid, no padding. Where things go stays the container the consumer owns, and this says only what the region IS. It is also the target an ArenaSkipLink jumps to, so it is focusable programmatically: an anchor pointing at a container the platform will not focus scrolls the page and leaves focus behind, which is the failure that makes most skip links look like they work. | `content` | [`ArenaMain.prompt.md`](./arena-main/ArenaMain.prompt.md) |
| `ArenaScroller` | A row that scrolls sideways because it holds more than fits, with no arrows pretending to be a slideshow. It is one tab stop carrying a group role and a name, which is what a scrolling region needs to be reachable by keyboard at all: without it, everything past the right edge belongs to the pointer alone. Each child is laid out at one width so the row reads as a rail rather than as a line of whatever the children happened to measure. | `label*` `content*` `itemWidth` `behaviour` | [`ArenaScroller.prompt.md`](./arena-scroller/ArenaScroller.prompt.md) |
| `ArenaScrollerItem` | One cell of an ArenaScroller: the box that carries the width the row decided and the point the row settles on. It exists because a row cannot reach inside its children to size them, and a child that is an Arena component may render no box of its own at all, so a rule aimed at the row's direct children lands on nothing in one layer and on the card in the other. The item is the box both layers agree about. | `content` | [`ArenaScrollerItem.prompt.md`](./arena-scroller-item/ArenaScrollerItem.prompt.md) |
| `ArenaSection` | A named region of a page: a heading, optionally an eyebrow above it, a line under it and an action beside it, over whatever the region holds. It wraps what the consumer wrote and never replaces it. The title register is the section one, a step above a card's and a step below a page's, so a style plugin re-pitching the hierarchy moves this with the other two rather than leaving a page with three heads that disagree. | `title*` `headingLevel` `content*` `eyebrow` `description` `action` `rhythm` | [`ArenaSection.prompt.md`](./arena-section/ArenaSection.prompt.md) |
| `ArenaSiteFooter` | The band across the bottom of every screen: what a page says about itself once it has finished. It is the contentinfo landmark, so there is one per page, and like the bar at the top its contents line up with the page above them. | `content` `note` | [`ArenaSiteFooter.prompt.md`](./arena-site-footer/ArenaSiteFooter.prompt.md) |
| `ArenaSkipLink` | The link that lets a keyboard reader step over everything repeated on every screen and land in the content. It is four details and almost nobody gets all four: it has to be the first focusable thing in the document, invisible until it takes focus and visible the moment it does, and its target has to be focusable programmatically or focus never moves. Arena owns all four, and the consumer owns only the words. It points at the ArenaMain on the page, by an id Arena writes on both sides, so nothing is coordinated at the call site: a page has one main landmark, which is what makes a fixed id right here and wrong almost everywhere else. Place it first in the shell, above the header and the nav bars it exists to skip, which is the one thing it cannot do for itself. | `label*` | [`ArenaSkipLink.prompt.md`](./arena-skip-link/ArenaSkipLink.prompt.md) |

11 layout components in this layer.


<!-- frameworks/angular/components/navigation/INDEX.md -->

<!-- GENERATED from the contracts by bun run generate:skills. Edit the contracts, not this file. -->

# Arena navigation components, the Angular layer

Every navigation component this layer ships, under the names it binds them to. **This page is an
index, not a manual.** How to write one is its own prompt, linked in the last column.

**The rules every component below answers to are stated in
[`../../../../skills/design/SKILL.md`](../../../../skills/design/SKILL.md) before any component
here**, and nothing on this page restates them.

Import from the package root, never from a path inside it:

```ts
import { ArenaButton, ArenaTag } from '@dravensoft/arena-angular';
```

Every component is standalone: put its class in the host component's `imports`, then write its
`arena-` element. A member is a signal input, an event is an output under the name the contract
gives it, and the main slot is content projection. A named slot is a marker directive, which goes
in `imports` as well, because a component cannot tell an un-imported marker from an unfilled
slot. An icon is a Phosphor class-name string, never an element.

- Every other category this layer ships: [`../../INDEX.md`](../../INDEX.md).
- Installing the package, declaring your skin, and what it exports besides components:
  [`../../PACKAGE.md`](../../PACKAGE.md).
- **Takes** is the members the component's API contract declares, in contract order, under this
  layer's own names. A member marked `*` is required; the prompt gives its type and its default.
- **A member whose type is an object or an enum takes one this package exports.** The prompt
  names the type and says what it is for; the fields it holds are in the type declaration itself,
  which `import type { … } from '@dravensoft/arena-angular'` brings in. That field list is in neither
  the prompt nor the contract, so the type is where you read it.

| Component | What it is | Takes | Usage |
|---|---|---|---|
| `ArenaAppBar` | The band across the top of every screen: the site's identity, the way through it, and the controls that follow the reader everywhere. It is the banner landmark, so there is one per page, and its contents line up with the page under it because the bar spans the viewport and the band inside it does not. | `brand` `nav` `actions` `sticky` | [`ArenaAppBar.prompt.md`](./arena-app-bar/ArenaAppBar.prompt.md) |
| `ArenaBottomNav` | The bar of destinations pinned to the bottom edge of a phone screen. A compound component: the consumer writes one ArenaBottomNavItem per destination, and the coordination that tells each child which id is active and how to report `nav` is the parent's. That coordination is a member of no contract and each layer wires it in its own idiom. It is a row of equal columns with the glyph above the label, which is what separates it from a sidebar's stack of indented rows. | `active` `ariaLabel*` `content` `nav` | [`ArenaBottomNav.prompt.md`](./arena-bottom-nav/ArenaBottomNav.prompt.md) |
| `ArenaBottomNavItem` | One destination in an ArenaBottomNav. The consumer writes one per destination; which id is currently active and how it reports `nav` are settled between it and its parent, and none of that is a member of this contract, the same shape and the same reason as ArenaSideNavItem and as the name an ArenaRadioGroup settles with each ArenaRadio. It draws its glyph above its label and takes an equal share of the bar's width, however many destinations there are. | `id*` `label*` `icon*` `badge` `href` `disabled` | [`ArenaBottomNavItem.prompt.md`](./arena-bottom-nav-item/ArenaBottomNavItem.prompt.md) |
| `ArenaBreadcrumbs` | A trail of ancestor locations ending at the current one. An explicit return path for hierarchies deeper than tabs. | `ariaLabel*` `items*` `separator` `origin` `navigate` | [`ArenaBreadcrumbs.prompt.md`](./arena-breadcrumbs/ArenaBreadcrumbs.prompt.md) |
| `ArenaBulkActionBar` | Appears when rows are selected and operates on the selection as a set. Renders nothing at a count of zero. | `count*` `noun` `actions*` `run` `layout` `clearable` `clear` | [`ArenaBulkActionBar.prompt.md`](./arena-bulk-action-bar/ArenaBulkActionBar.prompt.md) |
| `ArenaCommandPalette` | Power-user accelerator (Cmd/Ctrl+K): search and run actions without a mouse. Controlled: the host owns whether it is open. | `open*` `commands*` `placeholder` `maxResults` `close` `run` | [`ArenaCommandPalette.prompt.md`](./arena-command-palette/ArenaCommandPalette.prompt.md) |
| `ArenaMenu` | Dropdown menu of actions on a trigger -- overflow, more actions, context. | `trigger*` `items*` `align` `select` | [`ArenaMenu.prompt.md`](./arena-menu/ArenaMenu.prompt.md) |
| `ArenaPageHead` | A page heading: a required title, an optional subtitle, and an optional actions slot. | `title*` `headingLevel` `subtitle` `actions` `align` | [`ArenaPageHead.prompt.md`](./arena-page-head/ArenaPageHead.prompt.md) |
| `ArenaPagination` | Page selector for a paged list. Renders a windowed range, never every page. | `page*` `pageCount*` `ariaLabel*` `change` | [`ArenaPagination.prompt.md`](./arena-pagination/ArenaPagination.prompt.md) |
| `ArenaSegmentedControl` | A compact inline filter over mutually exclusive options. A real radio group, never a tab list, and it carries no crimson. | `options*` `value` `defaultValue` `size` `ariaLabel*` `name` `change` | [`ArenaSegmentedControl.prompt.md`](./arena-segmented-control/ArenaSegmentedControl.prompt.md) |
| `ArenaSideNav` | The sidebar's navigation list -- the list alone, not the frame around it. A compound component: the consumer writes one ArenaSideNavItem per destination, and the coordination that tells each child where it sits, which id is active and how to report `nav` is the parent's. That coordination is a member of no contract and each layer wires it in its own idiom. | `active` `ariaLabel*` `content` `indentStep` `nav` | [`ArenaSideNav.prompt.md`](./arena-side-nav/ArenaSideNav.prompt.md) |
| `ArenaSideNavCollapsible` | A named group inside an ArenaSideNav that shows and hides its own contents. It may contain items, sections and further collapsibles to any depth; the indent compounds with depth, which is why ArenaSideNav.indentStep is a step rather than a total. It binds the `disclosure` pattern and deliberately does NOT claim to be a treeview: there is no aria-level, no roving tab stop and no arrow navigation, because each collapsible is an independent disclosure. Its expanded state lives in the component, seeded by defaultExpanded, and it additionally opens itself when it COMES TO HOLD ArenaSideNav.active -- a transition, not a standing condition, which is what leaves a user free to collapse a group again while the route stays inside it. Implicit behaviour, stated here and in its .prompt.md rather than left to be discovered. | `id*` `label*` `icon` `defaultExpanded` `content` `toggle` | [`ArenaSideNavCollapsible.prompt.md`](./arena-side-nav-collapsible/ArenaSideNavCollapsible.prompt.md) |
| `ArenaSideNavItem` | One destination in an ArenaSideNav. The consumer writes one per destination; the nesting depth it sits at, which id is currently active and how it reports `nav` are settled between it and its parent, and none of that is a member of this contract -- the same shape, and the same reason, as the name, checked state and selection callback an ArenaRadioGroup settles with each ArenaRadio. It used to be api/types/side-nav-item.json, a predefined object Arena read out of an array; it is an element the consumer writes now, which is what makes a section, a collapsible and arbitrary nesting expressible at all. | `id*` `label*` `icon` `disabled` `badge` `href` | [`ArenaSideNavItem.prompt.md`](./arena-side-nav-item/ArenaSideNavItem.prompt.md) |
| `ArenaSideNavSection` | A named group of navigation items inside an ArenaSideNav. It wraps what the consumer wrote and never replaces it; its accessible name is the same heading a sighted user reads. A section always has children -- a childless one is guarded against at runtime, because two shapes would be one more thing a single behaviour binding cannot describe. Having sections at all is optional: loose SideNavItems at the root are legal and may sit beside them. | `label*` `content*` | [`ArenaSideNavSection.prompt.md`](./arena-side-nav-section/ArenaSideNavSection.prompt.md) |
| `ArenaTab` | One tab in an ArenaTabs strip, and the panel it shows. ArenaTab draws the button; its content fills the tabpanel ArenaTabs renders beside the tablist. | `value*` `label*` `content` | [`ArenaTab.prompt.md`](./arena-tab/ArenaTab.prompt.md) |
| `ArenaTabs` | A row of tabs and the one panel they switch between. Write one `ArenaTab` per view; ArenaTabs renders the tablist, the panel, and the keyboard. | `content` `value` `defaultValue` `change` | [`ArenaTabs.prompt.md`](./arena-tabs/ArenaTabs.prompt.md) |

16 navigation components in this layer.


<!-- frameworks/angular/components/brand/arena-app-logo/ArenaAppLogo.prompt.md -->

Arena brand lock-up. Project the mark into the `mark` slot and pass the product name; one
`size` picks both the mark's box and the wordmark, from the `--logo-*` scale.

```html
<arena-app-logo name="Draven" dim="soft" size="md">
  <img mark src="/assets/your-mark.svg" alt="" />
</arena-app-logo>

<arena-app-logo name="Delivery" size="lg" orientation="vertical">
  <img mark src="/assets/your-client-mark.svg" alt="" />
</arena-app-logo>
```

<!-- @api GENERATED from contracts/api/components/ArenaAppLogo.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `mark*` | slot |  |  | The mark, as an asset the consumer supplies. Required: Arena ships MIT and a default would ship Dravensoft's trademark to whoever never read the API. The slot sizes the mark; a mark that brings its own dimensions fights the lock-up. |
| `name*` | primitive | `string` |  | The product name, or its first half when `dim` carries the second. |
| `dim` | primitive | `string` |  | The wordmark's second half, drawn muted and set straight against `name` with no space between them, so `name` of Draven and `dim` of soft reads as the one word Dravensoft. It is the second half of a name and never a tagline beside it: a product called Coldwalk splits as Cold and walk, and passing the tagline here draws it butted onto the name. Present for the manual's Primary variant, absent for Monochrome, which is why there is no `variant` member: the mark's ink and this are the same two decisions. |
| `size` | enum | `ArenaLogoSize` | `"md"` | Both halves at once: the mark's slot and the wordmark. |
| `orientation` | enum | `ArenaOrientation` | `"horizontal"` | Mark beside the name, or above it. |

<!-- @api end -->

**Do / Don't**
- Give the projected mark no width or height of its own. The slot sizes it; a mark that
  brings its own dimensions breaks the ratio the lock-up exists to hold.
- Give the projected element the `mark` attribute, `<ng-content select="[mark]" />` only
  projects an element marked that way; an `<img>` with no `mark` attribute projects nowhere.
- The slot stretches the projected mark with child variants (`*:block *:w-full *:h-full`)
  rather than reaching into the node, Angular has no `cloneElement`, and the CSS
  descendant combinator reaches the same result through the platform's own idiom.
- Use `dim` for the second ink of a two-part wordmark, and pass no space between the
  parts, `name="Draven" dim="soft"` renders Dravensoft in two inks, one word.
- Write `name` in the case your brand wears. Arena sets the face, the weight and the
  tracking of the wordmark and never its case: a name is text you wrote, and a component
  that shouted it would be renaming the company in CSS.
- Don't ship it with a mark that is not yours. Nothing defaults here on purpose: Arena is
  MIT and a default mark would be someone else's trademark travelling in your build.
- Don't reach for a fifth size. Four steps are the repertoire; a size between them is a
  token question, not a call-site one.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-bar-chart/ArenaBarChart.prompt.md -->

Arena bar chart. One axis, hand-written SVG, every colour a token, so it re-themes
with the rest of Arena and costs no dependency. It takes series, and a series names
itself. Identity comes from a series' `slot` (one colour for the whole series) or its
`slots` (a colour per bar, **in ramp order, never cycled**); meaning comes from its
`tone`. Passing both warns and `tone` wins, because a chart carries identity or meaning,
never both. A series with no identity of its own takes the slot its position gives it,
so two series are never the same colour by accident.

```ts
readonly deployments = computed<ArenaSeries[]>(() => [{ label: 'Deployments', values: this.counts(), slot: 1 }]);
readonly latency = computed<ArenaSeries[]>(() => [
  { label: 'p50', values: this.median() },
  { label: 'p95', values: this.p95() },
]);
readonly health = computed<ArenaSeries[]>(() => [{ label: 'Errors', values: this.errors(), tone: 'danger' }]);
```

```html
<arena-bar-chart label="Deployments per week" [labels]="weeks()" [series]="deployments()" />
<arena-bar-chart label="Latency by region" [labels]="regions()" [series]="latency()" valueSuffix=" ms" />
<arena-bar-chart label="Build health" [labels]="services()" [series]="health()" />
```

<!-- @api GENERATED from contracts/api/components/ArenaBarChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per category, in the same order as every series' `values`. A category with no value in a series is drawn for the series that do have one. |
| `series*` | array | `readonly ArenaSeries[]` |  | The plotted series, drawn as one group of bars per category. One series is the common case and draws exactly what it drew before; two or more share each category's band, so the bars of one category stand side by side and the reader compares within a category before comparing across. The ramp clamps at its last slot rather than cycling, so a ninth series folds into "Other" upstream, never into a colour already spent. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing, so two charts on one page announce identically. |
| `stack` | primitive | `boolean` | `false` | Sit each series on the one below it inside a single band per category, rather than standing them side by side. Stack when the series are parts of one total and that total is the thing being read; leave it off when the comparison is between the series, because a segment that does not start at zero is one a reader cannot measure against its neighbours. Positive and negative values stack on their own runs, so a category holding both grows in both directions from the zero line and the axis is sized from the two sums rather than from the largest single value. A series with no value at a category contributes no segment, and the segment above it sits on the one below rather than floating over a gap: a missing number is not a zero here either. Only the outermost segment of each direction is rounded, so the joints inside a bar stay square and read as joints. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the axis ticks, the tooltip and the accessible table. Carries its own leading space if one is wanted. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. A currency that precedes its amount is the majority case worldwide and had no expression: with suffix alone, "1234.5 Bs." is what a chart drew where the table beside it read "Bs. 1.234,50", and the accessible table inherited the disagreement. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number, which is what this chart drew before the member existed. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. A number rather than a dimension string, because the chart does arithmetic with it to place every mark, and a caller-supplied "20rem" is neither a token nor a derivation of one. |
| `minPointSpacing` | primitive | `number` |  | The narrowest gap, in px, the chart draws between two adjacent points. Below it the chart stops compressing and overflows its container horizontally instead, scrolled and anchored to the most recent point: marker spacing is a legibility constant, not something that yields to the viewport, and thirty days in 390px is unreadable at any font size. Absent, the chart fits whatever width it is given. The rail it scrolls in is the same region the data cursor lives in, and it is keyboard-reachable whether it overflows or not. |

<!-- @api end -->

`valueSuffix` is appended to the tick labels, the tooltip and the numbers table together,
so a unit written once appears everywhere. It is appended verbatim, write the space
yourself:

```html
<arena-bar-chart label="Latency by region" [labels]="regions()" [series]="latency()" valueSuffix=" ms" />
```

`valuePrefix` is drawn before the number the same way, for a currency that precedes its
amount. Between them, `valueFormat` says how the number itself is written: the locale, the
fraction digits, whether thousands are grouped, whether large numbers compact to `48,2K`.
Every field is data rather than a function, which is what keeps it a member at all, and
`Intl.NumberFormat` does the work. Formatting the values before binding them is not an option
and never was: what you bind is `ArenaSeries[]`, and the writing happens on labels Arena
generates afterwards. With no `valueFormat` the raw JavaScript number is drawn, which is the
old behaviour.

The chart sizes itself to its container, give it a parent with a width (an
`arena-chart-card` is the usual one) rather than setting a width on the chart. The host
is a block-level, positioned box: it is what gets measured, and it is what the hover
tooltip is positioned against.

**Do / Don't**
- Give `label`, because it names the chart for a screen reader and captions the numbers
  table underneath. Give every series its own `label` too: that one heads the series' own
  column in the same table, and the two names are different things.
- Use `tone` only when the series genuinely *is* a state. A red bar means "bad", and a
  red bar that just means "the second category" makes the chart lie.
- Don't pass a ninth `slots` entry expecting a ninth colour. The ramp is eight, in
  order; a ninth series folds into "Other" or becomes small multiples.
- Don't add a second axis. Arena's charts are one axis, always. Several series on one
  scale is what `series` is for; several that do not share a scale are several charts.
- Don't omit `labels`, `series` or `label`. All three are required inputs, and Angular
  throws NG0950 on the first read rather than drawing an empty box. A chart with no data
  is a caller bug, not a state to render.
- Don't pass more `labels` than a series has values. A bar is drawn per value and takes
  the label at its own index, so a surplus label is silently dropped rather than drawn
  without a bar to sit under. A series shorter than its neighbours simply stops: a
  missing number is not a zero, so it draws no bar and leaves an empty cell in the table.
- Don't build the `series` array inline in the template if the data changes. A new array
  literal on every change detection cycle is a new reference every cycle; hold it in a
  `computed()` or a field so the chart re-reads only when the numbers actually move.


### When the points stop fitting

`minPointSpacing` is the narrowest gap, in px, the chart will draw between two adjacent
points. Below it the chart stops compressing and overflows its container sideways instead,
in a rail that scrolls and starts anchored to the most recent point. Marker spacing is a
legibility constant rather than something that yields to the viewport: thirty days in 390px
is unreadable at any font size.

Arena computes the minimum width from its own axis padding, so nothing outside needs to know
what that padding is, and the rail is the chart's own box rather than the card's: an
`arena-chart-card` around it needs no change. The rail carries `tabindex="0"` and a
`role="group"` named after the chart whether it overflows or not.

`height` is the plot's height in px, the `--chart-height` token by default. It is a number
rather than a length string, because the chart does arithmetic with it to place every mark.

### Reading the bars without a pointer

The rail is one keyboard region and it is the plot's only tab stop. Inside it, Arrow Left and
Arrow Right move a data cursor from bar to bar, clamping at the ends rather than wrapping,
Home and End jump to the first and the last, and Escape clears it. The cursor drives exactly
what hover drives: the emphasised bar and its tooltip.

Nothing inside the graphic is focusable, and that is deliberate rather than an omission. A
`role="img"` subtree is presentational, so no ARIA on a mark inside it reaches a screen reader
however correct it is. A screen reader gets the visually hidden table of the same numbers,
which is already there; a sighted keyboard user gets the cursor. There is no third copy of the
numbers for either of them to disagree with.

On a touch screen the rule is tap to read, drag to scroll: a tap reads the bar under the
finger, a drag scrolls the rail, and a reading stays up until the next tap because a lifted
finger has no leave event to clear it. Nothing captures the pointer and nothing calls
`preventDefault`, so the page keeps scrolling over the chart the way it does over anything else.

### The legend, and when there is one

A chart of two or more series draws a row of keys below the plot, one swatch and one series name
each, in the order the series were given. A chart of one series draws none: `label` already names
the chart, the table's single value column is already headed by that series' own name, and a
one-row legend would restate both while spending plot height to do it. There is no member for
this; the number of series is the whole rule.

The strip comes out of the plot rather than being added to the box, so `height` stays the height
of the whole component whether a legend is drawn or not. That is what keeps a grid of tiles
aligned when one of them gains a second series.

It is `aria-hidden`, deliberately. It is a key for a reader who can see the colours, and those
same names are already the column headers of the numbers table, so a focusable copy of them would
be a second source for one fact. Its rows take no focus, and the plot still has exactly one tab
stop.

### Grouped or stacked

`stack` puts the series inside one band per category, each sitting on the one below it, instead of
standing them side by side. Reach for it when the series are parts of one total and the total is
what the reader is there for. Leave it off when the comparison is between the series: only the
first segment starts at the zero line, so every one above it is a length a reader has to measure
against a moving base, which is the thing bar charts are good at and stacks are not.

Positive and negative values stack on their own runs, so a category holding both grows in both
directions from the zero line and the axis is sized from the two sums rather than from the largest
single value. That is the same divergent axis a grouped chart already had; a stack just gives it
more to hold.

A series with no value at a category contributes no segment, and the segment above it sits on the
one below rather than floating over a gap. A missing number is not a zero here either, so a hole
shortens the total instead of pretending the category was measured.

Only the outermost segment of each direction is rounded. The joints inside a bar stay square,
because a rounded joint reads as the end of something.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-chart-card/ArenaChartCard.prompt.md -->

Arena chart tile, the card a chart sits on, with a mono microlabel and an optional
action slot. Its title is a label and not a heading by default: a dashboard is a grid of
tiles, and a dozen tiles each opening a rung invents a document outline where the page
holds one region. The chart inside carries the accessible name through its own
`role="img"`, so nothing goes unnamed by it. A tile that genuinely is a region of the page
says so with `headingLevel`, and `h3` is the rung a chart card inside a section takes.

```html
<arena-chart-card title="Deployments per week">
  <arena-icon-button actions icon="ph-bold ph-download-simple" label="Export" />
  <arena-bar-chart label="Deployments per week" [labels]="weeks()" [series]="deployments()" />
</arena-chart-card>
```

<!-- @api GENERATED from contracts/api/components/ArenaChartCard.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title` | primitive | `string` |  | The card heading. Absent renders no head unless `actions` is present. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"none"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it, the micro register this title is drawn in included. It is the one title on the ladder that defaults to `none`, because the ordinary chart card is a tile in a dashboard grid and a dozen tiles each opening a rung invents an outline where a page has one region; the chart inside carries its own accessible name, so nothing goes unnamed. A tile that genuinely IS a region of the page says which rung it takes, and `h3` is the card rung a chart card inside a section would want. |
| `actions` | slot |  |  | Controls in the head row, right-aligned beside the title. |
| `content` | slot |  |  | The chart (or any body) the card frames. |

<!-- @api end -->

Import `ArenaActions` from `@dravensoft/arena-angular` alongside `ArenaChartCard` in the
host component's `imports`,
`actions` is a directive, not a plain attribute, because it is how the card
detects that actions were projected at all. Without it the attribute is inert, the
head row never renders when there is no title, and the button silently disappears.
`ArenaActions` is shared: every primitive with a plural, toolbar-shaped projected slot
imports the same directive rather than declaring its own, `arena-page-head` is the
other consumer.

The head row (title plus actions) renders only when one of them is actually present.
With neither, no empty row ships dead space above the chart.

**Do / Don't**
- Mark **each** control with `actions`, as siblings. The head row and the actions row both
  wrap their own children, so a single wrapper holding three buttons is one flex item that
  can never wrap and overflows the tile on a phone. `arena-page-head` says the same thing
  about the same slot.
- Keep the title short and in the tile's own words. It is a label, not a sentence.
- Let `title` and the chart's own `label` say the same thing when the card holds one chart.
  They are not redundant: `title` is what a sighted reader sees on the tile, `label` is what
  a screen reader hears and what captions the numbers table, and neither is derivable from
  the other.
- Don't put two charts in one card. A card is one question answered once.
- Don't reach for this as a general card: that is `mat-card` wearing Arena.

The card's own inner padding is not something a chart inside it needs to know. A chart that
overflows scrolls in its own rail rather than in the card's box, so `minPointSpacing` needs no
cooperation from here, and there is no member for the padding because nothing outside has to
reproduce it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-doughnut-chart/ArenaDoughnutChart.prompt.md -->

Arena doughnut, parts of one whole, hand-written SVG, every colour a token. It takes exactly
one series, whose values are read as shares of their own total. The legend is not optional:
slices are categories, and identity is never colour alone. Colours come from the categorical
ramp in order and are never cycled; a slice cannot be a status, so `tone` has no meaning on
this chart's series. The ring starts at 12 o'clock, the hole is 62% of the outer radius, and
hovering either a slice or its legend row dims the others and reads that slice's percentage
in the hole. Focusing a legend row does the same, because every row is a real button. The
numbers are also a real table for anyone who cannot see the ring.

```ts
readonly revenue = computed<ArenaSeries[]>(() => [{ label: 'Revenue', values: this.byRegion() }]);
```

```html
<arena-doughnut-chart label="Revenue by region" [labels]="regions()" [series]="revenue()"
                      valueSuffix=" €" (sliceActivate)="drillInto($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaDoughnutChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per slice, in the same order as the series' `values`. A label with no value at its index is dropped. |
| `series*` | array | `readonly ArenaSeries[]` |  | The parts, as one series whose values are read as shares of their own total. Exactly one series: a ring of two series is a sunburst, which is a different chart and not this one, so a second warns in development and is ignored. Per-slice identity goes in that series' `slots`. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing, so two charts on one page announce identically. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the legend value and the accessible table. Not the centre label, which is a percentage rather than a value. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. A currency that precedes its amount is the majority case worldwide and had no expression: with suffix alone, "1234.5 Bs." is what a chart drew where the table beside it read "Bs. 1.234,50", and the accessible table inherited the disagreement. |
| `shape` | enum | `ArenaChartShape` | `"doughnut"` | Whether the ring keeps its hole or fills to the centre. 'pie' is the same chart with the same slices, the same legend and the same table, drawn solid. It costs the centre percentage, which has nowhere to go once the hole is gone: over a wedge it would put --bone on a --color-cat slot, a pair nothing checks for contrast because nothing had drawn it. The figure is not lost, it is in the legend row and in the accessible table, which is where every other number the chart writes already is. |
| `legendLayout` | enum | `ArenaChartLegendLayout` | `"auto"` | How each legend row arranges its label and its figure. 'inline' puts them on one line, which is what fits a wide tile; 'stacked' puts the label above the figure; 'auto' measures the legend column and stacks when the row does not give. It exists because the two do not degrade equally: on one line the figure does not yield, so the label is what gets truncated, and a legend of numbers with nothing saying what they count is the opposite of a legend. The threshold is already declared, as the chart-legend-min and chart-legend-max tokens the ring width is clamped between; what was missing was the behaviour. |
| `sliceActivate` | event | `number` |  | A slice was activated, by pointer on the arc or on its legend row, or by keyboard on that row, which is a real button and answers Enter and Space without the component binding either. It carries the slice's index in the series' `values`. **In `values`, never in the drawn paths**, and that is the whole member: a slice worth zero paints nothing, so the shapes on screen and the entries in the array are two different lists, and a consumer indexing the SVG has to reproduce that omission from outside to translate one into the other. It is reverse engineering of a component's own DOM, which the next release breaks in silence. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number, which is what this chart drew before the member existed. |

<!-- @api end -->

`valueSuffix` is appended verbatim to the legend value and to the numbers table, write the
space yourself. `valuePrefix` is drawn before the number the same way, for a currency that precedes its
amount. Between them, `valueFormat` says how the number itself is written: the locale, the
fraction digits, whether thousands are grouped, whether large numbers compact to `48,2K`.
Every field is data rather than a function, which is what keeps it a member at all, and
`Intl.NumberFormat` does the work. Formatting the values before binding them is not an option
and never was: what you bind is `ArenaSeries[]`, and the writing happens on labels Arena
generates afterwards. With no `valueFormat` the raw JavaScript number is drawn, which is the
old behaviour.

`label` names the chart for a screen reader and captions the numbers table; it is required
and guarded, because a fallback of "Doughnut chart" identifies the chart type and not the
chart, and two rings on one page would announce identically. The series' own `label` names
its value column in that same table.

The series' `slots` overrides the ramp order, for when a category must keep the same colour
it has in a sibling chart:

```ts
readonly revenue = computed<ArenaSeries[]>(() => [
  { label: 'Revenue', values: this.byRegion(), slots: [3, 1, 5] },
]);
```

The chart sizes itself to its container, give it a parent with a width (an
`arena-chart-card` is the usual one) rather than setting a width on the chart. The host is
the flex row itself: the ring is one item, the legend the other, and the host is what gets
measured.

**Do / Don't**
- Keep it to five or six slices. Past that the arcs stop being comparable and a bar chart
  reads better. That is not a rendering limit; it is what the shape can carry.
- Make sure the values really are parts of one whole. Two doughnuts whose slices come from
  different totals are two charts that look like one.
- Don't ask for a ninth colour. The ramp has eight slots and is never cycled, so a ninth
  slice repeats slot 8 rather than silently claiming two categories are one, fold the tail
  into "Other" instead.
- Don't use it for change over time. That is `arena-line-chart`.
- Don't pass a second series. A ring of two series is a sunburst, which is a different chart
  and not this one: the second warns in development and is ignored.
- Don't reach for `tone` on the series. A slice is a category by definition, so a tone here
  paints every slice one colour and destroys the only thing the chart encodes.
- Don't omit `labels`, `series` or `label`. All three are required inputs, and Angular throws
  NG0950 on the first read rather than drawing an empty ring. A chart with no data is a
  caller bug, not a state to render.
- Don't pass more `labels` than the series has values. A slice is drawn per value and takes
  the label at its own index, so a surplus label is silently dropped rather than given a
  legend row with no slice behind it.
- Don't place it on a surface other than `--surface-card`. The gap between slices is that
  surface showing through a `--surface-card` stroke, not a border on the slice; on a
  different background the gaps read as stripes of the wrong colour.

**The legend is keyboard-reachable, one row at a time.** Every legend row is a real
`<button type="button">`, reset to look like text, so `(sliceActivate)` is reachable by
keyboard and each row answers Enter and Space without the component binding either. Focus on
a row moves the same emphasis the pointer does, so the dimmed slices and the centre
percentage follow the keyboard as well as the mouse.

The legend column keeps `role="group"` and `aria-label="Doughnut chart legend"` and carries
no tab stop of its own. Carrying one, as an `overflow: auto` scroll region with nothing
focusable inside it, lets a keyboard user scroll the legend and activate nothing: WCAG 2.1.1
with a real victim. Since the rows take focus the stop would be dead anyway, and a focusable
child scrolls its own overflow ancestor into view. `role="group"` is chosen over the WAI scrollable-region pattern's `role="region"` because a region is meant to
be a landmark a user jumps to directly, and this column is one row of a small chart rather
than a page landmark; `aria-label` names it either way.

The ring itself takes no data cursor and needs none. A ring has no ordered sequence to arrow
along, and its rows are already one tab stop each, so a keyboard user reaches a slice
directly instead of walking to it. That is the one place this chart parts company with
`arena-bar-chart` and `arena-line-chart`, which have an axis and therefore a cursor.

### Reading a slice back, and reading a legend on a phone

`(sliceActivate)` carries the index **in `values`**, and that is the whole member. A slice worth
zero paints no path, so the shapes on screen and the entries in the array are two different
lists; a consumer indexing `querySelectorAll('path')` has to reproduce that omission from
outside to translate one into the other, and the next release breaks it in silence. Both the arc
and its legend row report, so the zero-valued entry, which has no arc, is still reachable, and
reachable by keyboard because the row is a button.

`legendLayout` decides how each legend row arranges its label and its figure: `inline` on one
line, `stacked` with the label above, `auto` measuring the legend column and stacking when the
row does not give. The default is `auto`, and it matters because the two do not degrade equally:
on one line the figure does not yield, so at 390px the label is what gets cut, and a column of
numbers with nothing saying what they count is the opposite of a legend.

### Ring or solid

`shape` decides whether the hole stays. `pie` is this same chart, the same slices in the same
order with the same legend and the same table, filled to the centre. There is no ratio member:
the hole is 62% of the outer radius and that number is deliberately not a token, on the recorded
ground that a multiplier deriving one dimension from another stays inline, so handing it to a
caller one value at a time would move a design decision out of the chart.

A pie draws no centre percentage, and that is the trade rather than an oversight. There is
nowhere to put it once the hole is gone, and printing it over a wedge would put `--bone` on a
`--color-cat` slot, a pair nothing checks for contrast because nothing had ever drawn it. The
figure is still in the legend row and in the accessible table, which is where every other number
this chart writes already lives.

The accessible name follows the shape, so a pie announces as one.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-horizontal-bar-chart/ArenaHorizontalBarChart.prompt.md -->

Categorical bars running across the plot, with the category names down its left edge. Same data, same accessible table and same series as `ArenaBarChart`, with the axes transposed. Reach for it when the category names are worth reading: across the bottom of a vertical chart they get rotated or truncated, and here they have a gutter of their own.

```ts
readonly issues = computed<ArenaSeries[]>(() => [{ label: 'Open issues', values: this.counts() }]);
readonly spend = computed<ArenaSeries[]>(() => [
  { label: 'Cloud', values: this.cloud() },
  { label: 'Licences', values: this.licences() },
]);
```

<!-- @api GENERATED from contracts/api/components/ArenaHorizontalBarChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per category, in the same order as every series' `values`. They run down the left edge, in the gutter chart.pad-category holds, and a name longer than that gutter is truncated rather than pushed into the plot. |
| `series*` | array | `readonly ArenaSeries[]` |  | The plotted series, drawn as one group of bars per category. One series is the common case; two or more share each category's band, so the bars of one category stand one above the other and the reader compares within a category before comparing across. The ramp clamps at its last slot rather than cycling, so a ninth series folds into "Other" upstream, never into a colour already spent. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing, so two charts on one page announce identically. |
| `stack` | primitive | `boolean` | `false` | Sit each series on the one before it inside a single band per category, rather than standing them one above the other. Stack when the series are parts of one total and that total is the thing being read; leave it off when the comparison is between the series, because a segment that does not start at zero is one a reader cannot measure against its neighbours. Positive and negative values stack on their own runs, so a category holding both grows in both directions from the zero line. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the axis ticks, the tooltip and the accessible table. Carries its own leading space if one is wanted. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. A currency that precedes its amount is the majority case worldwide and had no expression: with suffix alone, "1234.5 Bs." is what a chart drew where the table beside it read "Bs. 1.234,50", and the accessible table inherited the disagreement. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number, which is what this chart drew before the member existed. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. On this chart it is the axis the categories run down, so a chart of many categories wants more of it: pass the room the data needs rather than letting the bands thin out. There is no scrolling rail here on purpose, because a vertical scroll region nested in a page takes the page's own scroll away from the reader, which is the reasoning that already keeps touch-action off the horizontal one. A number rather than a dimension string, because the chart does arithmetic with it to place every mark. |

<!-- @api end -->

```html
<arena-horizontal-bar-chart label="Open issues by area" [labels]="areas()" [series]="issues()" />

<arena-horizontal-bar-chart label="Spend by quarter" [labels]="quarters()" [series]="spend()" stack
                            valuePrefix="$" [valueFormat]="{ compact: true }" />
```

### Why this is a component and not an orientation

Transposing the axes changes what four members mean, which is why `arena-bar-chart` has no
`orientation` flag. The data cursor answers ArrowUp and ArrowDown here, and leaves the horizontal
pair to the page. The category gutter is its own token rather than the value gutter widened, so a
vertical chart does not pay 52px for names it does not draw. `height` stops being a fixed frame
and becomes the axis the categories run down. And there is no scrolling rail.

That last one is deliberate rather than missing. `arena-bar-chart` overflows sideways into a rail
when the points stop fitting, and sideways is a direction a page does not use. Down is the
direction a page already scrolls, so a rail here would take the page's own scroll away from
anyone passing through the chart, which is the reasoning that already keeps `touch-action` off
the horizontal one. A chart of many categories asks for the room instead: give `height` what the
data needs.

### Reading the bars without a pointer

The plot is one keyboard region and the only tab stop. ArrowUp and ArrowDown move a data cursor
from category to category, clamping at the ends rather than wrapping, Home and End jump to the
first and the last, and Escape clears it. ArrowLeft and ArrowRight do nothing and are not
consumed, because this chart has no sequence along that axis and swallowing a key it cannot use
would strand a reader.

Nothing inside the graphic is focusable. A `role="img"` subtree is presentational, so a screen
reader gets the visually hidden table of the same numbers and a sighted keyboard user gets the
cursor.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-line-chart/ArenaLineChart.prompt.md -->

Arena line chart, a value over an ordered sequence, hand-written SVG, every colour a token.
It takes series, one polyline each over the same sequence, and a series names itself. An
optional 18% area tint sits under the line, for one series only. The crosshair snaps to the
nearest point rather than drifting between them, and the numbers are also a real table for
anyone who cannot see the line. Identity comes from a series' `slot`, meaning from its
`tone`; passing both warns and `tone` wins, because a chart carries identity or meaning,
never both.

```ts
readonly p95 = computed<ArenaSeries[]>(() => [{ label: 'p95 latency', values: this.latency(), slot: 3 }]);
readonly percentiles = computed<ArenaSeries[]>(() => [
  { label: 'p50', values: this.median() },
  { label: 'p95', values: this.latency() },
]);
readonly errors = computed<ArenaSeries[]>(() => [{ label: 'Error rate', values: this.errorRate(), tone: 'danger' }]);
```

```html
<arena-line-chart label="Request latency" [labels]="days()" [series]="p95()" [area]="true" valueSuffix=" ms" />
<arena-line-chart label="Request latency" [labels]="days()" [series]="percentiles()" valueSuffix=" ms" />
<arena-line-chart label="Error budget" [labels]="days()" [series]="errors()" valueSuffix="%" />
```

<!-- @api GENERATED from contracts/api/components/ArenaLineChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per point, in the same order as every series' `values`. A label with no value in a series ends that series' line there rather than dropping to zero. |
| `series*` | array | `readonly ArenaSeries[]` |  | The plotted series, drawn as one polyline each over the same ordered sequence. One series is the common case and draws exactly what it drew before. The area fill is refused past one series, because two fills occlude each other and the reader cannot tell which value either edge belongs to. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing, so two charts on one page announce identically. |
| `area` | primitive | `boolean` | `false` | Fill under the line at 18% of the series colour: a tint, never a gradient. For a single series; two fills occlude each other. |
| `curve` | primitive | `boolean` | `false` | Draw the series as a smooth curve rather than straight segments between points. The interpolation is monotone cubic, not Catmull-Rom, and that is the whole of the decision: a Catmull-Rom curve overshoots, so between two measured points it draws a peak or a trough nobody measured, and a chart that draws data which does not exist is the one thing a chart may not do. A monotone curve stays inside the band its own two points define, keeps a flat tangent at a turning point, and never crosses zero unless the values do. It changes the path string and nothing else: the points, the crosshair, the tooltip and the data cursor read the same numbers at the same places. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the axis ticks, the tooltip and the accessible table. Carries its own leading space if one is wanted. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. A currency that precedes its amount is the majority case worldwide and had no expression: with suffix alone, "1234.5 Bs." is what a chart drew where the table beside it read "Bs. 1.234,50", and the accessible table inherited the disagreement. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number, which is what this chart drew before the member existed. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. A number rather than a dimension string, because the chart does arithmetic with it to place every mark, and a caller-supplied "20rem" is neither a token nor a derivation of one. |
| `minPointSpacing` | primitive | `number` |  | The narrowest gap, in px, the chart draws between two adjacent points. Below it the chart stops compressing and overflows its container horizontally instead, scrolled and anchored to the most recent point: marker spacing is a legibility constant, not something that yields to the viewport, and thirty days in 390px is unreadable at any font size. Absent, the chart fits whatever width it is given. The rail it scrolls in is the same region the data cursor lives in, and it is keyboard-reachable whether it overflows or not. |

<!-- @api end -->

`valueSuffix` is appended to the tick labels, the tooltip and the numbers table together,
so a unit written once appears everywhere. It is appended verbatim, write the space
yourself:

```html
<arena-line-chart label="Request latency" [labels]="days()" [series]="p95()" valueSuffix=" ms" />
```

`valuePrefix` is drawn before the number the same way, for a currency that precedes its
amount. Between them, `valueFormat` says how the number itself is written: the locale, the
fraction digits, whether thousands are grouped, whether large numbers compact to `48,2K`.
Every field is data rather than a function, which is what keeps it a member at all, and
`Intl.NumberFormat` does the work. Formatting the values before binding them is not an option
and never was: what you bind is `ArenaSeries[]`, and the writing happens on labels Arena
generates afterwards. With no `valueFormat` the raw JavaScript number is drawn, which is the
old behaviour.

The chart sizes itself to its container, give it a parent with a width (an
`arena-chart-card` is the usual one) rather than setting a width on the chart. The host
is a block-level, positioned box: it is what gets measured, and it is what the hover
tooltip is positioned against.

**Do / Don't**
- Give `label`, because it names the chart for a screen reader and captions the numbers
  table underneath. Give every series its own `label` too: that one heads the series' own
  column in the same table, and the two names are different things.
- Use `area` for a volume or a total, not for a rate. A filled area says "this much of
  something"; a rate has nothing to fill.
- Use `tone` only when the series genuinely *is* a state. A red line means "bad", and a
  red line that just means "the third series" makes the chart lie.
- Don't plot two series by stacking two line charts. Put both in `series` and they share
  one scale, one axis and one table. Two series that do *not* share a scale are two
  charts, and no member will make them one.
- Don't turn `area` on past one series. It is refused and warns in development, because
  two fills occlude each other and the reader cannot tell which value either edge belongs to.
- Don't omit `labels`, `series` or `label`. All three are required inputs, and Angular
  throws NG0950 on the first read rather than drawing an empty box. A chart with no data
  is a caller bug, not a state to render.
- Don't pass more `labels` than a series has values. A point is drawn per value and takes
  the label at its own index, so a surplus label is silently dropped rather than drawn with
  no point above it. A series shorter than its neighbours ends its line there rather than
  dropping to zero, because a missing number is not a zero.
- Don't build the `series` array inline in the template if the data changes. A new array
  literal on every change detection cycle is a new reference every cycle; hold it in a
  `computed()` or a field so the chart re-reads only when the numbers actually move.
- Don't express a condition as an attribute string. `area` carries the
  `booleanAttribute` transform, so a bare `area` and `[area]="true"` both mean true, and
  the one literal string `"false"` means false. Every *other* string is true, `"0"`,
  `"off"` and `"no"` all draw the fill. Bind a computed value instead:
  `[area]="isVolume"`. Keep the bare attribute for a constant true.


### When the points stop fitting

`minPointSpacing` is the narrowest gap, in px, the chart will draw between two adjacent
points. Below it the chart stops compressing and overflows its container sideways instead,
in a rail that scrolls and starts anchored to the most recent point. Marker spacing is a
legibility constant rather than something that yields to the viewport: thirty days in 390px
is unreadable at any font size.

Arena computes the minimum width from its own axis padding, so nothing outside needs to know
what that padding is, and the rail is the chart's own box rather than the card's: an
`arena-chart-card` around it needs no change. The rail carries `tabindex="0"` and a
`role="group"` named after the chart whether it overflows or not.

`height` is the plot's height in px, the `--chart-height` token by default. It is a number
rather than a length string, because the chart does arithmetic with it to place every mark.

### Reading the line without a pointer

The rail is one keyboard region and it is the plot's only tab stop. Inside it, Arrow Left and
Arrow Right move a data cursor from point to point, clamping at the ends rather than wrapping,
Home and End jump to the first and the last, and Escape clears it. The cursor drives exactly
what hover drives: the enlarged point, the crosshair and the tooltip.

Nothing inside the graphic is focusable, and that is deliberate rather than an omission. A
`role="img"` subtree is presentational, so no ARIA on a mark inside it reaches a screen reader
however correct it is. A screen reader gets the visually hidden table of the same numbers,
which is already there; a sighted keyboard user gets the cursor. There is no third copy of the
numbers for either of them to disagree with.

On a touch screen the rule is tap to read, drag to scroll: a tap reads the point nearest the
finger, a drag scrolls the rail, and a reading stays up until the next tap because a lifted
finger has no leave event to clear it. Nothing captures the pointer and nothing calls
`preventDefault`, so the page keeps scrolling over the chart the way it does over anything else.

### The legend, and when there is one

A chart of two or more series draws a row of keys below the plot, one swatch and one series name
each, in the order the series were given. A chart of one series draws none: `label` already names
the chart, the table's single value column is already headed by that series' own name, and a
one-row legend would restate both while spending plot height to do it. There is no member for
this; the number of series is the whole rule.

The strip comes out of the plot rather than being added to the box, so `height` stays the height
of the whole component whether a legend is drawn or not. That is what keeps a grid of tiles
aligned when one of them gains a second series.

It is `aria-hidden`, deliberately. It is a key for a reader who can see the colours, and those
same names are already the column headers of the numbers table, so a focusable copy of them would
be a second source for one fact. Its rows take no focus, and the plot still has exactly one tab
stop.

### Straight or smooth

`curve` draws the series as a smooth curve instead of straight segments. It changes the path
string and nothing else: the points sit where they sat, the crosshair snaps to the same one, the
tooltip reads the same numbers and the data cursor walks the same sequence.

The interpolation is monotone cubic rather than Catmull-Rom, and that choice is the whole reason
this member is safe to use on real data. A Catmull-Rom curve overshoots, so between two measured
points it draws a peak or a trough nobody measured, and a chart that draws data which does not
exist is the one thing a chart may not do. A monotone curve stays inside the band its own two
points define, flattens at a turning point instead of sailing past it, and never crosses zero
unless the values do.

Reach for it when the underlying quantity really is continuous, a temperature or a load average
sampled at intervals. Leave it off when the points are discrete events counted per bucket: a
smooth line between two counts implies values between them that were never counted.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-pyramid-chart/ArenaPyramidChart.prompt.md -->

A population pyramid: two counts per band, mirrored about a shared centre line, with the band names down the left edge. Diverging from a centre is the point rather than an option, which is why it is its own component and not a flag on a bar chart.

```ts
readonly byAge = computed<ArenaSeries[]>(() => [
  { label: 'Women', values: this.women() },
  { label: 'Men', values: this.men() },
]);
```

<!-- @api GENERATED from contracts/api/components/ArenaPyramidChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per band, in the same order as both series' `values`, running down the left edge. On a population pyramid these are the age brackets, oldest first or youngest first as the data is given: the chart does not reorder them, because which end is the top is a decision about the population and not about the drawing. |
| `series*` | array | `readonly ArenaSeries[]` |  | Exactly two series, one for each side of the centre line, in order: the first is drawn to the left and the second to the right. Both carry counts rather than signed values, and the chart negates the first when it draws it, so the accessible table reads the numbers that were passed and the picture reads the shape they make. A third series has nowhere to go and warns; a single one is a horizontal bar chart and should be one. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing, so two charts on one page announce identically. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the axis ticks, the tooltip and the accessible table. The ticks carry the magnitude, never the minus sign the left side is drawn with, because both sides count upward from the centre. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. A currency that precedes its amount is the majority case worldwide and had no expression: with suffix alone, "1234.5 Bs." is what a chart drew where the table beside it read "Bs. 1.234,50", and the accessible table inherited the disagreement. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number, which is what this chart drew before the member existed. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. It is the axis the bands run down, so a pyramid of many brackets wants more of it: pass the room the data needs rather than letting the bands thin out. A number rather than a dimension string, because the chart does arithmetic with it to place every mark. |

<!-- @api end -->

```html
<arena-pyramid-chart label="Population by age band" [labels]="bands()" [series]="byAge()" />
```

### Two counts, one centre

`series` takes exactly two, in order: the first is drawn to the left of the centre line and the
second to the right. Both carry **counts**, not signed values. The chart negates the first one
when it draws it, so the accessible table reads the numbers you passed and the picture reads the
shape they make. A tick on the axis is a magnitude for the same reason: a tick reading -600 would
say the left side is a debt rather than a count.

A negative value is not corrected. It crosses the centre line and draws on the other side, which
is what the number says, and the table says the same thing. A pyramid that quietly took the
magnitude would be the only place in Arena where the picture and the table can disagree.

The axis reaches the same distance on both sides, measured from the larger one. That is the whole
point: two halves scaled to their own maxima would look balanced whatever the data said, which is
the comparison this chart exists to make.

### Reading it without a pointer

The cursor walks BANDS rather than bars, so one press reads both sides at once. ArrowUp and
ArrowDown move it, Home and End jump to the ends, Escape clears it. ArrowLeft and ArrowRight do
nothing and are not consumed: this chart has no sequence along that axis, and swallowing a key it
cannot use would strand a reader.

The legend under the plot is what names the two sides, and it appears here always, because a
pyramid is two series by definition.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-radar-chart/ArenaRadarChart.prompt.md -->

Several measures on one shape: an axis per label around a polar grid, one closed polygon per series. It reads a profile rather than a magnitude, which is what makes it a different chart from bars over the same numbers.

```ts
readonly profile = computed<ArenaSeries[]>(() => [
  { label: 'Current', values: this.current() },
  { label: 'Target', values: this.target() },
]);
```

<!-- @api GENERATED from contracts/api/components/ArenaRadarChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `labels*` | array | `readonly string[]` |  | One label per axis, in the same order as every series' `values`, running clockwise from 12 o'clock. Keep the count small: past eight or so the labels collide and the shape stops being readable, which is a limit of the form rather than of the drawing. |
| `series*` | array | `readonly ArenaSeries[]` |  | The plotted series, drawn as one closed polygon each over the same axes. The shape is the reading, so two or three series is the useful case and more is a tangle. The ramp clamps at its last slot rather than cycling. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing. |
| `fill` | primitive | `boolean` | `false` | Fill each polygon at 18% of its series colour: a tint, never a gradient. Useful for one series, where the filled area reads as a footprint. Past one the fills overlap and the reader cannot tell which polygon an overlap belongs to, so leave it off and let the outlines carry the shape. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: the tooltip and the accessible table. Carries its own leading space if one is wanted. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. The grid is a circle inscribed in the smaller of the plot's two axes, so this also caps how wide the shape gets. A number rather than a dimension string, because the chart does arithmetic with it to place every mark. |

<!-- @api end -->

```html
<arena-radar-chart label="Service profile" [labels]="axes()" [series]="profile()" />
```

### What the grid is, and what it is not

The axes start at 12 o'clock and run clockwise, the same way the doughnut's slices do, so two
radial charts on one page never begin in different places. Every axis shares one radial scale
that starts at the centre, so the rings are readable across all of them.

A radius cannot be negative, so a value below zero is drawn at the centre rather than on the
opposite axis, where it would land as a different datum entirely. That floor is this chart's own,
the way the doughnut keeps one: `arenaScaleValue` maps and does not clamp, and where a value may
not go is the chart's rule and not the scale's. The accessible table still reads the number that
was passed.

Keep the axis count small. Past eight or so the labels collide, which is a limit of the form and
not of the drawing. And keep the series count to two or three: the shape is the reading, and four
outlines over one grid is a tangle.

`fill` is for one series, where the area reads as a footprint. Past one the fills overlap and a
reader cannot tell which polygon an overlap belongs to.

### Reading it without a pointer

The cursor walks the AXES, so one press reads every series on that axis at once. ArrowLeft and
ArrowRight move it, Home and End jump to the ends, Escape clears it. Going around is a sequence,
which is why this chart takes a cursor where the doughnut refuses one: a ring of slices has no
order to walk, and a ring of axes does.

ArrowUp and ArrowDown do nothing and are not consumed, so the page keeps its own scroll.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/charts/arena-scatter-chart/ArenaScatterChart.prompt.md -->

Two quantities against each other, one mark per pair. The first chart here whose horizontal axis carries a value rather than a position, which is why it takes a different series type and why it names both of its axes.

```ts
readonly clouds = computed<ArenaPointSeries[]>(() => [
  { label: 'Staging', x: this.stagingLoad(), y: this.stagingLatency() },
  { label: 'Production', x: this.prodLoad(), y: this.prodLatency() },
]);
```

<!-- @api GENERATED from contracts/api/components/ArenaScatterChart.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `series*` | array | `readonly ArenaPointSeries[]` |  | The plotted series, drawn as one cloud of marks each. Each carries pairs rather than indexed values, because a scatter has no categories to index against: that is what ArenaPointSeries is for and why it is a separate type from ArenaSeries. The ramp clamps at its last slot rather than cycling. |
| `label*` | primitive | `string` |  | Names the chart for its accessible name and for the caption of its data table. This is the CHART's name, not a series': a series names itself. Required and guarded rather than defaulted, because a fallback of the chart TYPE satisfies roles.label mechanically and tells a screen-reader user nothing. |
| `xLabel*` | primitive | `string` |  | Names the horizontal quantity, for the accessible table's column. Required, because unlike every other chart here both axes carry a quantity a reader cannot derive: a bar chart's categories name themselves through `labels` and its value axis is the one thing being measured, while a scatter measures two things and a table of bare X and Y columns says which is which to nobody. |
| `yLabel*` | primitive | `string` |  | Names the vertical quantity, for the accessible table's column. Required for the reason xLabel is. |
| `sizeLabel` | primitive | `string` |  | Names the quantity a series' `r` carries, for the accessible table's third column. Required as soon as any series carries one, and guarded at render rather than declared required, because a scatter with no sizes has no third quantity to name and a member that is required only sometimes cannot say so in a contract. A column headed "Size" would satisfy the table mechanically and tell a reader nothing, which is the same reason `label` is guarded. |
| `sizeLegend` | primitive | `boolean` | `false` | Draw a key of three sample bubbles, at the smallest, middle and largest size the data carries, under the series names. Without it a reader can see that one blot is bigger and cannot say by how much, because area is the one encoding nobody reads off a scale by eye. It costs plot height, like the series strip and for the same reason, and it is off by default so a scatter with no sizes never pays for it. |
| `valueSuffix` | primitive | `string` |  | Appended verbatim to every number the chart draws: both axes' ticks, the tooltip and the accessible table. Carries its own leading space if one is wanted. It reaches BOTH axes, so leave it off when the two quantities are not in the same unit, which on a scatter is the common case. |
| `valuePrefix` | primitive | `string` |  | Drawn verbatim before every number the chart writes, as valueSuffix is drawn after it, and on both axes for the same reason. |
| `valueFormat` | object | `ArenaNumberFormat` |  | How each number is written before the prefix and suffix are added: which locale, how many fraction digits, whether thousands are grouped, whether large numbers are compacted. Absent, the raw JavaScript number. |
| `height` | primitive | `number` | `280` | The plot's height in px, the --chart-height token by default. A number rather than a dimension string, because the chart does arithmetic with it to place every mark. |

<!-- @api end -->

```html
<arena-scatter-chart label="Latency against load" [series]="clouds()"
                     xLabel="Concurrent requests" yLabel="p95 latency (ms)" />
```

### Why the series type is a different one

`ArenaPointSeries` is not a variant of `ArenaSeries`, because the two disagree about what a mark
is: an `ArenaSeries` value takes its place on the axis from its index, and a pair carries both
coordinates. Folding them together would give every chart in the library a member most of them
cannot use, and would let a caller hand an indexed series to a chart with no index to read it
against.

It carries two parallel arrays rather than an array of `{ x, y }`, and that is a rule and not a
preference: a predefined object may hold an array of primitives and may not hold an array of
objects, because an array of objects reopens a nesting depth the reader has no bottom for. The
pairing by index is the same one `labels` and `values` already make on every other chart here,
and so is the rule when the two do not line up: **a mark is drawn only where both arrays have a
value**. A pair with half a coordinate is not a point, and inventing the other half is the one
thing a chart may not do.

### Both axes need naming

`xLabel` and `yLabel` are required. Every other chart here has one quantity and one set of
categories that name themselves; a scatter measures two things, and a table with bare X and Y
columns says which is which to nobody. They head the accessible table's columns and they name
the two figures in the tooltip.

`valueSuffix` and `valuePrefix` reach BOTH axes, so leave them off when the two quantities are
not in the same unit, which on a scatter is the common case.

### Reading it without a pointer

The cursor walks the marks in the order the accessible table lists them: series by series, and
within a series in the order given. That is deliberate, and it is why the two readings of this
chart agree. Walking them sorted by x was refused: it jumps between series and reads as one
sequence where there are several, and a scatter has no sequence of its own.

ArrowLeft and ArrowRight move it, Home and End jump to the ends, Escape clears it. The vertical
pair does nothing and is not consumed, so the page keeps its own scroll.

### A third quantity, as the size of the mark

A series that carries `r` turns this into a bubble chart. It is a third parallel array, paired
with `x` and `y` at the same index, for the reason those two are arrays and not an array of pairs.

**The mapping is by area, not by radius**, and that is the whole of the member. A reader compares
the blot, and doubling a radius quadruples the blot, so mapping the value onto the radius directly
would show a value four times larger as sixteen times the ink. `arenaRadiusAt` interpolates the
squared radius instead, so four times the value really is four times the area, and the suite
asserts that ratio rather than a table of radii.

`sizeLabel` becomes required the moment any series carries `r`. It is guarded at render rather
than declared required in the contract, because a scatter with no sizes has no third quantity to
name and a member required only sometimes cannot say so in a contract. A column headed "Size"
would satisfy the table mechanically and tell a reader nothing, which is the reason `label` is
guarded too.

A size that is absent, at the series or at one index, leaves the mark at the plain point radius
and its table cell empty. An unmeasured size is not a size of zero, and the mark keeps its place
because its POSITION was measured.

`sizeLegend` draws three sample bubbles under the series names, at the smallest, middle and
largest size in the data. Reach for it whenever `r` is doing real work: area is the one encoding
nobody reads off a scale by eye, so without a key a reader can see that one blot is bigger and
cannot say by how much. It costs plot height, like the series strip and for the same reason.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-activity-feed/ArenaActivityFeed.prompt.md -->

Arena event feed. Each item is an actor, an action, an optional target and an optional
time; `tone` colours the leading dot from ArenaBadge's vocabulary.

```html
<arena-activity-feed [items]="[
  { id: '1', actor: 'Marta', action: 'deployed', target: 'billing@2.4.1', time: '2m', tone: 'success' },
  { id: '2', actor: 'Ivan', action: 'opened an incident on', target: 'auth', time: '18m', tone: 'danger' },
  { id: '3', actor: 'Rae', action: 'approved the rollback', time: '1h' }
]" />
```

<!-- @api GENERATED from contracts/api/components/ArenaActivityFeed.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the feed for assistive technology. Required, and guarded at runtime: nothing can derive it, and a feed is a landmark a reader navigates BY, so say what the events are about ("Deployment activity"), never "Activity feed". |
| `items*` | array | `readonly ArenaActivityItem[]` |  | The events, newest first by convention. Each row is drawn by Arena; there is no per-item projection. |
| `busy` | primitive | `boolean` | `false` | Whether a multi-step update to the feed is in progress, reflected as `aria-busy`. Set it while rows are being loaded or replaced and clear it once they settle, so a screen reader announces the settled feed rather than each intermediate state. It is an input rather than something Arena infers: only the host knows when its own loading has finished. |

<!-- @api end -->

**Do / Don't**
- Keep the grammar. The actor is bold, the action is prose, the target is mono, a feed
  whose rows each read differently is a list, not a feed.
- Use `tone` for what the event *means*, not for variety. Seven tones cycling by row is
  decoration, and it makes the one row that matters invisible.
- Don't put controls in a row. A feed reports; an action on an event belongs on the thing
  itself.
- The dot is filled (`bg-current`, coloured by `tone`) even for `tone="danger"`, though
  danger is outline everywhere else, a tone dot is an identity mark, the same family as
  `ArenaTag`'s own dot and `ArenaAvatar`'s presence dot, not a danger surface.

**No row escape hatch**, on either layer. The API contract declares no per-item renderer,
because Angular has no binding for per-item projection, that would need a structural
directive and `ngTemplateOutlet`, which Arena does not ask a consumer to write. A consumer
needing a different row imports the exported `arenaActivityFeedStyles` and composes the slots
themselves.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-avatar/ArenaAvatar.prompt.md -->

Arena avatar, a person's or team's mark. `src` renders the image; without it the
initials of `name` render on the raised surface, so `name` is always worth passing.
`shape="circle"` is a person, `shape="rounded"` a team or organisation. `status` adds
a presence dot.

```html
<arena-avatar name="Juan Carlos Hidalgo" />
<arena-avatar name="Delivery" shape="rounded" size="sm" />
<arena-avatar [src]="user.photo" [name]="user.name" size="lg" status="online" />
```

<!-- @api GENERATED from contracts/api/components/ArenaAvatar.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `src` | primitive | `string` |  | Image URL. Absent renders initials from `name`. |
| `name` | primitive | `string` | `""` | The person or entity name. Its first two words' initials render when there is no `src`, and it is the image's alt text. |
| `size` | enum | `ArenaAvatarSize` | `"md"` | The avatar's diameter. |
| `shape` | enum | `ArenaAvatarShape` | `"circle"` | Circle for a person, rounded for a team. |
| `status` | enum | `ArenaAvatarStatus` |  | A presence dot in the state's colour. `offline` is a visible muted dot; omit `status` entirely for no dot. Optional: there is no invisible enum value. |

<!-- @api end -->

**Do / Don't**
- Always pass `name`, even with `src`: it is the image's `alt` text and the fallback
  when the image fails to load.
- Don't use the presence dot as a status badge for anything but presence, the
  offline tone is a muted grey by design and reads as "not here", not as "disabled".
- The presence dot is filled (`bg-success`/`bg-warning`/`bg-error`/`bg-base-content/(--level-presence)`)
  even though danger is outline everywhere else, presence is its own semantic
  family, not a danger surface. convention section.
- Don't put an avatar in place of an icon. It represents a person or an entity; a
  role or an action is an icon.

**Three things products asked this component for, and what each one measured.** Each is
recorded here because reading the code does not answer it, and every one of them was refused
with a reason rather than deferred.

- **A size past `lg`.** A profile header several times `lg` is a consumer-product measurement,
  and `lg` is already the largest step this scale names, the one a profile header in an
  application wears. The repertoire is four steps and not a length, so the product that wants a
  150px portrait re-values the scale inside its own scope, which is one line and stays that
  product's.
- **A ring around it.** The ask is a story ring, whose two states are a gradient and a grey, and
  a `ring` member taking a tone would hand that product two solid rings and lose the mark it was
  built for: an appearance selects the ring by its part and never by the value of a variant. A
  ring drawn as two padded circles around the avatar is markup the product owns, and it is
  exactly what the one product that wanted it wrote.
- **A group of them.** An assignee stack is negative margin over the sizes this component already
  ships, plus an overflow count, in about five lines. One product built it, and it is the one ask
  on this list a consumer composes out of what is already here.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-badge/ArenaBadge.prompt.md -->

Arena status label, mono, uppercase, short. Standalone, `OnPush`, signal input.
The host **is** the chip: it binds the root slot, so an attribute you write on
`<arena-badge>` lands on the chip itself.

```html
<arena-badge tone="success" dot>Deployed</arena-badge>
<arena-badge tone="warning">In review</arena-badge>
<arena-badge>Draft</arena-badge>
```

<!-- @api GENERATED from contracts/api/components/ArenaBadge.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The label text. Short: a badge is a chip, not a sentence. |
| `tone` | enum | `ArenaTone` | `"neutral"` | System status (success/warning/danger/info) reflects an object's actual state; emphasis (accent, gold) is editorial; neutral carries no semantic weight. |
| `dot` | primitive | `boolean` | `false` | Draws a filled dot in the tone colour before the label. |

<!-- @api end -->

**Tone taxonomy.** Two families, and they are not mixed:
- **Status**: `success` `warning` `danger` `info`: the actual state of the system
  (a deploy, a service, a version). `dot` reinforces "live status".
- **Emphasis**: `accent` (new/featured), `gold` (priority/distinction): editorial,
  and never a state. `neutral` carries no semantic weight.

**Do / Don't**
- Keep the label to one or two words. A badge is a chip, not a sentence, if it
  runs longer, it is not a badge.
- Don't use `accent` to communicate a status; reserve its crimson for
  "new/featured", and reach for a status tone when the badge reports state.
- Don't put `dot` on an emphasis tone. The dot means "this is live status", so on
  `accent` or `gold` it claims something the tone does not.
- Don't reach for a badge when the label can be dismissed or acted on: that is
  `arena-tag`, which owns `removable` and a real `<button>`. A badge has no
  interactive affordance at all, and its behaviour binding says so.
- Don't write a `class` or an ARIA attribute on `<arena-badge>` expecting it to
  reach the chip: the root slot is host-bound, so the host **is** the chip and a
  static `class` on it is overwritten by Arena's own styling. Wrap it in your own element
  when you need to position it.

**By hand, in a real browser** (`bun run demos`, then this component's own
playground or any page composing it):
- Each of the seven tones reads as its own colour against `--surface-card`, and
  the mono uppercase treatment survives at the smallest text size.
- With `dot`, the dot takes the tone's own ink (`bg-current`) rather than a
  second colour.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-calendar-event/ArenaCalendarEvent.prompt.md -->

One event on an `arena-calendar`'s schedule. It is content of a calendar and nothing else: its top, its height, the column it shares with its overlaps, its ramp colour and its place in the grid's keyboard order all come from the calendar it pulls them out of. **Outside one it throws `NG0201`**: `ArenaCalendarState` is not optional, and an unplaced chip is not a thing worth rendering.

```html
<arena-calendar timeZone="Europe/Madrid">
  @for (c of classes(); track c.id) {
    <arena-calendar-event [id]="c.id" [title]="c.name" [start]="c.start" [end]="c.end"
                          [colorId]="c.room" (click)="open(c)" />
  }
</arena-calendar>
```

<!-- @api GENERATED from contracts/api/components/ArenaCalendarEvent.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `id*` | primitive | `string` |  | Stable identity, so a host can switch on it rather than on the title. |
| `title*` | primitive | `string` |  | What the chip reads. |
| `start*` | primitive | `string` |  | ISO datetime the event begins. |
| `end*` | primitive | `string` |  | ISO datetime the event ends. |
| `colorId` | enum | `ArenaCatSlot` |  | Identity colour. Give the same entity the same slot everywhere and it keeps its colour across views. |
| `interactive` | primitive | `boolean` | `false` | Whether the chip can be activated. A boolean rather than "is `click` bound?", because Arena never derives what it draws from what a consumer listens for, and the same member `ArenaTableRow.interactive` is for the same reason. An interactive chip is a <button> a keyboard user reaches with Enter from the hour cell it overlaps; a non-interactive one draws the same chip with no role and no activation, so a read-only schedule announces events rather than a screenful of buttons that do nothing. |
| `actionsEnabled` | primitive | `boolean` | `false` | Whether the chip shows its action button. A boolean rather than "is the actions slot filled?": Arena never derives what it draws from what a consumer listens for, because projected content is not inspectable in at least one platform, so gating the drawing on it is a divergence waiting to happen. |
| `actions` | slot |  |  | The action panel's content, revealed by the chip's action button. Rendered only while the panel is open, so a consumer's own controls never sit permanently in the grid's Tab sequence. |
| `disabled` | primitive | `boolean` | `false` | Whether the chip is drawn but cannot be activated: an event a consumer's rules lock, such as one already past or owned by someone else. It reflects through `aria-disabled` rather than the native `disabled` attribute, so the chip keeps its place in the grid's roving Tab sequence and is announced as unavailable instead of disappearing from it. With `interactive` false there is nothing to activate and the chip is inert already. |
| `click` | event |  |  | The chip was activated. No payload: the consumer wrote this element, so they already hold the event this is about. Never emitted while `disabled`. |

<!-- @api end -->

`id`, `title`, `start` and `end` are all required and **throw** when blank, `input.required` proves only that something was bound. `start` and `end` are ISO datetimes, read in the calendar's `timeZone` and never the reader's.

**`click` carries no payload, deliberately.** You wrote this element, so your handler already closes over the record it came from.

**`interactive` is what makes the chip a button, not `(click)`.** The shape cannot be derived from whether anything is subscribed, so activation is a member you declare, the same one `arena-table-row` carries. **Bind `interactive` alongside `(click)`, or the chip is inert**: a `<div>` with no role, nothing to activate and nothing to disable, which is what a read-only schedule wants.

**A `(click)` binding on `<arena-calendar-event>` is the DOM event, not the output.** Angular binds a native event name to the DOM even when the component declares an output of that name, so a click that bubbles out of an inert chip still reaches your handler. An interactive chip stops propagation before it can; an inert one does not, because it claims nothing and the click belongs to the day underneath it. Listen for activation on a chip you have declared `interactive`.

**An interactive chip is not a page-level tab stop, and that is on purpose.** The grid is one tab stop; Enter from the hour cell an event overlaps steps into the chip, Escape steps back out to the cell.

What "into the chip" means depends on the shape. A chip with no action panel *is* the button. A chip with one cannot be, a kebab nested inside a button is invalid HTML, so the chip is a `<div>`, the title and time move into a body `<button>` inside it, and that body is what Enter focuses. The focus target registered with the calendar has to follow that element; a target left pointing at the chip sends Enter on a paneled chip nowhere at all.

**The kebab is reachable by arrows rather than Tab.** With focus on a chip, `ArrowRight` steps to its kebab and `ArrowLeft` steps back. Tab has to *leave* a composite, and a tabbable kebab is precisely what would stop the calendar's grid being the single tab stop its `grid` binding claims. Activating the kebab opens the panel and moves focus into it; `Escape` closes the panel and returns focus to the kebab, and stops there rather than also returning focus to the hour cell.

**`actionsEnabled` draws a kebab; `[actions]` is what the panel behind it holds.**

```html
<arena-calendar-event [id]="c.id" [title]="c.name" [start]="c.start" [end]="c.end"
                      (click)="open(c)" actionsEnabled>
  <arena-button actions size="sm" variant="ghost" icon="ph-bold ph-pencil">Edit</arena-button>
  <arena-button actions size="sm" variant="ghost" icon="ph-bold ph-trash">Delete</arena-button>
</arena-calendar-event>
```

**The boolean is what draws the kebab, not the slot being filled**, and unlike the calendar's toolbar this slot needs no marker directive: `select="[actions]"` is a plain CSS selector, and only `contentChild` detection would need `ArenaActions` imported. `actionsEnabled` with nothing projected draws a kebab over an empty panel; that is a consumer mistake rather than a state Arena hides, and it is the same call `arena-alert`'s and `arena-toast`'s `dismissible` already record.

**The panel's content is in the tree only while the panel is open.** That is what keeps the grid at one tab stop. It also means the panel is not a place to keep state, it is created and destroyed with every open.

**Do**
- Give the same entity the same `colorId` everywhere it appears.
- Preformat the `title`. Arena does no locale formatting and no truncation beyond the chip's own ellipsis.
- Keep the panel to a couple of controls. It opens over the schedule at the chip's own width.
- Project `[actions]` whenever you set `actionsEnabled`. The two travel together.
- Reach for `disabled` when the event is drawn but must not be opened, one already past, or one owned by someone else. It reflects through `aria-disabled`, so the chip keeps its place in the grid's roving sequence and is announced as unavailable instead of disappearing from it, and `click` never fires while it is set.

**Don't**
- Don't project content into it other than `[actions]`. The title and the time line are the chip body, and Arena draws both.
- Don't render one outside an `arena-calendar`. It has no position of its own and will throw.
- Don't use `disabled` to make a chip inert. In this layer nothing does (see the divergence above), and `disabled` means "a button that announces it cannot be pressed right now", which reads differently to a screen reader.
- Don't reach past `colorId: 8`. There are eight ramp slots and they never cycle.
- Don't reach for `style` or `class` to place it. Its geometry is the calendar's, and a `class` on the host lands on an element that declares `display: contents`.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-calendar/ArenaCalendar.prompt.md -->

Week or day schedule on a time grid: a toolbar, one column per day, events positioned by their wall-clock span. Use it for an agenda someone reads against the clock: bookings, classes, shifts. It is not a date picker (use `arena-input type="date"`) and not a month planner (Arena ships no month grid).

**The events are its content.** Write one `<arena-calendar-event>` per event; `arena-calendar` reads each one's `start`, `end` and `colorId`, works out where the chip goes, and each chip reads that placement back out. There is no `events` input, and no throw for projecting nothing: a calendar with no children is a legitimately empty schedule, not a caller's mistake.

```html
<arena-calendar timeZone="Europe/Madrid" (rangeChange)="refetch($event)">
  <arena-button actions size="sm" variant="secondary">New class</arena-button>
  @for (c of classes(); track c.id) {
    <arena-calendar-event [id]="c.id" [title]="c.name" [start]="c.start" [end]="c.end"
                          [colorId]="c.room" (click)="open(c)" />
  }
</arena-calendar>
```

<!-- @api GENERATED from contracts/api/components/ArenaCalendar.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | One ArenaCalendarEvent per event. ArenaCalendar reads each one's start, end and colorId and settles where the chip goes, what colour it takes and how the keyboard reaches it; the chip itself is ArenaCalendarEvent's. |
| `timeZone` | primitive | `string` |  | IANA zone name. Defaults to the reader's own resolved zone, which is right whenever the schedule belongs to the person looking at it. Pass it when the calendar has a zone of its own that differs (a Madrid timetable read from Tokyo), and when server-rendering, where the reader's zone is not knowable. |
| `anchorDate` | primitive | `string` |  | ISO date the view opens on. Defaults to today in `timeZone`; pass and change it to drive the date yourself. |
| `view` | enum | `ArenaCalendarView` |  | Omit to derive from the CONTAINER width: day below --bp-md, else week. |
| `dayStart` | primitive | `string` |  | HH:MM the grid starts at. Defaults to the earliest visible event's hour, floored. |
| `dayEnd` | primitive | `string` | `"23:00"` | HH:MM the grid ends at. |
| `weekStartsOn` | primitive | `number` | `1` | 0 = Sunday … 6 = Saturday. |
| `hideEmptyWeekend` | primitive | `boolean` | `true` | Drop Sunday from the week unless an event falls on it. |
| `dayInteractive` | primitive | `boolean` | `false` | Whether a day can be activated. A boolean rather than "is `dateClick` bound?", because Arena never derives what it draws from what a consumer listens for, and the same member `ArenaTableRow.interactive` and `ArenaCalendarEvent.interactive` are for the same reason; here the derived render was the day's own cursor, and the layers diverged on screen because of it. With it on, the day header is a <button> (the keyboard's route to the date, and the one element that already names it), and the column background takes a pointer cursor; with it off both are inert and the cursor says so. The default is false because a schedule someone only reads is the ordinary calendar, and a pointer cursor over days that answer nothing is the defect this member exists to end. |
| `dateClick` | event | `string` |  | A day header or column background was activated; carries the ISO date. Never emitted unless `dayInteractive`. |
| `rangeChange` | event | `string` |  | The anchor moved via prev/Today/next; carries the new ISO date. A date rather than a delta, because Today is not a delta. |
| `actions` | slot |  |  | Right-aligned in the toolbar, beside the range title. |

<!-- @api end -->

`timeZone` is optional and defaults to the reader's own resolved zone, which is right whenever the schedule belongs to whoever is looking at it. **Pass it when the calendar has a zone of its own**: a class at 09:00 in Madrid must stay at 09:00 for a student loading the page from Lima, and only an explicit `timeZone="Europe/Madrid"` says so. It is also **not safe under server rendering**: on a server it resolves to the *server's* zone and then to the client's on hydration.

The anchor is internal, so prev/Today/next work with nothing wired. `rangeChange` reports the new anchor date; take it as the cue to refetch. Bind `anchorDate` only when you want to drive the date yourself: it is a `linkedSignal` source, so it wins whenever it changes and resets any navigation the reader had done.

**The toolbar's actions slot needs its marker directive.** `<ng-content select="[actions]">` is drawn only when `contentChild(ArenaActions)` resolves, so a consumer who writes `actions` on an element without importing `ArenaActions` from the layer root gets no toolbar actions and no error. That is the one failure mode of every marker slot in this layer.

**The range in the toolbar is a label, not a heading.** It says which dates are on screen and is
rewritten every time the reader steps a week, so a document outline built on it would carry
"13 – 15 Jul 2026" where the name of a region belongs. The region is named already: the grid takes
an `aria-label` composed from the same range, which is what a reader arriving by name lands on.
The heading that says what this calendar IS belongs outside it, on the `arena-section` or the page
head that holds it.

**A day is activable only if you say so.** `dateClick` emits the ISO date of the day a reader picked, and it emits for nobody unless `dayInteractive` is bound too:

```html
<arena-calendar dayInteractive (dateClick)="openDay($event)">
```

The boolean is not ceremony. What a component draws may never be derived from whether a listener is bound, because a subscriber list is private here, so the day's cursor, which is a render, follows the boolean and not your binding. **With it on, each day header becomes a `<button>`** carrying the full date as its label, so a keyboard reaches a day at the one element that already names it; the column background takes the same click but stays pointer-only, because it is the same date reachable above.

**Keyboard.** The grid is one tab stop, not one per event (`dayInteractive` adds the header strip's, above it). Tab lands on a single hour cell; **a row is a day**, so Left/Right move a day and Up/Down move an hour, Home/End jump to the first/last hour of the focused day, and focus clamps at every edge. Enter steps into the first event overlapping the focused hour, Escape steps back out to the cell.

**A chip is not a DOM child of its day column, and `aria-owns` is why that does not matter.** This layer cannot project one set of children into several positions, so every chip is a child of the grid and each day column claims its own through `aria-owns`, which is what the `grid` pattern actually asks for, since it constrains the accessibility tree and not the DOM. It is the shape Arena renders everywhere, so a chip sits in the same place in every layer. Two consequences are real: the day columns are CSS grid **tracks** rather than flex items, because a chip's horizontal placement is a percentage of the whole grid and unequal columns would slide the last day's chips off; and anything projected that is not an `arena-calendar-event` becomes a **grid item** and adds a column, so project nothing else.

**The chip body is Arena's, and there is nothing you can put inside it.** An `arena-calendar-event` carries `id`, `title`, `start`, `end` and `colorId`, and Arena draws all of it. There is no per-event template, because a structural directive returning markup is not a member of any Arena contract.

**So a consumer cannot mark an event cancelled or tentative at all.** Colour is spoken for by identity, and the non-chromatic channel a strikethrough or a dashed border would have used is not reachable. Say it in the `title` (`'Ballet I, cancelled'`), or do not render an event for it and show it somewhere that is not the schedule.

**Do**
- Give an entity a stable `colorId` and reuse it everywhere that entity appears, which is what makes the ramp identity rather than decoration.
- Let `dayStart` default. It follows the earliest event, so a schedule that begins at 16:00 does not open on eight empty morning rows.
- Set `weekStartsOn` and `hideEmptyWeekend` to your locale and product. The defaults (Monday, Sunday hidden until used) are defaults, not the system's opinion.
- Preformat every `title` you pass. The calendar does no locale and no truncation of your own text beyond the chip's ellipsis.

**Don't**
- Don't try to paint an event `--danger` to mean cancelled. You cannot: `colorId` picks a ramp slot and nothing else, and identity and meaning in one palette makes both unreadable. Same rule the charts enforce.
- Don't reach past `colorId: 8`. There are eight slots and they never cycle; a ninth entity wrapping to slot 1 claims two different things are the same thing.
- Don't feed it multi-day or all-day events. There is no all-day row: an event running past midnight is clamped to the end of the day it started on.
- Don't project anything but `arena-calendar-event` into the default slot. Anything else lands in the grid as a track of its own.
- Don't wrap it to add a month view or a mini datepicker and call it Arena. Arena ships no month grid, and the date control is the native one, `type="date"` on `arena-input`; a hand-rolled one in your product is exactly the `fullcalendar-overrides.css` story that put this component here.

## Verifying by hand

happy-dom does no layout, so the geometry below is checked in a real browser and
nowhere else. `bun run build:angular-demo && bun run demos`, then open
`frameworks/angular/components/display/arena-calendar/ArenaCalendar.demo.generated.html`:

1. Tab reaches the schedule ONCE, and one more Tab leaves it. No chip and no
   kebab is a stop of its own. An OPEN panel is the exception and is meant to be.
2. From an hour cell, Enter steps into an event chip; Escape steps back out. Walk
   a chip with a panel as well as one without, since they are different elements.
3. Arrow keys move by day and hour, and clamp at all four edges.
4. **Every chip sits inside its own day column**, with an even gutter each side.
   This is the one claim no suite can make: read a day column's track boundaries
   and the chip's own `getBoundingClientRect().left` and confirm. A chip crossing
   a column border means the tracks are no longer equal.
5. On a chip carrying a kebab, the title stops before the button and ellipsises
   there. Check a full-width chip and a half-width one.
6. A short event, 30 minutes or less, still shows its whole title. Its chip is
   at the height floor, and that floor is an outer height under `border-box`.
7. A chip sharing its slot with an overlap draws no time label; one that has the
   column to itself does.
8. On a chip that shares its column and is at least 56px tall, the kebab sits at
   the BOTTOM-right with the title running the full width above it. Open the
   panel in that case too: it hangs below the chip and every control is clickable.
9. The now line is drawn over the chips rather than under them, being the last child of
   the grid and carries no z-index of its own.
10. **Enter and Space on a focused day header fire `dateClick`.** That is the
    browser's own activation of a `<button>`, so no suite can claim it: happy-dom
    has no such behaviour and a test for it would pass against a `<div>` too. Tab
    through the headers, fire both keys, and confirm one more Tab past the last one
    lands on the grid's single roving cell.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-card/ArenaCard.prompt.md -->

Arena surface container, the hairline border on the base surface scale, with an
optional header. Standalone, `OnPush`, signal inputs. **The root slot is NOT host-bound**,
and that is forced rather than chosen: `click` is an output whose name is also a native DOM
event, and Angular installs both a DOM listener and an output subscription for such a name, so
a host that both
listens and emits re-enters its own listener on every emission. Arena's own styling lands on an inner
`<div>` that stops propagation, the shape `arena-side-nav-item` and `arena-table-row` already
take, and the host goes `display: contents`.

```html
<arena-card [eyebrow]="'Delivery'" [title]="'Client Portal'">
  <arena-badge action tone="success">Deployed</arena-badge>
  <p>Everything the client can see, in one place.</p>
</arena-card>

<arena-card floating>Just a surface, with no header block at all.</arena-card>

<arena-card interactive [title]="'checkout-api'" (click)="open(service)">Healthy, 14 replicas</arena-card>
```

<!-- @api GENERATED from contracts/api/components/ArenaCard.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The card's body, below the optional header. |
| `interactive` | primitive | `boolean` | `false` | Whether the whole card is one activation target, which is the ordinary shape of a list on a phone. A boolean rather than "is `click` bound?", because Arena never derives what it draws from what a consumer listens for, the same reason ArenaTableRow.interactive is one. An interactive card is a role="button" tab stop with an Enter/Space handler and the surface's own hover and focus states; a non-interactive one is inert and adds no tab stop, because a dead stop on every card of every list is worse than the gap it would close. It is a ROLE rather than a <button> element for the same reason ArenaTableRow's card shape is: a card body may hold controls of its own, and a control inside a control is reachable by nobody. |
| `disabled` | primitive | `boolean` | `false` | Whether an interactive card is drawn but cannot be activated. It reflects through aria-disabled rather than any native attribute, and the card stays in the tab order rather than leaving it, because a disabled control nobody can reach is a control nobody knows exists. Without `interactive` there is nothing to disable and the card is inert already. |
| `href` | primitive | `string` |  | Present => the card renders an <a>; absent, with `interactive`, a role="button". The same split, and the same reason, as ArenaSideNavItem.href: a control that navigates must be a link, openable in a new tab, address copyable, announced as a link, and none of that can be rebuilt on a div. A primary click with no modifier is cancelled and reported through `click`, so a router owns it; ctrl, meta, shift, alt, a middle click and a context menu stay the browser's and report nothing. It implies interaction on its own, so `interactive` is not also required, and with `disabled` it refuses activation through aria-disabled the way an item does. The card's own content still holds whatever controls it holds; a control inside the anchor is a control inside a link, which is the price of making the whole surface the target and the reason `interactive` exists as the alternative. |
| `action` | slot |  |  | Right-aligned in the header, beside the title. Arena draws the header row; the consumer draws what sits in it. |
| `title` | primitive | `string` |  | Header title. Absent, along with eyebrow and action, renders no header block at all. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h3"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h3` because a card is the bottom rung of the title ladder, under the heading a section draws and two under a page's own, which is where a card lands on a page that says nothing else. `none` draws the title with no heading at all, for a card whose title labels the surface rather than naming a region; with no title there is no heading either way. |
| `eyebrow` | primitive | `string` |  | Mono uppercase label above the title, in the accent colour. |
| `floating` | primitive | `boolean` | `false` | Adds the warm shadow. Depth comes from the shadow and the surface scale, never a gradient. |
| `accent` | primitive | `boolean` | `false` | Draws the border in the accent colour instead of the surface hairline. |
| `click` | event |  |  | An interactive card was activated, by pointer or by Enter or Space. With `href` it is also how the card reports the one activation a router owns, a primary click or Enter with no modifier, and Arena has already cancelled the anchor's own navigation by the time it fires; a modified or middle click is the browser's and does not fire it at all. No payload, because the consumer wrote this element and already holds what it is about. |

<!-- @api end -->

**`interactive` makes the whole card one activation target**, which is the ordinary shape of a
list on a phone, and it is a declared boolean rather than "is `(click)` bound?", because Arena never derives what it draws from what a consumer listens for,
the same one `arena-table-row`'s `interactive` gives. Arena writes `role="button"`, a tab stop and
an Enter/Space handler, and draws the surface's own hover and focus states. Without it the card is
inert and adds no tab stop, because a dead stop on every card of every list is worse than the gap
it would close.

**An interactive card is a `role="button"` div and never a `<button>` element**, because a card
body is where a consumer puts their own controls and a control nested inside a control is
reachable by nobody.

**A press that starts on one of those controls belongs to that control, by pointer and by keyboard
alike.** Clicking a button inside the card runs the button's handler and stops there; Enter typed
into a field inside it never opens the card. Both paths ask the same question, and the question is
"did this press start on a control", not "did it land on the card's own element": a click anywhere
else on the card, its title, its body, the space between them, is the card being pressed and
activates it. That covers the `action` slot too, where a header button is the common case.

**A card can also hand the press over entirely, by leaving `interactive` off.** Then it draws no
role, no tab stop and no handler at all: it is a surface, and the control inside it is the only
activation target on it.

```html
<arena-card title="Acme Corp">
  <p>Everything the client can see.</p>
  <arena-button (click)="open('acme')">Open</arena-button>
</arena-card>
```

Reach for `interactive` when the whole surface is the target and a control inside it is a second
route to the same place. Leave it off when the press means something narrower than "this card".

The `action` slot is an attribute selector, which is this layer's whole projection
convention: write `action` on the element that goes beside the title. With no
`title`, no `eyebrow` and nothing marked `action`, the header block does not
render, the card is a plain surface.

**Do / Don't**
- **Bind `title`, don't write it as a static attribute.** `<arena-card title="X">`
  leaves a real `title` attribute on the host, and the browser draws a tooltip over
  the whole card. `[title]="'X'"` does not. This is layer-wide rather than ArenaCard's
  own: Angular writes a static attribute during the creation pass whether or not it
  also matches an input. This host clears it (`'[attr.title]': 'null'`), which the
  layer holds in both directions, so the binding above is the clearer spelling rather
  than a workaround.
- Depth comes from `floating`'s warm shadow and the `base-100`→`base-200`→`base-300`
  surface scale. Never a gradient.
- Reach for `accent` to mark one card among several as the current or featured one;
  it draws the border in the accent colour and nothing else. It is not a status.
- Don't write a `class` on `<arena-card>` expecting it to reach the card: the host is
  bare and out of layout, so an attribute written there lands on nothing anyone can
  see. That is the price of the carve-out above, and there is no second route in. To
  size, constrain or position a card, wrap it in your own element rather than
  reaching through it.
- Don't nest a card inside a card. The surface scale has three steps and a card is
  one of them; a card on a card reads as a mistake rather than as depth.

**By hand, in a real browser** (`bun run build:angular-demo && bun run demos`, then
`frameworks/angular/components/display/arena-card/ArenaCard.demo.generated.html`):
- An interactive card takes the hover surface, and one Tab reaches it and shows the focus ring.
  Enter and Space both open it, and Space does not scroll the page underneath.
- The disabled card is still reached by Tab and still announces itself, and neither key nor
  pointer activates it.
- On the card holding a field, typing Enter in the field does not open the card, and the badge
  and the field keep their own presses.
- `floating` casts the warm shadow and the borderless variant does not, with no
  gradient on either.
- A long body wraps inside the padding rather than escaping the radius: the root
  clips with `overflow-hidden`, so a wide child is cropped rather than overflowing.
- With only an `action` and no title or eyebrow, the header still renders and the
  action sits right-aligned against an empty title block.

### A card that navigates

`href` makes the whole card a real `<a>`: openable in a new tab, address copyable, announced
as a link. It is the same split, and the same reason, as `arena-side-nav-item`'s own `href`,
and it implies interaction on its own, so `interactive` is not also needed. With `disabled` it
refuses activation through `aria-disabled` and prevents the anchor's default, the way an item
does.

```html
<arena-card href="/clients/acme" title="Acme Corp" (click)="go('/clients/acme')">
  <p>Everything the client can see.</p>
</arena-card>
```

**`href` reports its plain activation through `(click)`**, so `router.navigateByUrl` in that
handler is the whole bridge and the page does not reload. The modified clicks stay the
browser's and fire nothing, which is why the member is worth having over `interactive`. Bind
nothing and the card is a plain link that navigates the document, which is the right shape
outside a single-page application.

**`(click)` on `arena-card` is two bindings wearing one name, and the card resolves it.** Angular
subscribes the binding to the component's `click` output *and* adds a native listener for the DOM
event of the same name, so a click that reaches the host is counted twice. The card stops
propagation on its own anchor, which is what makes `(click)` fire exactly once for the activation
it owns and not at all for the ones it leaves to the browser. Both halves are pinned; the
consequence for you is that a click delegated from an ancestor of the card never sees an
activation the card handled.

**Do not put `routerLink` on `arena-card`.** It would not work: `RouterLink` decides whether
it is on an anchor from the host's `tagName`, and `arena-card` is neither an `<a>` nor a
registered custom element, so it ignores every modifier key and lands a second tab stop on the
host, over the anchor the card already draws inside itself. That is the reason `(click)` reports
the activation at all.

Choose between the two by what the press DOES. A card that goes somewhere is `href`; a card
that changes local state is `interactive` with `(click)`. And a card whose body holds controls
of its own is `interactive`, not `href`: the anchor wraps the whole surface, so a button inside
it is a control inside a link, which is exactly the nesting `interactive` was made a
`role="button"` div to avoid.

**How it is built, and why that is worth knowing.** The card projects into two slots, and
Angular hands projected content to the first matching one, so two branches cannot each carry
their own `<ng-content>`. Both projections live in one `<ng-template>` that whichever branch
renders stamps out with `ngTemplateOutlet`. Toggling `href` at runtime in either direction
keeps the content, once, inside the new root, and that is asserted rather than assumed. Nothing in Angular's documentation settles that, and an empty card would
be a silent failure.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-key-value/ArenaKeyValue.prompt.md -->

Arena key value, a list of terms and the values against them with an optional summed row ruled off
at the bottom. Standalone, `OnPush`, signal I/O. The host takes itself out of layout with
`display: contents` and the real `<dl>` is inside, because the association between a term and its
value has to be the platform's.

```html
<arena-key-value [rows]="summaryRows()" [total]="{ term: 'Total', value: money(totalCents), numeric: true }" />
```

<!-- @api GENERATED from contracts/api/components/ArenaKeyValue.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `rows*` | array | `readonly ArenaKeyValueRow[]` |  | The rows, in the order they are given. An empty array renders an empty list rather than throwing, because a summary with nothing to adjust is a state a basket reaches on its way to being filled and not a mistake in the markup. |
| `total` | object | `ArenaKeyValueRow` |  | The row the others add up to, drawn last, ruled off above and set in the heading register. It is a member rather than the last element of rows because the rule and the register are what say a total is a total, and deriving that from position would make the last adjustment in a list look like one. |

<!-- @api end -->

**Each row is a `<dt>` and a `<dd>` in a wrapper**, which is the shape a definition list takes when
the pair has to sit on one line.

**`numeric` is what keeps a money column from jittering.** It sets the value in the mono face with
tabular numerals, so a column of figures aligns by digit as it changes. It is per row because a
summary mixes an address with a price and only one of them is a figure.

**`total` is a member and not the last row.** The rule above it and the heading register are what
say a total is a total; deriving that from position would make the last adjustment in a list look
like one.

**Do / Don't**
- **Do** format the value before you pass it. Every value is a string, which is what a summary row
  actually holds: a price, a method, an address, a count.
- **Do** leave `rows` empty when there is nothing to adjust yet. An empty list is a state a basket
  reaches on its way to being filled.
- **Don't** reach for it for a table. Two columns of data with a header row are an `arena-table`.
- **Don't** put a control in a value. Every value is text; a row that has to be acted on belongs in
  a list you wrote.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/display/arena-key-value/ArenaKeyValue.demo.generated.html`:
- The figures align by digit down the column, and stay aligned as the values change.
- The total is ruled off above and reads a register heavier than the rows over it.
- With a screen reader running, each value is announced with the term it belongs to.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-people-list/ArenaPeopleList.prompt.md -->

A list of people. Standings, assignees, members, suggestions: a face, a name and, where the list
is about a quantity, a figure at the end. Standalone, `OnPush`, signal inputs. The host takes
itself out of layout and the component renders the real `<ul>` or `<ol>`, because the semantics
of a list are the element and not a class.

```html
<arena-people-list label="Ruby league standings" ordered size="sm">
  @for (player of league(); track player.id) {
    <arena-person-row [rank]="player.rank" [name]="player.name" [src]="player.avatar"
                      [figure]="player.xp + ' XP'" [current]="player.isMe" />
  }
</arena-people-list>

<arena-people-list label="Suggested accounts">
  @for (account of suggestions(); track account.handle) {
    <arena-person-row [name]="account.name" [src]="account.avatar"
                      secondary="Followed by marisol.b">
      <arena-button action variant="ghost" size="sm">Follow</arena-button>
    </arena-person-row>
  }
</arena-people-list>
```

`size` is the list's, not the row's: the list provides it and each row pulls it, the same
direction `arena-radio` reads its group. The face, the name and the figure move together, and
rows in one list that disagreed about their size would be a defect rather than a design.

<!-- @api GENERATED from contracts/api/components/ArenaPeopleList.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the list for assistive technology: what these people are a list OF, never that they are people. "Ruby league standings", "Suggested accounts", never "People". Required and guarded at runtime rather than defaulted, because nothing can derive it and a name that only says what the component is satisfies the requirement mechanically while telling a screen-reader user nothing: two lists on one page announce identically. |
| `ordered` | primitive | `boolean` | `false` | Whether the order is part of the meaning. A standings table read in any other order is a different claim, and its rows are numbered; a set of suggestions is a set. It is a declared input rather than something inferred from the rows carrying a `rank`, because Arena never derives what it draws from what a consumer happened to pass, and a numbered list whose numbers are decoration is a lie told to a screen reader. |
| `size` | enum | `ArenaControlSize` | `"md"` | How big every row in the list is: the face, the name and the figure move together. It sits on the list rather than on the row because rows in one list that disagree about their size are a defect and never a design, and how the list hands it down is each layer's business rather than this contract's. |
| `content` | slot |  |  | The rows. One ArenaPersonRow per person; a row is what says who and how much, and the list decides only where each one goes. |

<!-- @api end -->

**Do / Don't**
- **Do** say what the list is OF in `label`: "Ruby league standings", "Reviewers on this pull
  request". It is the name a screen-reader user navigates by, and "People" tells them nothing.
- **Do** set `ordered` when the order is the meaning and the rows are numbered. It picks the
  element, `<ol>` against `<ul>`, which is where that claim lives.
- **Don't** reach for this to show one person. A single face beside a name is `arena-avatar` and
  your own markup.
- **Don't** use it for a feed of events: `arena-activity-feed` is somebody did something to
  something, and its rows are about the event rather than about the person.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/display/arena-people-list/ArenaPeopleList.demo.generated.html`:
- The three sizes move the face, the name, the figure and the row's own air together.
- `ordered` swaps the element and nothing else: no marker is drawn in either, because the rank
  is the row's own column.
- The reader's own row fills, and reads as one row rather than as a section.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-person-row/ArenaPersonRow.prompt.md -->

One person inside an `arena-people-list`: a face, a name, an optional line under it, an optional
position in front and an optional figure behind. Standalone, `OnPush`, signal inputs. The host
takes itself out of layout and the component renders the real `<li>`, so the row is a list item
of the list around it rather than an element between the two.

```html
<arena-person-row [rank]="4" name="Priya Raman" src="/img/priya.jpg" figure="1815 XP" current />

<arena-person-row name="Tomas Klein" secondary="Platform, on call">
  <arena-icon-button action icon="ph-bold ph-x" label="Remove Tomas Klein" size="sm" />
</arena-person-row>
```

The control at the end is projected with the `action` marker. `name` is the row's text, the
initials the face falls back to and the image's alt text at once, because a name spelt
differently in any of those is the same person announced as two.

<!-- @api GENERATED from contracts/api/components/ArenaPersonRow.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `name*` | primitive | `string` |  | The person or entity. It is the row's own text, the face's initials when there is no image, and that image's alt text, which is why one member carries all three: a name spelt differently in any of them is the same person announced as two. Required and guarded at runtime rather than defaulted, because nothing can derive who a row is about and a blank one draws a face, a rank and a figure around nobody. |
| `src` | primitive | `string` |  | The face's image. Absent, the row draws the initials `name` gives it, which is the same fallback ArenaAvatar states and the reason a row needs no second member for the picture. |
| `secondary` | primitive | `string` |  | One line under the name: a handle, a role, a team, why this person is being suggested. Prose rather than a value, so it is set in the body register and never in the numeric one. |
| `rank` | primitive | `number` |  | The position this row holds, drawn in front of the face in a column wide enough for the list's longest. It is the number a standings list is read by, so it is set in the numeric register, and it says nothing about the order the rows are in: that is `ArenaPeopleList.ordered`. |
| `figure` | primitive | `string` |  | The quantity this row is about, drawn at the end: a score, a count, a share. A string rather than a number because the unit travels with it and a row reading "1815 XP" is one value and not two, which also keeps the formatting where the data is. |
| `current` | primitive | `boolean` | `false` | Whether this row is the reader's own. It fills the row so it can be found without reading it, and it says so rather than only showing it, because a highlight nothing announces is a highlight half the readers do not get. |
| `action` | slot |  |  | One control at the end of the row: follow, invite, remove. It sits after the figure, and the row draws nothing for it beyond the space it takes. |

<!-- @api end -->

**Do / Don't**
- **Do** bind `rank`, `[rank]="4"`, rather than writing `rank="4"`: it takes a number and an
  unbound attribute hands it the string.
- **Do** put the unit in `figure`: "1815 XP", "12 open", "38%". It is one value a reader says out
  loud, and formatting it where the data is beats formatting it here.
- **Do** use `current` for the reader's own row. It fills the row and announces itself through
  `aria-current`, which is what a highlight has to do to be worth drawing.
- **Don't** wrap the row in a link. A row is not an activation target; project the control
  instead, where it keeps its own name and its own keyboard.
- **Don't** use it outside `arena-people-list`. The row pulls its size from the list, so one on
  its own has no list to read and no element to be a list item of.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-skeleton/ArenaSkeleton.prompt.md -->

Arena loading placeholder. It reserves the layout the real content will occupy, so a
table or a dashboard fills in rather than jumping. `variant="text"` with `lines`
renders a stack whose last line is short, the way a paragraph ends; `line`, `block`
and `circle` are single shapes. `width`, `height` and `radius` are CSS strings that
override the per-variant defaults; each applies only where the shape has
something to override; see the table below.

```html
<arena-skeleton variant="text" [lines]="3" />
<arena-skeleton variant="circle" />
<arena-skeleton variant="block" />
<arena-skeleton variant="block" width="12rem" height="72px" radius="var(--r-lg)" />
<arena-skeleton variant="circle" width="40px" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSkeleton.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `variant` | enum | `ArenaSkeletonVariant` | `"block"` | The shape the placeholder reserves. |
| `width` | primitive | `string` |  | CSS width, e.g. "100%" or "12rem". Defaults to full width. |
| `height` | primitive | `string` |  | CSS height. Defaults per variant. For the `circle` variant a single diameter is what is wanted, so `height` wins over `width` when both are set. |
| `lines` | primitive | `number` | `3` | Number of rows when variant="text". The last runs short. |
| `radius` | primitive | `string` |  | CSS border radius. Defaults to a small token radius. |

<!-- @api end -->

| variant | `width`        | `height`       | `radius`             |
|---------|----------------|----------------|-----------------------|
| `text`  | applies (stack)| no (rows fixed)| no (rows fixed)      |
| `line`  | applies        | applies        | no (fixed radius)    |
| `block` | applies        | applies        | applies                |
| `circle`| diameter (`height` wins if both are set) | same diameter | no (always a circle) |

**Do / Don't**
- Match the placeholder to the shape of what is loading, a circle for an avatar, a
  block for a card. A placeholder that does not match the content is a layout jump
  with extra steps.
- `radius` only affects `variant="block"`. Passing it to `circle`, `line` or `text`
  has no effect, a circle is always a perfect circle, and the rows stay a fixed
  small radius.
- Don't animate a skeleton that will be on screen for more than a moment or two: the
  shimmer stops entirely under `prefers-reduced-motion`, and it is decoration, not a
  progress report. Use `<arena-progress-bar>` when there is real progress to report.
- Don't wrap a single `<arena-skeleton>` in a live region of your own, because it already
  carries `role="status"`. A set of several is a different case: see below.

**A set of siblings is several announcements, on purpose.** Every variant carries its
own `role="status"`/`aria-label="Loading"` host bindings, with no exception for `circle`,
so a circle beside a text stack is two announcements and twenty rows of the same pair are
forty, each placeholder announces its own pending replacement, and the component has no
way to know where a set of them begins and ends. That repetition is between sibling
`<arena-skeleton>` elements only: a `variant="text"` stack already renders as one row per
line inside a single host, so its `lines` never repeat the announcement among themselves.
When several skeletons stand for one block of content, wrap the set yourself in a single
labelled region and hide the individual placeholders from the accessibility tree:

```html
<div role="status" aria-label="Loading profile">
  <div style="display:flex;gap:var(--sp-3)" aria-hidden="true">
    <arena-skeleton variant="circle" width="40px" />
    <arena-skeleton variant="text" [lines]="2" width="220px" />
  </div>
</div>
```

That turns two announcements into one and gives a screen-reader user a name for *what* is
loading rather than only that something is. Nothing about it is particular to this layer:
it is a composition decision you make per set.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-stat-card/ArenaStatCard.prompt.md -->

Arena metric tile. A mono micro-label, the number in display weight, and an optional
delta chip. `label` and `value` are required. Two tone dimensions answer two different
questions about the same number, and neither implies the other:

- `tone` says what state the number **IS in right now**: colors the value itself.
  A service at 99.98% uptime is healthy whether or not it improved this week, and
  two open incidents are two open incidents even when that is down from five.
- `delta.tone` says whether the number's last change was **good**; `delta.direction`
  says which way it pointed, colors the delta chip. Revenue down is bad, latency
  down is good, and the tile cannot know which metric it is showing.

`delta` is one object (`ArenaStatDelta`), not three flat inputs, per the API capability contract
(`contracts/api/components/ArenaStatCard.json`). The chip renders only when `delta.value` is
truthy; a `delta` carrying a `tone`/`direction` but an empty `value` renders no chip at all.

A tile can legitimately show `tone="danger"` with `delta.tone="positive"` in the
same breath, a bad state that is improving is still a bad state.

`delta` is bound from a property and never written as an object literal in the template, for
the reason the Don't list below gives:

```ts
protected readonly revenue: ArenaStatDelta = { value: '12%', direction: 'up', tone: 'positive' };
protected readonly latency: ArenaStatDelta = { value: '9%', direction: 'down', tone: 'positive' };
protected readonly incidents: ArenaStatDelta = { value: '2', direction: 'up', tone: 'positive' };
```

```html
<arena-stat-card label="Revenue" value="$48.2k" [delta]="revenue" />
<arena-stat-card label="p95 latency" value="184ms" [delta]="latency" />
<arena-stat-card label="Open incidents" value="3" tone="danger" [delta]="incidents" sub="2 acknowledged" />
```

<!-- @api GENERATED from contracts/api/components/ArenaStatCard.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Short uppercase microlabel, two words at most. |
| `value*` | primitive | `string` |  | Preformatted, e.g. "1,284" or "99.9%". ArenaStatCard never formats. |
| `tone` | enum | `ArenaTone` | `"neutral"` | What state the number IS in right now, as against how it moved. ArenaBadge's vocabulary. |
| `delta` | object | `ArenaStatDelta` |  | How the number moved. Absent renders no marker. |
| `sub` | primitive | `string` |  | Small muted line under the value: context, e.g. "vs last week". |
| `icon` | primitive | `string` |  | A Phosphor class name for a small glyph beside the label, drawn muted. Arena renders the aria-hidden wrapper and the `<i>`. |

<!-- @api end -->

`icon` is a Phosphor class name, not a slot, Arena draws the `<i>` and its
aria-hidden wrapper, and an unfilled `icon` renders no wrapper at all:

```html
<arena-stat-card label="Build time" value="4m 12s" [delta]="buildTime" icon="ph-bold ph-timer" />
```

**Do / Don't**
- Set `delta.tone` deliberately for every delta. It defaults to neutral, and a neutral
  delta on a metric where the direction matters is a missed signal, not a safe one.
- Set `tone` for what the number currently IS, not for how it moved, reach for
  `delta.tone`/`delta.direction` for that instead. Conflating the two loses the
  distinction that "Open incidents" above depends on: the value stays `danger`
  red while the chip still reads a positive green improvement.
- Don't hand `delta` a fresh object identity to change one field without meaning to,
  it is a single input, so `[delta]="{ value: v, direction: 'up' }"` in a template
  expression rebuilds the whole object every change-detection pass. Bind from a
  component property computed once instead.
- Don't fill the negative delta or the danger value. Both are text/outline in
  `--error`, the value slot carries no background at all, and the delta chip is
  `bg-transparent`, like every other danger surface in Arena except
  `ArenaConfirmDialog`'s final confirmation.
- Don't put a chart in a stat card, `arena-chart-card` is the tile that holds one.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-table-cell/ArenaTableCell.prompt.md -->

One cell of an `arena-table-row`. It is an **attribute on a real `<td>`**, not an element of its
own. It draws the cell box, the padding, the alignment and the mono/gold treatment its column asks
for, and in card mode either a label/value pair or a full-width block, and shows whatever you put in
it.

```html
<td arena-table-cell>{{ d.p95 }}</td>
<td arena-table-cell><arena-badge tone="danger" dot>Failed</arena-badge></td>
<td arena-table-cell><arena-button variant="ghost" size="sm">Details</arena-button></td>
```

<!-- @api GENERATED from contracts/api/components/ArenaTableCell.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | What the cell shows: a value, or one of Arena's own components, such as an ArenaBadge for a status or an ArenaButton for an action. This is what the compound shape exists for. The consumer instantiates one element per cell, so nothing here is per-item projection. |
| `href` | primitive | `string` |  | Present => the cell draws an <a> around its content, inside its own box, which is where HTML admits one and why this member is the cell's rather than the row's: an anchor wrapping a row would break the row/cell structure the grid is made of, and may not contain the button a cell's own contract invites. It carries the settled anchor convention rather than restating it, the fifth member to do so after ArenaCard.href, ArenaCommand.route, ArenaCrumb.href and ArenaSideNavItem.href: a primary click with no modifier is cancelled and reported through `navigate`, so a router owns it, and ctrl, meta, shift, alt, a middle click and a context menu stay the browser's and report nothing. The anchor is a tab stop of its own, which is the answer this table already gives for a control a consumer puts in a cell, so it is one Tab from the cell rather than a step-in the grid does not have. Inside a row carrying `interactive` the anchor wins and the row does not fire, because a press that lands on a control inside the row was never the row's. It survives both shapes: below --bp-md the anchor is still an anchor and does not compete with the row's role="button", by the same predicate. |
| `navigate` | event |  |  | The cell's anchor was activated by the one activation a router owns, a primary click with no modifier, and Arena has already cancelled the anchor's own navigation by the time it fires; a modified click, a middle click and a context menu are the browser's and do not fire it at all. No payload, because the consumer wrote this element and already holds what it is about, the same shape as ArenaTableRow.click. It is `navigate` rather than a `click` because the cell has no other activation to report: with no `href` there is no anchor, and an event that only ever fires for one member is named after what that member does. |

<!-- @api end -->

**Do / Don't**
- Put a value in it, or one of Arena's own components: an `arena-badge` for a status, an
  `arena-button` for an action. This is why the table is a compound primitive at all: a
  column's render function would be per-item projection, which this library does not do, but
  a cell **you** instantiate is just an element you wrote.
- Don't set alignment, width or the mono face here. Those are the column's, so a column stays
  consistent down its whole length; a cell that styled itself would drift from its header.
- Don't add a `role` or a `tabindex`. A `<td>` inside the grid already maps to a gridcell, and
  the roving tab stop belongs to the enclosing grid and is read from the shared state; adding your
  own would put a second tab stop inside a composite that must have exactly one.
- A control you put in a cell **is** a page-level tab stop, and that is deliberate. Arena
  cannot silence markup it does not own, and silencing it would take away a route a keyboard
  user has. Reaching it must cost exactly one Tab; step 2 of the by-hand checklist in
  `ArenaTable.prompt.md` is the standing check.
- Don't use it outside an `arena-table-row`. It injects that row's state, so outside one it
  is a DI error rather than a cell that quietly renders wrong.

### `href` makes the cell a real destination, and the row keeps its own

`href` draws an `<a>` around the cell's content, inside the cell box. That is the one place HTML
admits it: an anchor around the whole row would break the row and cell structure the grid is made
of, and an anchor may not contain the `arena-button` a cell's own contract invites into it.

```html
<td arena-table-cell [href]="'/ventas/' + v.id" (navigate)="router.navigate(['/ventas', v.id])">
  {{ v.number }}
</td>
```

It carries the anchor convention the four members before it carry, and does not restate it: a
**primary click with no modifier** is cancelled and reported through `(navigate)`, so your router
owns it; ctrl, meta, shift, alt, a middle click and a context menu stay the browser's and report
nothing at all, because the reader asked for a new tab or for the address.

**Inside a row carrying `interactive`, the anchor wins and the row does not fire.** That is not a
special case written for this member: it is the same rule the row already applies to a checkbox or a
button you put in a cell, that a press landing on a control inside the row was never the row's. So a
table can have a link in its first column and a clickable row under it, and one press runs one
destination. A cell with no `href` in the same row still activates it.

**The anchor is a tab stop of its own**, one Tab from the cell rather than a step-in the grid does
not have, which is the answer this table already gives for any control you draw in a cell. The
grid's `Enter` is the cell's and still activates the row; the anchor's `Enter` is the anchor's.

### What is shared, and therefore not yours

Its column, its layout and its place in the grid's keyboard order come from `ArenaTableState` and
`ArenaTableRowState`, which the table and the row provide and this component injects. None of it
is a member of `contracts/api/components/ArenaTableCell.json`, and a consumer never writes one.
The cell's whole API is what you project into it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-table-row/ArenaTableRow.prompt.md -->

One row of an `arena-table`. It is an **attribute on a real `<tr>`**, not an element of its own,
and its cells are attributes on real `<td>`s. Write one per row. It only makes sense inside a table:
it injects the shared `ArenaTableState`, and outside one that is a DI error rather than a silently
inert row.

```html
<tr arena-table-row interactive (click)="openDeploy(d)">
  <td arena-table-cell>{{ d.build }}</td>
  <td arena-table-cell>{{ d.project }}</td>
  <td arena-table-cell><arena-badge tone="success" dot>Deployed</arena-badge></td>
</tr>
```

<!-- @api GENERATED from contracts/api/components/ArenaTableRow.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The row's cells. One ArenaTableCell per cell; a row may carry fewer or more than there are columns, and the grid's cursor is clamped against what is really there. |
| `interactive` | primitive | `boolean` | `false` | Whether the row can be activated. A boolean rather than "is `click` bound?": Arena never derives what it draws from what a consumer listens for, because an outbound member's subscriber list is private in at least one platform and a consumer's binding leaves nothing in the DOM to detect, so deriving the interactive shape from it is a divergence waiting to happen, and it was one. Below --bp-md the row is a card, and an interactive card is a role="button" tab stop with an Enter/Space handler; a non-interactive one is inert, because a dead tab stop on every row of every table is worse than the gap it would close. |
| `disabled` | primitive | `boolean` | `false` | Whether the row is drawn but cannot be activated: a record the consumer's rules lock. It reflects through `aria-disabled` rather than the native attribute, and the card shape stays a role="button" in the tab order rather than leaving it, because a disabled control nobody can reach is a control nobody knows exists. With no `click` there is nothing to disable and the row is inert already. |
| `click` | event |  |  | The row was activated, by pointer or by Enter on one of its cells. No payload, because the consumer wrote this element and already holds the row this is about. |

<!-- @api end -->

**Do / Don't**
- `(click)` takes no payload. You wrote this element inside your own `@for`, so you already
  hold the row it is about; a payload would hand you back what you just had.
- Cells are **positional**: the nth `arena-table-cell` reads the nth entry of the table's
  `columns`. Keep them in the same order.
- Don't write a bare `<td>` as a child. A row's cells are read as `arena-table-cell`
  components, and a `<td>` without the attribute renders but takes no column, no alignment and no
  place in the keyboard order.
- Don't reach for the row to style a cell: alignment, width and the mono/gold treatment are
  the **column's**, so they stay the same all the way down.
- `disabled` draws the row and refuses to activate it, by either route: the pointer and the
  grid's `Enter`. It reflects through `aria-disabled` rather than the native attribute, so a
  locked row still announces itself. With no `(click)` there is nothing to disable and the
  row is inert already.
- **Pass `interactive` alongside `(click)`, or the row is inert.** The flag is what makes the card
  shape a `role="button"` tab stop with an Enter/Space handler. It exists because this layer cannot
  ask whether an output has subscribers -- `OutputEmitterRef.listeners` is private -- so the shape
  has to be declared rather than detected. Before it existed, a clickable card row here was
  reachable by pointer and not by keyboard.
- Wire `(click)` only when the whole row means something to activate. A row with one
  actionable thing in it wants an `arena-button` in a cell instead; see the keyboard note
  below.
- **A control inside a cell keeps its own activation.** A selection checkbox in the first
  column and a row action in the last are the canonical table, so an activation that starts on
  a link, a button, a field or anything carrying an interactive role does not reach the row:
  the checkbox ticks and the reader stays where they are, and the action fires once rather
  than twice. Only a press that lands on the row itself activates it.

### Why it is an attribute on a `<tr>` and not an element of its own

A `<tr>` is a row without being told so, and the shape that keeps that is the one where the element
you write IS the row. An `<arena-table-row>` wrapping a `<tr>` does not work, and the reason is worth
having before you reach for it: `display: contents` fixes the **box** tree, not the **DOM** tree, so
a `<tr>` that is not a DOM child of `<tbody>` never forms the native mapping at all -- and under
server rendering it is worse, because the markup is serialized and re-parsed and the HTML parser
foster-parents a non-table element straight out of the table.

### Why the pointer handler is not in the host block

An Angular output named after a native DOM event collides with a host listener for that event, and
the collision was measured here rather than guessed: with `'(click)'` in the `host` block, the
listener is wired to this component's own `click` **output**, so `emit()` re-enters the handler. The
listener is therefore added to the host element directly, in the constructor, which also puts it
**before** the one Angular adds for the consumer's own `(click)`. That order is what makes
`stopImmediatePropagation()` work: it is what stops a native click on a cell being delivered a second
time alongside the output, and what keeps a press that started on a control inside the row from
reaching the row at all. One is the only passing number and two is the defect, and the count is
asserted so it cannot drift back.

### Card mode is a button when the row says so, and presentational when it does not

Below `--bp-md` the row is still a `<tr>` -- one set of elements is authored and the width that
decides the shape changes at runtime, so the markup cannot change with it -- and CSS restyles it into
a card. `interactive` decides what that card is: with it, a `role="button"` tab stop with an Enter and
Space handler, which is the binding's `card-interactive` case; without it, `role="presentation"` and
no tab stop, which is `card-inert`. The presentation role is a removal rather than an affordance: it
takes back the row mapping the element carries natively, so nothing describes a stack of cards as a
table. The shape follows the member and never whether anything is listening, which no render may follow from and
which `OutputEmitterRef.listeners` could not answer here anyway. That is the whole reason
`interactive` is a member rather than an inference: making every card row a button would put a
dead tab stop on every row of every table that is not clickable, and deriving it from a bound
`(click)` would make the row's shape depend on a subscriber list the platform keeps private.
`arena-calendar-event` answers the same question the other way, which is the useful contrast: a
chip is `tabindex="-1"` and never a page tab stop, so always-a-button costs no dead stop there,
where always-a-div would delete Enter-into-the-chip.

### What is shared, and therefore not yours

Where the row sits, which columns its cells are set against, and where the grid's cursor is
all live on `ArenaTableState`, which the table provides and this component injects. None of it is
a member of `contracts/api/components/ArenaTableRow.json`, and a consumer never writes one, the
same shape as `arena-radio` pulling its group's state. Nothing is pushed down: the child asks.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-table/ArenaTable.prompt.md -->

Arena data table for dense surfaces: headers in mono/uppercase, rows separated by a
hairline. Standalone, `OnPush`, signal inputs.

It is a **compound** primitive: `columns` says how each column is headed and set, and you
write one `<tr arena-table-row>` per row with one `<td arena-table-cell>` per cell inside it.
Cells are **positional**: the nth cell takes the nth column.

```html
<arena-table [label]="'Recent deployments'" [columns]="columns">
  @for (d of deploys(); track d.build) {
    <tr arena-table-row interactive (click)="openDeploy(d)">
      <td arena-table-cell>{{ d.build }}</td>
      <td arena-table-cell>{{ d.project }}</td>
      <td arena-table-cell><arena-badge [tone]="d.tone" dot>{{ d.status }}</arena-badge></td>
    </tr>
  }
  <span empty>No deployments in this range.</span>
</arena-table>
```

<!-- @api GENERATED from contracts/api/components/ArenaTable.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the grid for assistive technology. Required, and guarded at runtime: nothing can derive it; ArenaCalendar names its grid from the range it is showing, and a data table's subject is editorial. Say what the rows are, never "ArenaTable". |
| `columns*` | array | `readonly ArenaTableColumn[]` |  | The columns, in order. A column heads and sets its cells; it never says what goes in them. |
| `content` | slot |  |  | The rows. One ArenaTableRow per row. Where a row sits, the columns its cells are set against and how the keyboard reaches them are ArenaTable's to decide and no row's to declare; how that reaches a row is each layer's own idiom. |
| `empty` | slot |  |  | What shows when no row is written. In that state NO grid is drawn at all, header row included: a column head over a "no results" sentence describes a table that is not there, and a role="grid" holding neither a header nor a row is a degenerate render, the same judgement ArenaTabs makes when it draws no panel for a tab that does not exist. Every layer falls back to the string 'No data.' when nothing is given, each in its own idiom for a default. Unlike ArenaTable.label this one IS derivable: 'No data.' states what happened rather than what the component is, which is the distinction that makes a fallback useful here and useless there. A consumer with a better sentence, what to do next or why the list is empty, projects it. |
| `sort` | object | `ArenaTableSort` |  | Which column the rows are ordered by and which way. Controlled: ArenaTable draws the caret and the aria-sort, and the consumer does the ordering, because ArenaTable does not hold the rows. Absent, no header is a sort target. |
| `sortChange` | event | `ArenaTableSort` |  | A sortable header was activated, carrying the column and the direction it should become: the same column flips, a different one starts ascending. ArenaTable never reorders anything itself, so a consumer who ignores this event gets a caret that moves and rows that do not, which is why the member is controlled rather than a starting value. |
| `page` | object | `ArenaTablePage` |  | Which page of a longer list is on screen. Present, ArenaTable draws its own ArenaPagination below the grid and names it from `label`, which is what gives that required name its uniqueness on a page with two paged tables. Absent, no pager is drawn and the projected rows are the whole list. |
| `slice` | object | `ArenaTableSlice` |  | Where the projected rows sit inside a longer list, which is what `aria-rowcount` and `aria-rowindex` carry on the grid. Absent with `page` bound, both are derived from the page, so a paged table needs nothing here. Bind it when the projection is not a page: a window a scroller renders, an infinite list that grows, or a page inside which you render less again. It is a separate member from `page` because the two answer separate questions, the same split `page` and `pageControl` make: `page` is the model the pager draws, and this is where the rows in the DOM sit in the list they came from. Bound together, this one answers the two attributes whole rather than composing with the page, because a reader is told one position and two sources for it is how they disagree. |
| `pageChange` | event | `number` |  | A page was chosen, carrying the new 1-based page. It also fires with 1 when the current page has gone PAST THE END, which is the only reset ArenaTable performs; a filter that leaves the page in range is silent, so returning the reader to page one on a change of criterion stays the consumer's, beside the criterion they hold. |
| `pageControl` | enum | `ArenaTablePageControl` | `"auto"` | Whether ArenaTable draws the pager below the grid. 'auto' draws it whenever `page` is bound, which is what a table showing one list of its own wants; 'none' draws nothing and leaves the consumer to place an ArenaPagination themselves, over this table or over two of them at once. It is a separate member from `page` because the two are separate facts: `page` is what the table KNOWS about a longer list, and this is what it DRAWS about it. Bound together, a consumer who wanted the control elsewhere had to withhold `page` and leave the table knowing nothing about paging at all, which is a member deliberately unbound and a comment explaining why. The same split, and the same reasoning, as `sort` and `sortControl`. |
| `sortControl` | enum | `ArenaTableSortControl` | `"auto"` | How the sort affordance is reached in CARD MODE, where there is no header row to activate and a `sortable` column therefore has no control under it at all. 'auto' draws one compact select above the cards, listing every sortable column in each direction, which is the shape a phone has room for; 'none' leaves card mode unsorted by hand, for a table whose order is the document's rather than the reader's. Above --bp-md the header row is the control and this member draws nothing. The header row does NOT come back below the breakpoint, because card mode exists for the one reason a grid does not fit. It is a member rather than something a consumer draws for themselves because the state it edits, ArenaTableSort, is Arena's: left to each consumer, the label, the option order and the way a direction is worded are invented once per project over a model they did not define. |
| `responsive` | primitive | `boolean` | `true` | ArenaCard mode below --bp-md. Set false only when the columns are meaningless apart. |

<!-- @api end -->

**Do / Don't**
- **A grid showing part of a list owes its true size.** `page` pays that on its own; bind `slice` when the rows in the DOM are a window rather than a page, and count `offset` from 0. A windowed grid that states neither tells a reader the list is as long as the rows it happens to have rendered.
- **`page` is what the table knows and `pageControl` is what it draws.** Bind `[page]` whenever
  the list is longer than the screen, so the table sizes and resets it; pass
  `pageControl="none"` when you want the `arena-pagination` somewhere else, or want one
  control over two tables. Withholding `[page]` to move the control is the shape this member
  exists to replace: it left the table knowing nothing about paging at all.
- `label` is required and names the grid for a screen reader. Say what the rows *are*, as
  in "Recent deployments" or "Team members", and never "Table". Nothing can derive it, which is why
  it **throws** rather than falling back, and why `input.required` alone is not the guard:
  that only proves something was bound, and `[label]="row.title"` with an empty title
  satisfies it.
- Put your own components in a cell: an `arena-badge` for a status, an `arena-button` for
  an action. That is what the compound shape is for; a column carries no render function.
- Numeric data and codes in `mono` columns with `align: 'right'`. `mono` is the mono face and the gold ink together, and the ink is the half that does not travel: gold reads as an identifier, so a total in gold inside a card says the wrong thing. For a figure you draw outside a table, put `.arena-num` on it, which is the same face and the same digit alignment with no colour.
- Mark the actions column `mobileLayout: 'block'`. Its buttons name themselves, and pairing
  them with an "ACTIONS" label reads as a mistake.
- Don't set `responsive="false"` to "keep it looking like a table" on a phone. A table
  narrower than its content is unreadable; card mode is the honest fallback.
- Row activation is `(click)` on the row, and it carries no payload, because you wrote that
  element inside your own `@for`, so you already hold the row it is about.

### Responsive

Below `--bp-md` the table renders one card per row. The threshold is measured on the
table's **container**, never the viewport and never a media query, so a table inside a narrow
panel goes card-mode on a wide monitor, which is what you want. Before anything has been
measured the wide shape renders, so the card shape never flashes on first paint.

### Keyboard

The wide shape is a `role="grid"` with **one** tab stop. Tab reaches the grid, arrows move
by cell (the header row is row 0 and is navigable, as APG prescribes), `Home` and `End` go
to the first and last cell of the **current row**, and `Enter` activates the cursor's row by
emitting that row's `click`. There is no step-in: a control you drew inside a cell keeps its
own place in the page Tab sequence, so nothing you own is silenced.

The grid is **not assumed rectangular**. A row may carry fewer or more cells than there are
columns, and the cursor is clamped against the row it is actually in.

Card mode answers none of this, and it does not have to: a card is a list item, and a list is
traversed with Tab. A card row carrying `interactive` is a `role="button"` tab stop of its own
with an Enter and Space handler, which is `ArenaTableRow`'s `card-interactive` case rather than a
clause of this component's binding. A card row without it is inert, because a dead tab stop on
every row of every table is worse than the gap it would close. The shape follows the member and
never whether anything is listening, which is why `interactive` exists at all.

### Why there is always a real `<table>`, at both widths

The rows are **authored** by the consumer, as `<tr arena-table-row>`, and the width that decides the
shape is measured at runtime. So the elements cannot change with the shape: a `<tr>` that is not a
DOM child of a table is dropped outright by the HTML parser, which is what a server render and its
re-parse put it through. A shape that appears and disappears under the rows is therefore not
available here, and the single shape that survives both widths is a real `<table>` always, restyled
by CSS into cards below `--bp-md`.

That also settles a second constraint that used to point the other way: Angular indexes projection
slots in template order and hands the content to the **first** matching one, so a `wide` branch and a
`card` branch could not each carry their own `<ng-content>`. With one table there is one `<tbody>`
and one `<ng-content>`, and nothing to choose between.

`role="grid"` is still written, because APG's grid is not the `table` a `<table>` maps to and the
roving tab stop is the difference. Nothing under it is: a `<tr>` is a row, a `<th scope="col">` is a
columnheader and a `<td>` inside the grid is a gridcell, so none of the three is written back onto
the element that already means it. Below `--bp-md` the whole table declares `role="presentation"` and
drops its `aria-label`, which is what takes those mappings back off it -- a name would make the
element ineligible for the role and bring the table back in the reader's ear while the screen shows a
stack of cards.

The empty state is still a block **beside** the table rather than a cell spanning it, and the table
left behind is presentational. One measured cost stands: the `<table>` sits inside the bordered
frame, so the measured `contentRect` excludes that border and the narrow threshold trips a couple of
pixels earlier than the declared breakpoint. The host itself is a plain block.

**By hand, in a real browser** (`bun run build:angular-demo && bun run demos`, then
`frameworks/angular/components/display/arena-table/ArenaTable.demo.generated.html`). Steps 1–5 were checked in real
Chromium: one Tab in, the gold inset ring on the focused cell, the arrow walk,
`Home`/`End` inside the row, `Enter` on a data row, one Tab out onto the actions button, and
zero grid roles and zero tab stops in the squeezed card shape. Step 6 and every judgement about how
it *looks* were not, and are why this list stays:
1. Tab reaches the grid ONCE, and one more Tab leaves it. No cell is a stop of its own.
2. From a cell, Tab reaches a control inside a cell in **one** press, not two. Two means the
   grid pulled focus back onto the cell, since `focusin` bubbles and only a real browser shows it.
3. Arrows clamp at all four edges and focus never leaves the grid. `Home`/`End` stay inside
   the current row. Walk a middle row, not only the first.
4. `Enter` activates a row with `(click)` and does nothing on the header row or on the
   disabled row; the page logs what was activated.
5. The squeezed container is already in card mode on load. Confirm nothing there took a
   role, a tabindex or a key handler by accident.
6. The measured width does not oscillate between the two shapes. Narrow the window slowly
   across the threshold and watch it settle rather than flicker.

### Sorting and paging

Both are **controlled**, and for the same reason: `arena-table` does not hold the rows, so it
cannot order them and cannot cut them. It draws the affordance and tells you what was asked.

```html
<arena-table label="Recent deployments" [columns]="columns"
             [sort]="sort()" (sortChange)="sort.set($event)"
             [page]="page()" (pageChange)="goTo($event)">
```

Mark a column `sortable: true` and pass `sort`. Without `sort` no header is a target however
many columns declare it, because a control drawing a direction it does not know is worse than
no control. Activating the sorted column flips it; activating a different one starts it
ascending. It costs **no tab stop**: the header row is already row 0 of the grid's roving
cursor, so Enter and Space act on the cell the reader is already on, and `aria-sort` says which
column and which way.

**Below `--bp-md` the header row is gone, so `sortControl` is the affordance.** With `sort`
bound and at least one `sortable` column, card mode draws one compact select above the cards,
listing every sortable column in each direction, and it reports through the same `sortChange`
the header does. Set it to `none` for a table whose order is the document's rather than the
reader's. The header row does **not** come back below the breakpoint: card mode exists for the
one reason a grid does not fit.

### A grid that shows part of a list says how big the list is

`aria-rowcount` and `aria-rowindex` are what a reader moving through a grid is counted by, and the
grid pattern's source page applies them whenever rows are not in the DOM. Binding `page` is enough:
the count and each row's position are derived from it, so a paged table already reports row 41 of
500 rather than row 1 of 20.

Bind `slice` when the projection is not a page, which is what a scroller renders:

```html
<arena-table label="Recent deployments" [columns]="columns"
             [slice]="{ total: 20000, offset: firstVisible() }">
  @for (row of visible(); track row.id) { <tr arena-table-row>...</tr> }
</arena-table>
```

`offset` counts from 0 and is the number of rows before the first one you projected; the header row
takes index 1 and `arena-table` does that arithmetic, so an offset that already counted from 1 tells
the reader they are one row further on than they are. `total: -1` is the answer for a list whose
length nobody knows yet, and it reaches the attribute unchanged. Bound beside `page`, `slice` is
what answers, because one position with two sources is a position two things can disagree about.

### `ArenaTableSort.column` is an index, and a column that moves takes the order with it

The cells are already positional, so a key would be a second identity for a thing that has one,
and that is the right trade. The price is that moving a column silently reorders the rows,
because the index now names a different column. **Keep the sort field inside the column entry it
belongs to and the two move together:**

```ts
const COLUMNS = [
  { header: 'Customer', sortable: true, field: (s: Sale) => s.customer },
  { header: 'Status' },
  { header: 'Total', sortable: true, field: (s: Sale) => s.total },
];
```

Arena cannot check that, but it does catch the loudest way to get it wrong: a `sort.column`
aimed at a column that declares no `sortable` **warns once**, naming the column it landed on,
instead of drawing no caret and saying nothing.

`page` is `{ index, size, total }`. `total` is the count across every page and is required,
because the rows you project are one page and nothing about the whole list can be read from
them. ArenaTable draws its own `arena-pagination` below the grid and names it from `label`, which is
what makes two paged tables on one dashboard tellable apart.

The one thing ArenaTable emits on its own is `pageChange` with 1, when the total drops far enough
that the current page is **past the end**. It is bounded: a filter that leaves the page valid is
silent, so nothing loops.

**That is not the reset you write beside a filter, and expecting it to be is the mistake this
paragraph exists to stop.** Filter ten pages down to five while the reader is on the third and
the page is still in range, so ArenaTable says nothing and the reader is left on page three of
results they never asked for. ArenaTable cannot tell that from removing one row from page three of
ten, which must move nobody, because a count is all it has. **Whether a change of criterion
returns the reader to page one is yours**, and it belongs beside the criterion:

```ts
setStatus(next: string): void {
  this.status.set(next);
  this.pageIndex.set(1);   // your own signal; `page` is the whole {index, size, total}
}
```

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-tag/ArenaTag.prompt.md -->

Arena status/emphasis tag, a chip whose `tone` follows the ArenaBadge/ArenaTag taxonomy.
Standalone, `OnPush`, signal I/O. `removable` shows an
Arena-drawn dismiss `×` that emits `remove` on click.

`colorId` is the other colour a tag can take, and it answers a different question: `tone` says
what state a thing is in, `colorId` says which thing it is. A database label, a workflow status
and a project name are identities, so they take a ramp slot and keep it everywhere.

```html
<arena-tag>Neutral</arena-tag>
<arena-tag tone="primary">Active</arena-tag>
<arena-tag tone="danger">Blocked</arena-tag>
<arena-tag [colorId]="3">Backend</arena-tag>
<arena-tag removable (remove)="drop('staging')">Staging</arena-tag>
```

<!-- @api GENERATED from contracts/api/components/ArenaTag.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The tag's label. |
| `tone` | enum | `ArenaTagTone` | `"neutral"` | The tag's emphasis colour. Ignored while `colorId` names a ramp slot, because a tag draws one colour and the two mean different things. |
| `colorId` | enum | `ArenaCatSlot` |  | An identity colour from the categorical ramp, the ramp the charts and the calendar read, so one entity keeps its colour across a chart, a schedule and a label. Colour here means which thing and never what state, which is why it replaces `tone` rather than joining it: a label reading "Backend" is not a warning, and a tag that could say both at once would say neither. Optional, and its absence is the tone tag. The slot's colour also reaches the tag as a custom property, `--arena-tag-cat`, so an appearance that fills the marker rather than outlining it is a style plugin's to write and needs no member here. |
| `removable` | primitive | `boolean` | `false` | Whether the dismiss × is shown. Every layer gates the × on this member and never on whether anything listens for `remove`, because Arena never derives what it draws from what a consumer listens for. Removability is a declared input, not something inferred from the event. |
| `disabled` | primitive | `boolean` | `false` | Whether removal is unavailable while the tag stays visible: a filter a consumer's permissions lock, not a tag that is merely inert. It reflects through `aria-disabled` rather than the native `disabled` attribute, so the × keeps its place in the tab order and a screen-reader user is told the action is unavailable instead of never finding it. With `removable` false there is no × and nothing to disable. |
| `remove` | event |  |  | The dismiss × was activated. Never emitted while `disabled`. |

<!-- @api end -->

**Do / Don't**
- Use `tone="danger"` for a blocked/destructive status: the chip's border and
  text render in `--error`, never a fill. That is the danger convention; the
  only filled danger surface in Arena is `ArenaConfirmDialog`'s final confirmation.
- The leading dot is filled (`bg-current`, coloured by `tone`) even for
  `tone="danger"`, though the chip itself is outline, a tone dot is an
  identity mark, the same family as `ArenaActivityFeed`'s own dot and `ArenaAvatar`'s
  presence dot, not a danger surface. convention section.
- Use `removable` only when removing the tag is a real user action (applied
  filters), not on informational tags, and handle `(remove)`, or the × has
  nothing wired to it.
- Reach for `disabled` when removal is temporarily unavailable and the tag must
  stay on screen, a filter the user's permissions lock. The × keeps its place
  in the Tab sequence and announces itself as unavailable, which is why this is
  `aria-disabled` and not the native `disabled` attribute, and `remove` is never
  emitted while it is set. Without `removable` there is no × and it does nothing.
- Don't use `disabled` to mean "this tag is greyed out". A tag with no `×` is
  already inert; the state is about the remove action alone.
- Don't use a tag as a button. It is a status/emphasis label; an action belongs
  on an `arena-button`, not on the chip itself, the dismiss `×` is the one
  exception, and it is a real `<button>` gated on `removable`.
- Don't add a `tone` outside the taxonomy: the five tones are the whole set.
- Reach for `colorId` when the colour identifies rather than warns, and give the same entity the
  same slot on every screen: the ramp is the one the charts and `arena-calendar-event` read, so a
  label, a series and a schedule chip agree. Derive the slot from a stable key with
  `arenaCatSlotFor` rather than from the position of a row, which moves when the list is sorted.
- Bind it, `[colorId]="3"`, rather than writing `colorId="3"`: the input takes a number and an
  unbound attribute hands it the string.
- Don't pass `tone` and `colorId` together expecting both: `colorId` wins, and a chip that
  carried a state colour and an identity colour at once would read as neither.
- The identity chip outlines, like every other tone. A filled one is an appearance decision: the
  ramp colour reaches the host as `--arena-tag-cat`, so a style plugin fills `tag` with it and no
  member is needed here.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/display/arena-unauth-card/ArenaUnauthCard.prompt.md -->

Arena's signed-out panel. A frame: the lock-up, an eyebrow, a title, whatever the screen
is actually for, and a footer. It knows nothing about credentials, so one component
serves sign-in, "check your inbox", "this link expired" and two-factor entry.

```html
<div style="display:flex;min-height:100vh;align-items:center;justify-content:center">
  <arena-unauth-card eyebrow="Delivery Console" title="Sign in">
    <arena-app-logo brand name="Draven" dim="soft" size="md">
      <img src="/assets/your-mark.svg" alt="" />
    </arena-app-logo>

    <arena-input label="Email" type="email" [value]="email()" (change)="email.set($event)" />
    <arena-button type="submit" full>Sign in</arena-button>

    <span footer>Trouble signing in? Contact your administrator.</span>
  </arena-unauth-card>
</div>
```

<!-- @api GENERATED from contracts/api/components/ArenaUnauthCard.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `brand` | slot |  |  | The brand lock-up above the panel's content. An ArenaAppLogo, in practice. |
| `eyebrow` | primitive | `string` |  | Mono crimson microlabel: the product, not the task. |
| `title` | primitive | `string` |  | The task. "Welcome back", "Check your inbox". |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h2"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h2` because this title is drawn in the section register rather than the card one, so the outline follows the register the same way every other title on the ladder does. A signed-out screen whose only title is this one says `h1` and gets the page's one heading, which is the case the member exists for. `none` takes the title out of the outline entirely; with no title there is no heading either way. |
| `content` | slot |  |  | The fields, composed from ArenaInput and ArenaButton. |
| `footer` | slot |  |  | Centred muted line below the content: a recovery link, a legal note. |

<!-- @api end -->

Import `ArenaBrand` and `ArenaFooter` from `@dravensoft/arena-angular` alongside
`ArenaUnauthCard` in the host component's `imports`,
`brand` and `footer` are directives, not plain attributes, because they are how the panel
detects that something was actually projected into each slot. Both wrappers carry their
own margin, so a card that omits one ships no dead space for it.

**Do / Don't**
- Centre it yourself. The three-line wrapper above is the whole job, and keeping it out
  of the component is what lets the panel sit in a split layout or inside a dialog.
- Don't put auth logic here. Submit handlers, validation and provider buttons belong to
  the screen; this is the frame around them.
- Don't override the width. 454px is the figure this panel has always rendered at, and it
  is arithmetic, content, padding and both hairlines added back together.
- Don't forget to import `ArenaBrand` / `ArenaFooter` when projecting into `[brand]` /
  `[footer]`, without them, the attribute is inert and the content silently fails to
  render inside its wrapper.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-alert/ArenaAlert.prompt.md -->

Arena in-page message. Unlike a snackbar it is persistent: it belongs where the
condition it reports lives, and it stays until that condition is resolved. `tone`
carries the severity and picks the Phosphor Fill icon; `actionLabel` adds one
uppercase mono action; `dismissible` adds the single `ph-x` close control.

```html
<arena-alert tone="warning" title="Deploy window closes in 20 minutes">
  Merge or park the release before 18:00 UTC.
</arena-alert>

<arena-alert tone="danger" title="Sync failed" actionLabel="Retry" [dismissible]="true"
             (action)="retry()" (close)="hide()">
  Three records could not be written.
</arena-alert>
```

<!-- @api GENERATED from contracts/api/components/ArenaAlert.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `tone` | enum | `ArenaAlertTone` | `"info"` | The severity: colour, default icon, and (for danger) the alert role. |
| `title` | primitive | `string` |  | An optional bold lead line above the message. |
| `content` | slot |  |  | The message body. |
| `icon` | primitive | `string` |  | A Phosphor class name overriding the tone's default glyph. Arena draws it. |
| `actionLabel` | primitive | `string` |  | The label of a single inline action button. Absent renders no action. |
| `action` | event |  |  | The inline action button was activated. |
| `dismissible` | primitive | `boolean` | `false` | Whether the × is shown. Every layer gates the × on this member and never on whether anything listens for `close`, because Arena never derives what it draws from what a consumer listens for. |
| `close` | event |  |  | The × was activated. |

<!-- @api end -->

**Do / Don't**
- Use `tone="danger"` only for a condition the user must act on. It renders
  `role="alert"`, which interrupts a screen reader; every other tone renders
  `role="status"`, which does not.
- Don't use an alert for something transient: that is `MatSnackBar` wearing Arena.
- Don't stack more than one alert in the same region. Two competing alerts read as
  one broken page; summarise instead.
- Don't express a condition as an attribute string. `dismissible` carries the
  `booleanAttribute` transform, so a bare `dismissible` and `[dismissible]="true"` both
  mean true, and the one literal string `"false"` means false. Every *other* string is
  true, `"0"`, `"off"` and `"no"` all suppress nothing. Bind the expression
  (`[dismissible]="canDismiss"`) and keep the bare attribute for a constant true.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-confirm-dialog/ArenaConfirmDialog.prompt.md -->

Arena confirmation for a high-consequence action. It does not close on click-outside,
losing a half-finished decision to a stray click is the failure this component exists
to prevent. `requireText` makes the user type a word before the confirm button
enables. `destructive` turns the eyebrow red and gives the confirm button Arena's
**only filled danger surface**.

```html
<arena-confirm-dialog [open]="confirming()" [destructive]="true"
                      [title]="'Delete project Ardennes?'"
                      eyebrow="Irreversible" confirmLabel="Delete project"
                      requireText="Ardennes"
                      (cancel)="confirming.set(false)" (confirm)="destroy()">
  Every deployment, log and artifact under this project is removed. This cannot be
  undone.
</arena-confirm-dialog>
```

<!-- @api GENERATED from contracts/api/components/ArenaConfirmDialog.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `open*` | primitive | `boolean` |  | Whether the dialog is shown. The host owns it, as in the other three modals: defaulting it would let an ArenaConfirmDialog whose open was never wired render nothing forever and look like a working closed dialog. |
| `title*` | primitive | `string` |  | The dialog heading, and the name the panel's aria-labelledby points at. Required: nothing can derive a name for a confirmation, because its subject is editorial, and a modal announcing only its role is worse than none at all. Required whatever open is, since a required member absent is a caller bug rather than a state to render: render the component when there is something to confirm, and hold on to the subject across a cancel so it still has a name while it closes. |
| `eyebrow` | primitive | `string` | `"Confirm"` | Small uppercase label above the title. |
| `content` | slot |  |  | The dialog body: the question and any detail. |
| `confirmLabel` | primitive | `string` | `"Confirm"` | The confirm button's label. |
| `cancelLabel` | primitive | `string` | `"Cancel"` | The cancel button's label. |
| `destructive` | primitive | `boolean` | `false` | Gives the confirm button Arena's only filled danger surface. |
| `requireText` | primitive | `string` |  | Locks the confirm button until this exact word is typed. |
| `cancel` | event |  |  | The dialog was dismissed -- by the Cancel action or by the Escape key, in both layers. A scrim click is deliberately NOT one of them: this component never closes on click-outside. No payload. |
| `confirm` | event |  |  | The action was confirmed. |

<!-- @api end -->

`title` is **required**: the panel's `aria-labelledby` points at it, and nothing can
derive a name for a confirmation because its subject is editorial. Escape dismisses
through `(cancel)`, focus moves into the panel on open and returns to the invoker on
close, and Tab wraps at the panel's edges.

**Do / Don't**
- Say what will be destroyed, in the body, in plain words. "Are you sure?" is not a
  confirmation, it is a speed bump.
- **Bind `title`, never write it as a static attribute.** `title="Delete project X"`
  compiles and does set the input, and it also lands on the host as the native HTML
  `title` attribute. The host here is the fixed full-viewport scrim, and a native
  `title` on it would be a tooltip target the size of the page, which is why this host
  clears the attribute (`'[attr.title]': 'null'`). The layer holds that rule in both
  directions: a primitive taking the input and not clearing it fails, and so does one
  clearing an attribute it takes no input for. `[title]="'Delete project X'"` or
  `[title]="projectName()"` sets the input alone, and it is the spelling that says so.
- Use `requireText` when the action is genuinely irreversible, and use the name of the
  thing being destroyed as the word.
- **Don't hold one in the template with an empty `title` while it is closed.** Both are
  required inputs whatever the other is, so a screen that keeps one confirmation and feeds it a
  subject per row fails on the first render: put it behind an `@if` on the subject instead. Keep
  the subject through a cancel and toggle only `open`, or focus never returns to the control
  that opened it.
- Don't reach for `destructive` on a merely inconvenient action. The filled red is the
  system's loudest surface and it stops working once it is common.
- Don't use this for a routine question: that is `MatDialog` wearing Arena.
- Don't express a condition as an attribute string. `destructive` carries the
  `booleanAttribute` transform, so a bare `destructive` and `[destructive]="true"` both
  mean true, and the one literal string `"false"` means false. Every *other* string is
  true, `"0"`, `"off"` and `"no"` all give you the destructive button. Whether an
  action is irreversible is a computed fact, so bind it:
  `[destructive]="isIrreversible"`. Keep the bare attribute for a constant true.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-dialog/ArenaDialog.prompt.md -->

Arena dialog, the routine modal, over a blurred scrim. Standalone, `OnPush`, signal I/O.
The host **is** the scrim, so `<arena-dialog>` covers the viewport when open and takes the
`hidden` branch of its own `open` variant when closed, put it anywhere in the template.

```html
<arena-dialog [open]="dialogOpen()" title="Promote build 482 to production?" eyebrow="Deployment"
              (close)="dialogOpen.set(false)">
  The current production build stays available for rollback for seven days.
  <div footer>
    <arena-button variant="ghost" (click)="dialogOpen.set(false)">Cancel</arena-button>
    <arena-button (click)="promote()">Promote</arena-button>
  </div>
</arena-dialog>
```

<!-- @api GENERATED from contracts/api/components/ArenaDialog.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `open*` | primitive | `boolean` |  | Whether the dialog is shown. The host owns it. |
| `title*` | primitive | `string` |  | Names the dialog for assistive technology and heads it visually. Required: aria-labelledby points at it, and a modal with no name is worse than none at all. |
| `eyebrow` | primitive | `string` |  | A short kicker above the title. |
| `width` | primitive | `string` | `"calc(var(--sp-1) * 120)"` | A CSS width for the panel. It defaults to 480px, which each layer reaches in its own idiom, and the input overrides whichever. |
| `content` | slot |  |  | The dialog's body. |
| `footer` | slot |  |  | The action row, right-aligned. |
| `close` | event |  |  | The dialog was dismissed -- by Escape or by a scrim click. No payload. |

<!-- @api end -->

`title` and `open` are both **required inputs**. `title` names the dialog for assistive
technology, the panel's `aria-labelledby` points at it, and nothing can derive it, because a
dialog's subject is editorial. `open` is required because `false` is the closed state and not an
absence; the host owns it.

`width` is a **CSS string** and an override, not a requirement: the panel already carries its own
default and a `92vw` cap, so a wide dialog still fits a narrow viewport. Pass a token expression
(`width="calc(var(--sp-1) * 200)"`), never a bare number. A named size is not one of the things it takes: `width="md"` compiles, sets a declaration the browser drops, and leaves the panel at its default, so Arena reports that once at runtime rather than letting it pass in silence.

The footer is projected through the `[footer]` marker and is **optional**, with nothing marked,
the action row is not rendered at all rather than rendered empty. **Import `ArenaFooter` from
`@dravensoft/arena-angular` in the component that writes the marker.** The gate is a
`contentChild(ArenaFooter)`, which resolves the directive rather than the attribute, so an
un-imported marker leaves the query null and the whole footer silently unrendered, no error, no
template diagnostic, since a bare `footer` attribute on a `<div>` is valid HTML whether or not a
directive matches it. The component cannot detect it, because it cannot tell "the marker was not
imported" from "nothing was projected". Arena catches every such consumer inside its own tree;
nothing can reach one in yours.

Focus is Arena's own, and it implements
`contracts/behaviour/dialog-modal.json` clause by clause. Opening moves focus to the first
focusable element inside the panel; closing returns it to whatever held focus before. Tab and
Shift+Tab wrap at the panel's edges, and that wrap is verified against a real browser rather
than asserted. The CDK is **not** involved: this dialog is in flow, on `--z-modal`.

Arena dismisses two ways and both report through `close`: **Escape**, and a click on the scrim.
A click inside the panel is stopped before it reaches the host, so only the scrim dismisses. A
third path is yours, a button in `[footer]` wired to the same handler, and it adds no member.

**Do / Don't**
- **Do** give every dialog a `title` that says what it is about, not what it is ("Delete
  project", never "Dialog").
- **Do** keep the dismissing control in `[footer]`. Escape is a shortcut for it, never the only
  way out.
- **Don't** open a second modal inside a dialog by nesting one. `arena-confirm-dialog` sits on
  `--z-modal-nested` for exactly this and is the one that belongs on top; two traps nested inside
  one panel fight over the same Tab key.
- **Don't** put `tabindex="-1"` on content the user has to reach. It is how the trap decides what
  is focusable, so a control held out of the Tab order is one the wrap skips.

**By hand, in real Chromium**: the trap's **interior** is the browser's own sequential focus
navigation, which Arena does not implement and happy-dom does not have, so a suite asserting it
would pass identically against a perfect trap and against none. The boundary wrap is Arena's own
`.focus()` call and is asserted for real; the rest is this list. Run `bun run demos` and open
`/frameworks/angular/components/feedback/arena-dialog/ArenaDialog.demo.generated.html`:

1. **Tab to "Promote build" and press Enter.** Focus lands on **Cancel**, the first focusable
   inside the panel, not on the trigger.
2. **Tab once.** Focus moves to **Promote**. This is the step no suite can make: Cancel is first
   and not last, so Arena's handler does nothing and the browser moves focus on its own. If this
   fails, the trap is fighting native navigation rather than bounding it.
3. **Tab again.** Focus wraps from Promote back to Cancel. This one is Arena's.
4. **Shift+Tab.** Focus wraps from Cancel back to Promote.
5. **Escape**, then a click on the scrim, then a click inside the panel. The first two close and
   return focus to "Promote build"; the third does nothing.
6. The scrim blurs what is behind it, and the panel enters with `arena-pop`, which drops its
   travel and keeps its fade under `prefers-reduced-motion`.

Driving it through CDP costs an afternoon on one gotcha: a `rawKeyDown` does not activate a
button. Enter must be dispatched as `keyDown` carrying `text: '\r'`. Tab and Escape are fine as
`rawKeyDown`.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-empty-state/ArenaEmptyState.prompt.md -->

Arena empty state, a section or screen with nothing in it yet, and one clear way
forward. The action is projected, so the empty state places a control the consumer wrote
rather than carrying a second button implementation. The dashed border is what distinguishes it from
`arena-error-state`: nothing is wrong here, there is simply nothing yet. The action
wrapper only renders when an action is actually projected, an empty state with no
action ships no dead space for one.

`title` is required (`input.required<string>()`, per `contracts/api/components/ArenaEmptyState.json`),
say what is empty. `icon` is optional and, like `arena-stat-card`'s, a Phosphor class name
Arena draws itself, not projected content.

```html
<arena-empty-state icon="ph-bold ph-folder-open"
                   title="No projects yet"
                   message="A project groups deployments, logs and artifacts for one client.">
  <arena-button action (click)="create()">Create a project</arena-button>
</arena-empty-state>
```

<!-- @api GENERATED from contracts/api/components/ArenaEmptyState.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `icon` | primitive | `string` |  | A Phosphor class name for the glyph Arena draws, muted. |
| `title*` | primitive | `string` |  | The headline: what is empty. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h3"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h3`, the card rung of the title ladder, because an empty state fills the body of a region something above it already names, so its headline sits under that name rather than beside it. `none` is refused at runtime, the rule every component whose `title` is required follows: a title required because it names the thing it draws cannot also be told that the name is not one. |
| `message` | primitive | `string` |  | A sentence of guidance under the title. |
| `action` | slot |  |  | A single call-to-action control, centred under the message. |

<!-- @api end -->

Import `ArenaAction` from `@dravensoft/arena-angular` alongside `ArenaEmptyState` in the
host component's `imports`,
`action` is a directive, not a plain attribute, because it is how the empty
state detects that an action was projected at all. `ArenaAction` is shared: every
primitive that projects a single action through `[action]` (`ArenaEmptyState`,
`ArenaErrorState`) imports the same directive rather than declaring its own.

**Do / Don't**
- Say what the thing *is* in the message, not just that there are none of it. An empty
  state is often the first time someone reads a definition.
- Give exactly one action. Two competing actions in an empty state is a decision the
  user has no information to make.
- Don't use an empty state for a failed load: that is `arena-error-state`, and the
  difference matters: one invites, the other apologises and offers a retry.
- Don't forget to import `ArenaAction` when projecting an action. Without it, the
  `action` attribute is inert and the action silently fails to render.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-error-state/ArenaErrorState.prompt.md -->

Arena failure state, something did not load, and there is a way to try again. Under
the API contract (`contracts/api/components/ArenaErrorState.json`) Arena draws the primary retry
itself, from `retryLabel`/`retry`, the same drawn-from-data shape `ArenaAlert`'s
`actionLabel`/`action` uses, rather than leaving it to a consumer to project. The
`[secondaryAction]` slot stays projected, for whatever a consumer wants beside the
retry (a link to logs, say). The solid `--error` fill is what distinguishes it from
`arena-empty-state`'s dashed neutral border: one apologises and offers a retry, the
other simply has nothing yet. `code` renders the support code as a mono chip: it is
for a support conversation, not for the user to act on, which is why it is muted and
small. The actions wrapper only renders when a retry or a secondary action actually
exists, a bare error state ships no dead space for a retry it does not offer.

```html
<arena-error-state icon="ph-bold ph-plugs"
                   title="Couldn't reach the delivery API"
                   message="The dashboard is showing the last data it cached."
                   code="ERR_UPSTREAM_504"
                   [retryLabel]="'Retry'"
                   (retry)="retry()">
  <a secondaryAction href="/logs">View logs</a>
</arena-error-state>
```

<!-- @api GENERATED from contracts/api/components/ArenaErrorState.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `icon` | primitive | `string` |  | A Phosphor class name for the danger glyph Arena draws. |
| `title` | primitive | `string` | `"Something went wrong"` | The headline: what failed. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h3"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h3`, the card rung of the title ladder, for the reason an empty state does: a failure fills the body of a region something above it already names. `none` takes the headline out of the outline, which is what a failure inside a small surface wants, and it is available here because `title` carries a default rather than being required. |
| `message` | primitive | `string` |  | A sentence of detail under the title. |
| `code` | primitive | `string` |  | A diagnostic/support code, shown monospaced. |
| `retryLabel` | primitive | `string` |  | The label of the retry button Arena draws. Absent renders no retry. |
| `retry` | event |  |  | The retry button was activated. |
| `secondaryAction` | slot |  |  | An extra control beside the retry (e.g. a link to logs). |

<!-- @api end -->

Import `ArenaSecondaryAction` from `@dravensoft/arena-angular` alongside `ArenaErrorState`
in the host component's `imports`,
`secondaryAction` is a directive, not a plain attribute, because it is how the error
state detects that a secondary action was projected at all.

**Do / Don't**
- Always pass `retryLabel` when a retry could work. An error state with no retry is a
  dead end the user has to navigate out of.
- Say what still works, if anything does: "showing the last cached data" is more
  useful than "an error occurred".
- Don't put the raw exception in `message`. The code chip is where a machine-readable
  detail goes; the message is for a person.
- Don't use this for a validation failure on a field: that belongs on the field.
- Don't forget to import `ArenaSecondaryAction` when projecting a secondary action,
  without it, the `secondaryAction` attribute is inert and the content silently fails
  to render.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-onboarding/ArenaOnboarding.prompt.md -->

Arena guided tour. A coachmark with progress dots, Skip and Next, floating bottom-right
over an unblurred scrim, a tour that blurs the product it is touring defeats itself.
It is controlled: the host owns `index` and answers `next`, `back`, `skip` and `done`.
Clicking the scrim reports `skip`. It is a real modal, binding `dialog-modal`:
focus moves into the panel when the tour opens and returns to whatever opened it when the
tour closes, Tab and Shift+Tab cycle inside the panel, and Escape reports `skip`.

```html
<arena-onboarding [open]="touring()" [steps]="steps" [index]="step()"
                  [anchor]="target()?.getBoundingClientRect()"
                  (next)="step.set(step() + 1)" (back)="step.set(step() - 1)"
                  (skip)="touring.set(false)" (done)="finish()" />
```

<!-- @api GENERATED from contracts/api/components/ArenaOnboarding.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `open*` | primitive | `boolean` |  | Whether the tour is shown. Closed renders nothing, scrim included. |
| `steps*` | array | `readonly ArenaOnboardingStep[]` |  | The tour, in order. An empty tour renders nothing. |
| `index` | primitive | `number` | `0` | Which step is current. The host owns it and answers next/back. |
| `anchor` | object | `ArenaOnboardingAnchor` |  | Where to attach the coachmark, as the two viewport coordinates it positions from. Absent floats it bottom-right. |
| `next` | event |  |  | Next was activated on a step that is not the last. |
| `back` | event |  |  | Back was activated on a step that is not the first. |
| `skip` | event |  |  | Skip was activated, or the scrim was clicked. |
| `done` | event |  |  | The final step's confirming control was activated. |

<!-- @api end -->

**Do / Don't**
- Keep a tour to three or four steps. The dots are a promise about how long this will
  take, and a tour that breaks that promise gets skipped.
- Pass `anchor` (an `ArenaOnboardingAnchor`, `{ left, bottom }`; a `getBoundingClientRect()`
  result satisfies it directly) when a step must point at a specific control; the
  coachmark clamps itself inside the viewport. Without it, it floats bottom-right.
- Handle `skip` as a real dismissal: Escape reports it too, on every step including the
  last one, where the Skip button itself is not rendered. Escape is how a user leaves,
  not how they finish, so it never reports `done`.
- Don't put anything in a tour that the interface should have made obvious. A
  coachmark explaining a confusing control is a bug report with a nicer border.
- Don't express a condition as an attribute string. `open` carries the
  `booleanAttribute` transform, so a bare `open` and `[open]="true"` both
  mean true, and the one literal string `"false"` means false. Every *other* string is
  true, `"0"`, `"off"` and `"no"` all leave the tour open. Bind the expression
  (`[open]="touring()"`) rather than relying on the literal.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-progress-bar/ArenaProgressBar.prompt.md -->

Arena progress bar, determinate by default, indeterminate for a wait with no percentage.
Standalone, `OnPush`, signal I/O. The host is the column the meter sits in: as a bar, an
optional head row carrying the label and the percentage with the track below it; as a ring,
the ring with the figure inside it and the label under that. The host shrinks to the ring
rather than filling the row, which is the one layout difference between the two shapes.

```html
<arena-progress-bar [progressPercentage]="uploaded()" label="Uploading build 482" />
<arena-progress-bar indeterminate label="Waiting for the build agent" tone="gold" />
<arena-progress-bar shape="radial" size="lg" [progressPercentage]="done()" label="Sprint 32" />

<arena-progress-bar shape="radial" size="lg" [showPercentage]="false"
                    [progressPercentage]="lesson()" label="Unit 3, lesson 4">
  <arena-icon-button icon="ph-fill ph-star" label="Start lesson 4" />
</arena-progress-bar>
```

A ring's middle is projected content, so it can measure something of yours instead of showing
a number. Turn the figure off yourself when you fill it: the two share that space, and this
component decides nothing from what was projected, because the other layer cannot see it either.

<!-- @api GENERATED from contracts/api/components/ArenaProgressBar.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | What sits in the middle of a ring, in place of the percentage: a glyph, a mark, or the control the ring measures. A bar has no middle, so a bar draws nothing for it. The ring's own `progressbar` element is the drawing rather than the box around it, because that role's children are presentational and a control projected inside it would be drawn and never announced; here it is a sibling of the meter and keeps everything it came with. |
| `progressPercentage` | primitive | `number` | `0` | How far along, 0-100. Clamped and rounded. Ignored when `indeterminate`. |
| `indeterminate` | primitive | `boolean` | `false` | A wait with no percentage; the bar sweeps instead of filling. |
| `tone` | enum | `ArenaProgressTone` | `"accent"` | The bar's colour. |
| `label*` | primitive | `string` |  | Names what is progressing. Drawn above the bar or under the ring, and it is the meter's accessible name. Required and guarded rather than defaulted: nothing can derive what is progressing, and a fallback of "Progress" satisfies roles.label mechanically while telling a screen-reader user only what the component is -- two of them on one page announce identically. |
| `showLabel` | primitive | `boolean` | `true` | Draws the label beside the meter. False leaves the meter alone and keeps the accessible name, which is carried by aria-label on the progressbar element rather than by the text. For a bar in a table cell or a card row, where the row already names what is progressing and repeating it is noise. `label` stays required either way, on the reading it already carries: what a screen reader announces is not a decision about what is drawn. It is the same escape ArenaIconButton.showLabel offers, and it is here because the two components pose one question. |
| `showPercentage` | primitive | `boolean` | `true` | Shows the percentage: beside the label on a bar, and in the middle of a ring, which is the figure a meter in a tile is read by. Determinate only. Turn it off when `content` fills a ring's middle: the two share that space, and Arena never derives what it draws from what a consumer projected, because projected content is not inspectable in at least one layer. |
| `size` | enum | `ArenaControlSize` | `"md"` | How heavy the meter is: the bar's thickness, and a ring's diameter with a band the same weight as the bar it replaces. |
| `shape` | enum | `ArenaProgressShape` | `"linear"` | Whether the meter is drawn as a bar or as a ring. A ring puts the percentage inside its own track and the label under it, which is the arrangement a tile wants and the one a row cannot give: a bar is as wide as its row and reads along it, while a ring is as wide as it is tall and reads at a glance. It is a shape rather than a second component because everything else is the same question answered once: the percentage, the tone, the required name, the announcement and the sweep a wait draws. |

<!-- @api end -->

`progressPercentage` is **clamped to 0–100 and rounded**, so a caller cannot report 143% or a
fraction; the same number drives `aria-valuenow` and the fill's width, which is the point,
what a sighted user sees and what a screen reader is told cannot drift apart.

**`indeterminate` is a different claim, not a styling flag.** It drops `aria-valuenow`
altogether, because ARIA expresses indeterminacy by *omitting* the value rather than by
reporting zero: zero is a determinate claim that no progress has been made. `aria-valuemin` and
`aria-valuemax` stay, because they are still true. It also hides the percentage whatever
`showPercentage` says: there is no percentage to show.

**The live region is explicit, and it has content to announce.** `role="progressbar"` carries no
implicit politeness the way `role="status"` does, so the track sets `aria-live="polite"` itself.
A live region reports changes to its **content**, so the percentage is repeated inside the track
as visually-hidden text: reporting progress through the `aria-valuenow` attribute alone leaves a
polite region whose content never changes, and whether an AT announces that at all varies by AT.
`showPercentage` governs the visible number beside the label and never this copy.

`label` names the bar for assistive technology and heads it visually. With none, the accessible
name falls back to `Progress`, which is honest but says nothing about what is progressing,
supply one for anything a user is waiting on.

**Do / Don't**
- **Do** reach for `indeterminate` the moment the percentage stops being knowable. A bar frozen
  at 90% is worse than one that says it is still working.
- **Do** use `tone` for what the progress *means*: `danger` for a failing rollout, `success`
  for one that finished. The track stays the neutral rail in every tone; only the fill is inked,
  because danger is outline in Arena and a progress bar is not the exception.
- **Do** put a ring where the meter is the tile rather than a line in one: a completion ring on
  a dashboard, a node on a path. `size` moves its diameter and its band together, so there is
  nothing else to tune.
- **Don't** use this for a wait with no measurable end and no room for a label. That is
  `arena-spinner`. An indeterminate ring turns, which is close to what a spinner does, and the
  difference is that this one is still a labelled meter and reports a range.
- **Don't** project into a bar: a bar has no middle and the projection is dropped.
- **Don't** reach for a ring to save room. A ring at `sm` is smaller than a bar is long and
  harder to read, and the figure inside it is the point.
- **Don't** put two bars in one row expecting them to read as one process. They are two live
  regions, and a screen reader will announce both.

**By hand, in real Chromium**: the sweep is an animation and happy-dom has none. Run
`bun run demos` and open
`/frameworks/angular/components/feedback/arena-progress-bar/ArenaProgressBar.demo.generated.html`:
- The indeterminate sweep travels left to right, continuously, and **slows** rather than stops
  under `prefers-reduced-motion`, motion that reports work in progress must keep reporting it.
- The determinate fill animates its width on `--dur-state`/`--ease-state` when the value changes,
  and does not
  animate on first paint.
- Each tone inks the fill only; the track behind it stays `--color-base-300` in all five.
- The three sizes differ in track height alone; the head row does not move with them.
- With `shape="radial"` the arc sweeps clockwise from twelve o'clock, its band is the weight of
  the bar it replaces, and an indeterminate ring turns a fixed quarter arc, slowing rather than
  stopping under `prefers-reduced-motion` for the reason the sweep gives.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-sheet/ArenaSheet.prompt.md -->

Arena sheet, a working surface anchored to one edge of the page and kept open beside it rather than
over it: a cart, a filter drawer, a detail pane. Standalone, `OnPush`, signal I/O. The host
**is** the panel, so `<arena-sheet>` is the element you place.

It carries no scrim, traps no focus and takes nothing away from the page behind it. **When a panel
is meant to take the whole interaction until it is answered, that is `arena-dialog`**, two stacking
slots higher, and the scrim is how it says so.

```html
<arena-sheet [open]="cartOpen()" placement="end" title="Cart"
             [collapsed]="folded()" (collapsedChange)="folded.set($event)"
             dismissible (close)="cartOpen.set(false)">
  @for (line of lines(); track line.id) {
    <app-cart-line [line]="line" />
  }
  <div footer>
    <arena-button (click)="checkout()">Checkout</arena-button>
  </div>
</arena-sheet>
```

<!-- @api GENERATED from contracts/api/components/ArenaSheet.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `open*` | primitive | `boolean` |  | Whether the panel is on the page at all. The host owns it, the same way it owns a dialog's. Closed renders nothing, which is what distinguishes it from collapsed. |
| `placement` | enum | `ArenaSheetPlacement` | `"bottom"` | The edge the panel is anchored to. It spans that edge and stands off the device's own inset there, so a bottom sheet on a phone clears the home indicator. |
| `title*` | primitive | `string` |  | Names the panel for assistive technology and heads it visually. It is also the accessible name of the fold control, so a reader hears which panel is being folded rather than the word Toggle. Required and **guarded at runtime** rather than defaulted: what this panel is showing is editorial, and a constant fallback would satisfy the pattern mechanically while telling a screen-reader user nothing. |
| `collapsed` | primitive | `boolean` | `false` | Whether the body is folded away. The header stays visible either way: a collapsed panel is still on the page and still says what it is, which is why folding is not the same act as closing. The body is hidden rather than removed, so the fold control's reference to it never points at nothing. |
| `collapsedChange` | event | `boolean` |  | The fold control was pressed, carrying the state it moved to. Arena never folds the panel by itself, so a host that ignores this gets a control that reports and a body that does not move. |
| `dismissible` | primitive | `boolean` | `false` | Whether the close control is shown. Every layer gates it on this member and never on whether anything listens for `close`, because Arena never derives what it draws from what a consumer listens for. |
| `close` | event |  |  | The panel was dismissed, by the close control or by Escape. No payload. Escape reports here rather than adding a member of its own, and it is the only key the panel takes: a non-modal panel leaves every other key to the page behind it. |
| `content` | slot |  |  | The panel's body, which is what folds away. |
| `footer` | slot |  |  | A row that stays put while the body scrolls: a total and its action, a pair of filters buttons. It is outside the folding body on purpose, so a folded panel can still carry the one action it exists for. |

<!-- @api end -->

**Closed and collapsed are two different states, and both exist.** `open` decides whether the panel
is on the page at all; `collapsed` folds the body away and leaves the header and the footer where
they were. That is what the pattern buys: a reader can put the cart out of the way and still see
what it is and still check out, without losing it. The body is hidden rather than removed, so the
fold control's `aria-controls` never points at nothing.

`title` is required and **guarded at runtime**: a blank one throws rather than rendering a nameless
panel. It heads the panel and it is also the accessible name of the fold control, so a screen-reader
user hears "Cart, collapse" rather than "Toggle". Nothing can derive it, because what the panel is
showing is editorial.

`dismissible` gates the ×. It exists because Angular cannot ask whether an output has subscribers,
so the host says whether the panel is closeable rather than have Arena infer it from a `close`
listener. **Escape reports through that same `close`**, which is why answering it costs no member.
It reaches the panel only while focus is inside it: nothing here took focus in the first place, and
a panel that swallowed Escape from across the page would break a dialog open somewhere else.

**Do / Don't**
- **Do** own both booleans. Neither folds nor closes itself, so a template that ignores
  `collapsedChange` gets a caret that turns and a body that does not move.
- **Do** put the one action the panel exists for in the `footer` slot. It sits outside the folding
  body, so a folded panel still carries it.
- **Don't** reach for it as a menu or a popover. It spans a whole edge and stays; `arena-menu` is
  the transient list that hangs off a trigger.
- **Don't** open two at once on the same edge. They share a stacking slot and one lands on the
  other; a second surface at the same time is a sign the first should have been a dialog.
- **Don't** put a form a reader must finish in it. Nothing stops them clicking away mid-way, which
  is the whole point of a non-modal panel and the whole reason a confirmation is not one.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/feedback/arena-sheet/ArenaSheet.demo.generated.html`:
- The page behind the panel still scrolls and its buttons still take a click, at every placement.
- Folding leaves the header and the footer in place and moves nothing else; the caret turns with it.
- A `ArenaMenu` opened from inside the panel paints over the panel, and the panel paints over a fixed
  bottom bar.
- Tab from the last control in the panel leaves it and lands on the page; nothing is trapped.
- At 390px the bottom panel clears the home indicator when the browser emulates a device inset.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-spinner/ArenaSpinner.prompt.md -->

Arena spinner, an indeterminate wait indicator. Standalone, `OnPush`, signal I/O. The host
**is** the indicator, and it is the live region: `role="progressbar"`, `aria-live="polite"`
and the accessible name all sit on it, with the spinning ring a decorative `aria-hidden` child.

```html
<arena-spinner label="Fetching deployments" />
<arena-spinner size="sm" tone="on-accent" label="Saving" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSpinner.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `size` | enum | `ArenaControlSize` | `"md"` | Diameter. 'sm' is --icon-sm exactly, so a spinner at that size sits inline with control text. |
| `tone` | enum | `ArenaSpinnerTone` | `"accent"` | Colour of the ring. 'on-accent' inside a filled button; 'accent' on a page surface. |
| `label` | primitive | `string` | `"Loading"` | Accessible name, announced by the status role. Say what is loading when you can. |

<!-- @api end -->

It reports **no value at all**: no `aria-valuenow`, no `aria-valuemin`, no `aria-valuemax`,
because a spinner is indeterminate by definition and ARIA expresses that by omitting the value.
Reporting zero would be a determinate claim that nothing has happened.

**The live region is explicit**, the same way `arena-progress-bar`'s is: `role="progressbar"`
carries no implicit politeness, `MatProgressSpinner` set no `aria-live` at all, and that was the
exception the delegated binding carried. This clears it.

`label` defaults to `Loading`, which is a name rather than an absence, but it is a name that
says what the component is instead of what the user is waiting for. Set it.

`tone="on-accent"` exists for a spinner sitting **on** a filled brand surface, inside a loading
button, on a crimson banner, where the accent ink would disappear into its own background.

**Do / Don't**
- **Do** reach for `arena-progress-bar` the moment the wait has a measurable end. A spinner says
  "something is happening"; a bar says how much is left, and a user who can see the end waits
  better.
- **Do** keep one spinner per wait. Three of them in a row are three live regions announcing the
  same thing.
- **Don't** size it with a wrapper. `size` is the axis, `sm` matches an icon, `md` a control,
  `lg` a page-level wait, and a scaled wrapper puts the ring's border width off the token.
- **Don't** leave it on screen with nothing behind it. A spinner that never resolves is the one
  state `arena-error-state` is for.

**By hand, in real Chromium**: the rotation is an animation and happy-dom has none. Run
`bun run demos` and open `/frameworks/angular/components/feedback/arena-spinner/ArenaSpinner.demo.generated.html`:
- The ring rotates continuously on `--loop-spin`, and **slows** to `--loop-reduced` under
  `prefers-reduced-motion` rather than stopping, motion reporting work in progress keeps
  reporting it.
- The gap in the ring is the transparent top border, so the rotation is legible at every size;
  at `sm` it must still read as a ring rather than a dot.
- `on-accent` is the only tone that stays legible on a filled crimson surface, the card puts
  all four on one to show it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-toast-host/ArenaToastHost.prompt.md -->

Arena toast host, the fixed box a stack of notices lives in. Standalone, `OnPush`, signal I/O.
The host **is** the box, so `<arena-toast-host>` is the element you place.

It exists because `arena-toast` carries `--z-toast` and no `position` of its own, and a
statically-positioned element ignores `z-index`: the one thing that must float above every overlay
in the system stops floating unless something places it.

```html
<arena-toast-host placement="bottom-end">
  @for (notice of notices(); track notice.id) {
    <arena-toast [title]="notice.title" [message]="notice.message" [tone]="notice.tone"
                 actionLabel="Retry" dismissible
                 (action)="retry(notice)" (close)="drop(notice)" />
  }
</arena-toast-host>
```

<!-- @api GENERATED from contracts/api/components/ArenaToastHost.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `placement` | enum | `ArenaToastPlacement` | `"bottom-end"` | Which corner the stack is pinned to. A bottom placement clears the device's own bottom inset, so a stack on a phone never lands under the home indicator. |
| `content` | slot |  |  | The notices, in the order they are read. The stack is a plain column and the visual order is the source order, whatever the corner: a reversed one would put the newest notice first on screen and last in the reading order, and the two must agree. Nothing here caps the count or times a dismissal, because the queue that produced these notices already holds their identity and their order, and a cap applied by the box that draws them would fight the queue that owns them. |

<!-- @api end -->

`placement` picks the corner: `top-start`, `top-end`, `bottom-start`, `bottom-end`, default
`bottom-end`. The inline half is `start`/`end` rather than left/right, so a right-to-left document
flips the stack with the text. A bottom placement stands off `max(var(--sp-6),
var(--pad-safe-bottom))`, so on a phone the stack clears the home indicator instead of sitting
under it, and nothing about the device's own geometry is retyped.

**It owns no clock, and it counts nothing.** The queue that produced these notices already holds
their ids, their order and how many there are, so the timer and any ceiling stay there. Read
`data-persist` off each notice and skip the timer for the ones that carry it, and take the interval
from `ARENA_TOAST_DISMISS`, exported beside `arena-toast`:
`.default` for a notice that only has to be read, `.actionable` for one carrying a button.

**Do / Don't**
- **Do** mount exactly one per placement, in the app's root template, outside anything that scrolls
  or transforms: a `transform` on an ancestor becomes the containing block for a fixed descendant,
  and the stack then scrolls away with it instead of staying put.
- **Do** leave the notices in the order they were raised. The stack is a plain column, so what is
  read is what is seen, and reversing the list to put the newest on top puts it last in the reading
  order.
- **Don't** give it a `role` or an `aria-live` of its own. Each `arena-toast` already announces,
  `alert` for danger and `status` for the rest, and a second live region around them announces the
  same notice twice.
- **Don't** put anything but notices in it. It is one positioned box above every overlay in the
  system, the CDK layer included; anything else parked there covers the whole app.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/feedback/arena-toast-host/ArenaToastHost.demo.generated.html`:
- Each of the four corners pins where it says, and the stack grows away from its own edge.
- The gap between two notices is the same in all four, and the standoff from the edges is too.
- With the browser emulating a device that reports a bottom inset, the bottom stack moves up by it
  and the top one does not move at all.
- A notice raised while a dialog is open paints over the dialog.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-toast/ArenaToast.prompt.md -->

Arena toast, an ephemeral notice with a tone-coloured side bar and one optional action.
Standalone, `OnPush`, signal I/O. The host **is** the card, so `<arena-toast>` is the
element you place.

It positions nothing and owns no clock. The host decides where the stack sits and when each
notice goes: `arena-toast-host` is the box that places it, and the clock belongs to the queue that
raised the notice. `ArenaToastQueue`, provided in root, is that queue: inject it, call
`raise(notice)`, render `toasts()` into the host, and the dismissal rule is already inside it. `ARENA_TOAST_DISMISS`, exported beside the component, carries the two intervals to run
it off: `.default` for a notice that only has to be read, `.actionable` for one carrying a button,
which asks the reader to decide rather than only to read. They are tokens, so a host that reads
them stays in step with a release that moves one; a host that retypes 4200 does not. The
component's only say in the matter is `data-persist`, which it sets when the notice must not be
taken away on a timer.

```html
@for (notice of notices(); track notice.id) {
  <arena-toast [title]="notice.title" [message]="notice.message" [tone]="notice.tone"
               actionLabel="Retry" dismissible
               (action)="retry(notice)" (close)="drop(notice)" />
}
```

<!-- @api GENERATED from contracts/api/components/ArenaToast.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title` | primitive | `string` |  | The bold lead line. |
| `message` | primitive | `string` |  | The body. |
| `tone` | enum | `ArenaToastTone` | `"neutral"` | The side bar's colour, and whether the toast announces assertively. |
| `actionLabel` | primitive | `string` |  | The label of the single inline action: Undo, Retry, View logs. Absent renders no action. |
| `action` | event |  |  | The inline action was activated. |
| `persist` | primitive | `boolean` | `false` | Disables the host's auto-dismiss and shows the Pinned marker. **Implied by `tone: "danger"`, which ignores `false`**: a critical message that vanishes on a timer is one a user can miss entirely, and this was documented as mandatory in an error state while nothing enforced it. Set it explicitly for any other tone that must not disappear on its own. |
| `dismissible` | primitive | `boolean` | `false` | Whether the × is shown. Every layer gates the × on this member and never on whether anything listens for `close`, because Arena never derives what it draws from what a consumer listens for. |
| `close` | event |  |  | The × was activated. |

<!-- @api end -->

**Tone decides how the message is announced, and that is the whole reason this primitive
exists.** `tone="danger"` renders `role="alert"` with `aria-live="assertive"`, so a critical
message interrupts whatever a screen reader is already saying; every other tone renders
`role="status"` with `aria-live="polite"` and queues behind it. `persist` is **implied by
danger and ignores an explicit `false`**: a critical message that vanishes on a timer is one a
user can miss entirely, and a pinned toast says so visibly with the `Pinned` marker as well as
in `data-persist`.

`dismissible` gates the ×. It exists because Angular cannot ask whether an output has
subscribers, so the host has to say whether the notice is closeable rather than have Arena infer
it from a `close` listener.

**Do / Don't**
- **Do** read `data-persist` in the host's own clock and skip the timer for any toast that
  carries it. Danger sets it for you; anything else sets it through `persist`.
- **Do** keep `message` to one line of consequence. The title is the lead; a toast is not where
  a paragraph goes.
- **Don't** put more than one action on it. `actionLabel` is singular on purpose: Undo, Retry,
  View logs. A notice with two choices is a dialog.
- **Don't** reach for `tone="danger"` for anything a user can ignore. Assertive announcement cuts
  a screen reader off mid-sentence, and a tone that always interrupts stops meaning anything.
- **Don't** give it a `position` of its own. It carries `--z-toast`, the one slot above every
  other overlay including the CDK layer, but a statically-positioned element ignores `z-index`,
  the stack's own container is what places it.

**By hand, in real Chromium**: the announcement is a screen reader's, not a browser's, so what
this page shows is the rest. Run `bun run demos` and open
`/frameworks/angular/components/feedback/arena-toast/ArenaToast.demo.generated.html`:
- Each tone's left bar takes its own colour and the card surface never does; danger is
  **outline**, never a filled red panel.
- A danger toast shows `Pinned` even when the host passed `persist="false"`, and the demo's
  clock leaves it alone while every other toast expires.
- The action and the × are two separate controls, both reachable by Tab, and the × sits outside
  the body column rather than inside it.
- Stacked against an open dialog, a toast paints above it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/feedback/arena-tooltip/ArenaTooltip.prompt.md -->

Arena tooltip, a short label revealed on pointer intent, bone over dark. Standalone, `OnPush`,
signal I/O. Wrap the element the tooltip describes; Arena draws the bubble and names it
from `label`.

The bubble is positioned by `@angular/cdk/overlay`, not by the wrapper, so it escapes an
`overflow: hidden` ancestor and stays anchored while the page scrolls. That is the one thing
Arena does not hand-roll here; focus and roles stay Arena's. The app must import
`frameworks/angular/theme/arena-cdk.css` once, or the bubble renders unpositioned.

```html
<arena-tooltip label="Everything shipped in the last 30 days">
  <button type="button">Deployments</button>
</arena-tooltip>

<arena-tooltip label="95th percentile response time">
  <span tabindex="0">p95</span>
</arena-tooltip>
```

<!-- @api GENERATED from contracts/api/components/ArenaTooltip.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | The bubble's text. Arena draws the bubble; the consumer names it. |
| `content*` | slot |  |  | The element the tooltip describes and attaches to. |

<!-- @api end -->

**Do / Don't**
- Project exactly **one** element, and one that can take an attribute. Arena writes
  `aria-describedby` onto the wrapper's first element child, so a bare string or several
  siblings leave the bubble naming nothing. The trigger's own `aria-describedby` is preserved:
  the bubble's id is appended on reveal and removed on withdrawal.
- Project something **focusable**. A tooltip on an unfocusable element is unreachable without a
  pointer, give it `tabindex="0"` if it is not natively focusable, as the `p95` example does.
- A pointer waits `--delay-open` (400 ms) before the bubble appears and `--delay-close` (120 ms)
  before it withdraws, so crossing a toolbar reveals nothing. **Keyboard focus reveals
  immediately**, and that asymmetry is deliberate: a delay on focus reads as an unresponsive
  control. `contracts/design/behaviour.json` states the rule; do not route focus through the
  delays.
- Escape dismisses, and the listener is on the document rather than the host, because a
  pointer-invoked tooltip leaves focus somewhere else entirely.
- Don't put interactive content in a tooltip. It never receives focus, so a button inside it is
  unreachable: that is `focus.never` in the pattern, not a limitation of this implementation.
  Reach for `arena-menu` or a dialog instead.
- Don't use a tooltip to carry information the user needs to complete a task. It is
  supplementary by definition; a field's own `hint` is where a requirement belongs.
- Don't set `label` to the trigger's own text. `aria-describedby` is read **in addition** to the
  name, so a bubble repeating the label just says everything twice.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/feedback/arena-tooltip/ArenaTooltip.demo.generated.html`, which lays out one
section per item below:
- The bubble sits centred above the trigger with a `--sp-2` gap, and **flips below** when the
  trigger is near the top of the viewport.
- It escapes a scrolling `overflow: hidden` container and stays anchored while that container
  scrolls, which is the whole reason for the overlay.
- The reveal genuinely waits on pointer rest and is instant on Tab; travelling from the trigger
  onto the bubble does not dismiss it.
- Layering: a tooltip on an `arena-menu` item, and one inside an open dialog, both land above
  what they annotate.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-button/ArenaButton.prompt.md -->

Arena action button, one primary per view, and danger stays outline. Standalone, `OnPush`,
signal I/O. The host stays bare and unstyled: Arena's own styling lands on a real `<button>`
inside it, because the element carrying the behaviour contract must be the element the browser
already knows how to focus, activate and disable.

```html
<arena-button (click)="save()">Save changes</arena-button>
<arena-button variant="secondary" size="sm">Cancel</arena-button>
<arena-button variant="danger" icon="ph-bold ph-trash" (click)="confirmDelete()">Delete project</arena-button>
<arena-button variant="ghost" iconRight="ph-bold ph-caret-down">More</arena-button>
<arena-button loading>Deploying</arena-button>
<arena-button type="submit" form="project-form" full>Create project</arena-button>
```

<!-- @api GENERATED from contracts/api/components/ArenaButton.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The button's label. Sits between the two icons when both are given. |
| `variant` | enum | `ArenaButtonVariant` | `"primary"` | Which action this is. Danger is outline, never filled. |
| `size` | enum | `ArenaControlSize` | `"md"` | Height, from the density tokens, so the button re-densifies inside .arena-compact. |
| `icon` | primitive | `string` |  | Phosphor class name drawn before the label. Replaced by the spinner while loading. |
| `iconRight` | primitive | `string` |  | Phosphor class name drawn after the label: a caret on a menu trigger, an arrow on a next action. |
| `loading` | primitive | `boolean` | `false` | Replaces the leading icon with a spinner and blocks activation. The spin slows under reduced motion rather than stopping: a frozen spinner reads as a hung process. |
| `full` | primitive | `boolean` | `false` | Stretches to the container's width. |
| `disabled` | primitive | `boolean` | `false` | Blocks activation and dims the control. Implied by loading. |
| `type` | enum | `ArenaButtonType` | `"button"` | Native button behaviour. Defaults to 'button' so a button inside a form does not submit it by accident. |
| `name` | primitive | `string` |  | Submitted with the form, when the button submits one. |
| `value` | primitive | `string` |  | The value submitted under `name`. |
| `autoFocus` | primitive | `boolean` | `false` | Focused on mount. |
| `form` | primitive | `string` |  | The id of the form this button belongs to, when it is not a descendant of it. |
| `tabStop` | primitive | `boolean` | `true` | Whether the control is reached from the page's Tab sequence. Set false when it lives inside a composite that manages its own focus (a grid with a roving tab stop, a menu), where reaching it by Tab would be a second way in. Arena writes tabindex="-1" and the control stays programmatically focusable; a positive tab order is not expressible and never should be. Arena's own table is NOT that composite: its grid deliberately has no step-in, so a control in a cell keeps its place in the page Tab sequence and setting this false there takes away its only keyboard route, since the cursor moves by cell and Enter activates the row. |
| `click` | event |  |  | The button was activated, by pointer or by keyboard. |

<!-- @api end -->

**Do / Don't**
- Use `variant="danger"` for a destructive action: transparent background, border and text in
  `--error`. That is the danger convention, and the only filled danger surface in Arena is
  `ArenaConfirmDialog`'s final confirmation.
- `loading` implies `disabled`: it swaps the leading icon for a spinner and blocks activation,
  so there is no need to set both. The spin **slows** under `prefers-reduced-motion` rather
  than stopping, because a frozen spinner reads as a hung process; that answer comes from the
  shared design layer, not from this component.
- `icon` and `iconRight` are Phosphor class-name strings Arena draws, never slots. That is the
  single-icon convention, and it is why this component projects a label and nothing else.
- Set `type` explicitly when the button sits in a form. It defaults to `button` on purpose: a
  bare `<button>` inside a form silently defaults to `submit`, which is the footgun this member
  exists to make explicit. Use `form` only when the button is **not** a descendant of the form
  it submits.
- Reach for `tabStop="false"` only inside a composite that manages its own focus (a grid with
  a roving tab stop, a menu) where reaching this control by Tab would be a second way in. It
  writes `tabindex="-1"` and the control stays programmatically focusable. A positive tab order
  is not expressible and never should be.
- Don't use `disabled` to mean "this action is not available yet" on a control the user must
  discover. A disabled button is unreachable by Tab and announces nothing about why; prefer
  keeping it enabled and reporting the reason on activation.
- Don't wrap `<arena-button>` in another button or an anchor. It renders a real `<button>`, and
  nesting interactive elements is invalid regardless of how it looks.
- Don't rely on click delegation from an ancestor. `click` is an output named after a native
  DOM event, and Angular then registers **both** the output subscription and a host DOM
  listener, so a consumer's `(click)` would fire twice on every press. The inner button calls
  `stopPropagation()` to make it fire once, which is the whole reason the event does not reach
  ancestors. Bind `(click)` on the `<arena-button>` itself. `type="submit"` still submits: the
  default action is untouched, only propagation is.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/forms/arena-button/ArenaButton.demo.generated.html`:
- With `loading` set, the spinner turns; with `prefers-reduced-motion: reduce` forced in
  DevTools' Rendering pane, it keeps turning and only slows.
- `active:scale-98` gives a real press response, and the gold focus ring is visible on
  keyboard focus, for every one of the four variants, including `ghost`, whose border is
  transparent.
- `full` spans the row. The host is bare, so it carries `display: contents` to stay out of
  layout; without that it blockifies to shrink-to-fit as a flex item and `w-full` measures the
  shrunk host instead of the row.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-checkbox/ArenaCheckbox.prompt.md -->

Arena checkbox, one independent choice, checked showing a crimson fill with a tick. Standalone,
`OnPush`, signal I/O. The host stays bare
and out of layout: the root is a real `<label>` wrapping a real `<input type="checkbox">`, because
that pairing is what gives the control its role, its name and Space-to-toggle without a single
line of authored ARIA.

```html
<arena-checkbox label="Notify on failure" [checked]="notify()" (change)="notify.set($event)" />
<arena-checkbox label="Managed by policy" checked disabled />
<arena-checkbox label="I accept the terms" required name="terms" value="yes"
                [checked]="accepted()" (change)="accepted.set($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaCheckbox.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `checked` | primitive | `boolean` | `false` | Whether it is ticked. |
| `label` | primitive | `string` |  | Text beside the box. |
| `disabled` | primitive | `boolean` | `false` | Blocks toggling and dims it. |
| `required` | primitive | `boolean` | `false` | Must be checked for the form to submit. |
| `name` | primitive | `string` |  | Submitted with the form. |
| `value` | primitive | `string` |  | The value submitted under `name` when checked. |
| `change` | event | `boolean` |  | Toggled; carries the new checked state. |

<!-- @api end -->

**Do / Don't**
- It is **controlled**. `checked` is what the consumer owns and pushes back in; the component
  never holds a copy, so a `(change)` you ignore is a checkbox that visibly does not move.
- **Always pass `label`.** It is optional in the contract, but the accessible name comes from the
  wrapping `<label>`'s own text, so a checkbox without one announces nothing. If the name must
  live elsewhere on screen, the control is the wrong shape; reach for a labelled group instead.
- `change` carries the new boolean, not the DOM event. It is an output named after a native DOM
  event, so Angular would register both the output subscription and a host DOM listener and a
  consumer's `(change)` would fire twice; the inner input calls `stopPropagation()` to make it
  fire once. The cost is that a native `change` never reaches an ancestor, bind on the
  `<arena-checkbox>` itself.
- `disabled` and `required` land on the native input, never as `aria-disabled` or
  `aria-required`. The native attributes are what the accessibility tree reads, what removes the
  control from the Tab order, and what Arena's `:disabled`-family styling can match.
- The box and the tick are decoration: the `<span>` carries the fill and the `<svg>` the tick,
  and neither is the control. Do not attach a click handler to either, because the `<label>` already
  forwards a click to the input, and a second handler double-toggles.
- Don't use a checkbox for an immediate effect. A checkbox reads as a pending form value; a
  setting that applies the moment it flips is `<arena-switch>`.
- There is no indeterminate state. `aria-checked="mixed"` is in the pattern and not in this
  contract, so a partially-selected parent row needs a different control, not this one.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/forms/arena-checkbox/ArenaCheckbox.demo.generated.html`:
- The tick's stroke reads cleanly on the crimson fill at 100% zoom, and its box is `--sp-3`
  inside an `--sp-5` square rather than filling it.
- Clicking the label text toggles the box, and so does Space with the control focused.
- `disabled` dims the whole control to 50% and the cursor turns to not-allowed over the label
  as well as the box.
- Tab to the control and the **box** takes a gold focus ring, even though the element the
  browser focused is the `opacity-0 size-0` native input. The `box` slot carries
  `[&:has(~input:focus-visible)]:shadow-[…]`, which reaches the input as a later sibling inside
  the same `<label>`, so the input must stay after the box in the template, and moving it
  removes the ring with nothing failing.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-icon-button/ArenaIconButton.prompt.md -->

Arena icon-only button, an action compact enough to carry no visible text, and an accessible
name in every state regardless. Standalone, `OnPush`, signal I/O. The host stays
bare and out of layout: Arena's own styling lands on a real `<button>` inside it, because the element
carrying the behaviour contract must be the element the browser already knows how to focus,
activate and disable.

```html
<arena-icon-button icon="ph-bold ph-trash" label="Delete project" (click)="confirmDelete()" />
<arena-icon-button icon="ph-bold ph-plus" label="New project" variant="solid" (click)="create()" />
<arena-icon-button icon="ph-bold ph-pencil-simple" label="Rename" size="sm" (click)="rename()" />
<arena-icon-button icon="ph-bold ph-download-simple" label="Export CSV" showLabel (click)="export()" />
<arena-icon-button icon="ph-bold ph-arrow-clockwise" label="Retry" disabled />
<arena-icon-button icon="ph-bold ph-push-pin" label="Pin this view" [pressed]="pinned()" (click)="pinned.set(!pinned())" />
```

<!-- @api GENERATED from contracts/api/components/ArenaIconButton.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `icon*` | primitive | `string` |  | Phosphor class name, e.g. 'ph-bold ph-plus'. Arena draws the <i> and hides it from assistive technology; `label` is the accessible name. |
| `label*` | primitive | `string` |  | The accessible name, present in every state. Also the visible text when showLabel is set, and the title attribute when it is not. |
| `size` | enum | `ArenaControlSize` | `"md"` | Height, from the density tokens: the same scale ArenaButton uses, so the two re-densify together in a toolbar. |
| `variant` | enum | `ArenaIconButtonVariant` | `"ghost"` | Visual treatment. |
| `showLabel` | primitive | `boolean` | `false` | Shows the label as text beside the icon (H6). Don't rely on the title alone on touch or keyboard surfaces. |
| `pressed` | primitive | `boolean` |  | Whether this control is a toggle, and whether it is currently on. Present, Arena writes aria-pressed and draws the on state with the same accent tint a current ArenaSideNav item takes, so "this one is on" is one statement across the library; absent, the control is not a toggle at all. The tri-state is the point and a default of false would destroy it: aria-pressed="false" on a plain button announces a toggle that is off rather than a button, so every ArenaIconButton in the system would announce as an unpressed toggle. The label does NOT change with the state, which is what the button pattern means by a toggle: a control that renames itself is announced as a different control rather than as the same one in another state. |
| `disabled` | primitive | `boolean` | `false` | Blocks activation and dims the control. |
| `type` | enum | `ArenaButtonType` | `"button"` | Native button behaviour. Defaults to 'button' so an icon button inside a form does not submit it by accident. |
| `name` | primitive | `string` |  | Submitted with the form, when the button submits one. |
| `value` | primitive | `string` |  | The value submitted under `name`. |
| `autoFocus` | primitive | `boolean` | `false` | Focused on mount. |
| `form` | primitive | `string` |  | The id of the form this button belongs to, when it is not a descendant of it. |
| `tabStop` | primitive | `boolean` | `true` | Whether the control is reached from the page's Tab sequence. Set false when it lives inside a composite that manages its own focus (a grid with a roving tab stop, a menu), where reaching it by Tab would be a second way in. Arena writes tabindex="-1" and the control stays programmatically focusable; a positive tab order is not expressible and never should be. |
| `click` | event |  |  | The button was activated, by pointer or by keyboard. |

<!-- @api end -->

**Do / Don't**
- `label` is **required and is the accessible name**, not a decoration. It is the `aria-label` in
  every state, the visible text under `showLabel`, and the `title` when there is none. An icon
  button without it announces nothing at all, which is why this input has no default.
- **`pressed` is what makes it a toggle, and its absence is a state of its own.** Bound, Arena
  writes `aria-pressed` and draws the on state with the accent tint a current `arena-side-nav`
  item takes; unbound, the control is not a toggle at all. Never default it to `false`: on a
  plain button `aria-pressed="false"` announces a toggle that is off rather than a button, so
  every icon button in the app would read as an unpressed toggle.
- **A toggle keeps its `label` in both states.** Changing the name to carry the state is the
  workaround `pressed` exists to end: a screen reader then announces a different control instead
  of the same one in another state. Name what it does, not what pressing it will do next.
- `icon` is a Phosphor class-name string Arena draws inside an `aria-hidden` `<i>`, never a slot.
  That is the single-icon convention, and it is why this component projects nothing.
- The `title` is dropped the moment `showLabel` is set. A title beside a visible label makes the
  browser draw a tooltip repeating what is already on screen.
- Don't rely on the `title` alone on a touch or keyboard surface, because a title appears on pointer
  hover and nowhere else. Set `showLabel`, or reach for `arena-tooltip` on the trigger.
- `variant="solid"` fills with the brand and is for the one primary action in a dense toolbar.
  `ghost` is the default and the right answer nearly always; a row of solid icon buttons has no
  hierarchy left to spend.
- There is no `danger` variant, and that is the danger convention rather than an omission: a
  destructive action needs a word, so use `<arena-button variant="danger">`.
- `size` reads the same density tokens `arena-button` does, so the two re-densify together in a
  toolbar. Set the same `size` on both or they will not line up.
- Reach for `tabStop="false"` only inside a composite that manages its own focus (a grid with a
  roving tab stop, a menu) where reaching this control by Tab would be a second way in.
- Don't rely on click delegation from an ancestor. `click` is an output named after a native DOM
  event, and Angular then registers **both** the output subscription and a host DOM listener, so
  a consumer's `(click)` would fire twice on every press. The inner button calls
  `stopPropagation()` to make it fire once, which is the whole reason the event does not reach
  ancestors. Bind `(click)` on the `<arena-icon-button>` itself; `type="submit"` still submits,
  because the default action is untouched and only propagation is.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/forms/arena-icon-button/ArenaIconButton.demo.generated.html`:
- The focus ring is visible on keyboard focus for both variants, including `ghost`, whose
  background is transparent.
- Without `showLabel` the control is square at every size, and the glyph is optically centred
  rather than merely boxed in the middle.
- Hovering shows the `title`, and setting `showLabel` stops it appearing at all.
- `disabled` dims to 45% and the cursor turns to not-allowed; both come from `:disabled`
  variants, so they prove the native attribute is really set.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-input/ArenaInput.prompt.md -->

Arena text field, label above, hint or error below, and a validation state the field wears.
Standalone, `OnPush`, signal I/O. The host binds the root slot, so `<arena-input>` is itself
the column its parent lays out. The control is a real `<input>`, named by a real
`<label for>`.

```html
<arena-input label="Project name" [value]="name()" (change)="name.set($event)"
             hint="Lowercase, no spaces" required />

<arena-input label="Repository" icon="ph-bold ph-git-branch" prefix="git@"
             [value]="repo()" (change)="repo.set($event)" />

<arena-input label="Contact email" type="email" [value]="email()" (change)="email.set($event)"
             [validate]="notEmpty" validateOn="change" />

<arena-input label="Slug" [value]="slug()" [error]="serverError()" (change)="slug.set($event)" />
<arena-input label="Created" type="date" [value]="created()" readOnly />
```

<!-- @api GENERATED from contracts/api/components/ArenaInput.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label` | primitive | `string` |  | Field label above the control. |
| `id` | primitive | `string` |  | The control's id, and what the label's `for` points at. Generated from `label` when omitted, as `in-` followed by the label with each run of whitespace replaced by a single hyphen and the whole lowercased. The derivation is normative, and the prefix differs per component on purpose: the same markup must get the same id in every layer, and an ArenaInput and an ArenaTextarea sharing a label must not collide. |
| `hint` | primitive | `string` |  | A line of help under the field. |
| `error` | primitive | `string` |  | Controlled error message; wins over `validate`. |
| `valid` | primitive | `boolean` | `false` | Force the valid (green check) state. |
| `required` | primitive | `boolean` | `false` | Marks the label and the control required. |
| `validate` | functionInput | `(value: string) => string` |  | Called on the value; returns the error message, or empty for valid. |
| `validateOn` | enum | `ArenaValidateOn` | `"blur"` | When `validate` runs. |
| `type` | enum | `ArenaInputType` | `"text"` | Native input type. |
| `icon` | primitive | `string` |  | Phosphor class name drawn at the field's start. |
| `prefix` | primitive | `string` |  | Static text Arena draws before the value, e.g. `git@`. |
| `value` | primitive | `string` |  | The controlled text. |
| `disabled` | primitive | `boolean` | `false` | Blocks editing and dims it. |
| `readOnly` | primitive | `boolean` | `false` | Shows the value but blocks editing. |
| `placeholder` | primitive | `string` |  | Shown when empty. |
| `name` | primitive | `string` |  | Submitted with the form. |
| `autoComplete` | primitive | `string` |  | The browser autofill hint. |
| `min` | primitive | `string` |  | Minimum, for number/date types. |
| `max` | primitive | `string` |  | Maximum, for number/date types. |
| `step` | primitive | `string` |  | Step, for number/date types. |
| `maxLength` | primitive | `number` |  | Caps the length. |
| `pattern` | primitive | `string` |  | A regex the value must match. |
| `change` | event | `string` |  | Edited; carries the new value. |
| `blur` | event | `string` |  | Left the field; carries the value. |

<!-- @api end -->

**`validate` is the one member that takes a function.** You supply it, the component calls it on
the field's value, and it returns the error message or the empty string. Bind it as a bare
arrow: the input is optional already, so a `| undefined` arm in the type says a second time what
leaving it unbound says once.

```ts
readonly validate = input<(value: string) => string>();
```

Return the message, or the empty string when the value is good.

**Do / Don't**
- It is **controlled**. `value` is what the consumer owns; `change` fires on every keystroke and
  carries the text. **Angular will not force the DOM back**: ignore `change` and the box keeps
  what the user typed. Wire the signal.
- `error` **wins over `validate`**, and it wins even when it is the empty string: a controlled
  error that is present-and-blank suppresses the validator and shows the hint. Every use of the
  resolved error reads its truthiness rather than its nullness, which is what
  `ArenaInput.json` contracts. Pass `undefined`, not `''`, to mean "no controlled error".
- `validate` runs on blur by default. Its message appears only once the field is **touched**, so
  an untouched form never accuses the user of anything. `validateOn="change"` touches on the
  first keystroke instead; reach for it on a field with a cheap, obvious rule.
- The valid state (green ring, check) is either `valid` set by the consumer, or a touched field
  whose validator returned nothing. It is not "the field has a value".
- The focus ring is the field's, not the control's: the `field` slot carries `focus-within:`,
  so there is no focus signal to keep in sync with the DOM.
- `id` is derived from `label` as `in-<slug>` when you do not pass one; the derivation
  `ArenaInput.json` states, so the same markup gets the same id in every layer. Pass `id` when two
  fields share a label.
- `required` and `readOnly` land on the native attributes rather than on `aria-required` and
  `aria-readonly`. Those are what a native control's accessibility tree already reports, and
  writing both would be two claims that can disagree.
- `icon`, `prefix` and the status glyphs are decoration and all four are `aria-hidden`. The error
  message beside the glyph is what carries the state, so nothing announces a Phosphor
  ligature beside the message it duplicates.
- The error line **replaces** the hint rather than stacking under it. Two lines of guidance under
  one field is one too many.
- `type` is the `ArenaInputType` enum. `checkbox` and `radio` are not among them: those are
  `<arena-checkbox>` and `ArenaRadio`, their own components.
- Don't reach for `change` to run an expensive query. It fires per keystroke by design; debounce
  in the consumer, where the interval is a decision about that query rather than about the field.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/forms/arena-input/ArenaInput.demo.generated.html`:
- `type="date"`: the picker indicator is **visible** on the dark field and brightens on hover.
  That is Arena's own `[&::-webkit-calendar-picker-indicator]:` styling reading
  `--picker-invert`; without it the browser draws a black glyph on a dark surface. Toggle
  `.arena-light` on `<html>` and it must invert with the theme.
- The gold focus ring appears on the field group, not on the input, and a valid field keeps its
  green border while showing that ring.
- The error border and ring appear at rest, with no focus needed.
- Typing into the validated field and leaving it produces the message on blur, and the
  `validateOn="change"` one produces it while typing and clears it again.

### Taking focus, the one method on the component

`arena-input` exposes `focus()` and `select()` on the class. Reach them with a `viewChild`, and
never by querying the real `<input>` out of the host, which is Arena's markup and can move:

```ts
readonly search = viewChild.required(ArenaInput);

completeSale(): void {
  this.record();
  this.search().focus();
  this.search().select();
}
```

They are methods rather than members because no member is imperative, and `autoFocus` would
answer a different question: it fires once at mount, and chaining sales needs focus back after
**every** completion. These two are the whole surface; `ArenaInput` exposes no other method.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-radio-group/ArenaRadioGroup.prompt.md -->

Arena single-selection group, governs the value and distributes it to its `arena-radio`
children. Standalone, `OnPush`, signal I/O. The host **is** the radiogroup: it carries the role,
the accessible name and the column layout, so there is no wrapper inside it.

```html
<arena-radio-group ariaLabel="Deployment target" name="env" [value]="target()"
                   (change)="target.set($event)">
  <arena-radio value="production" label="Production" hint="Serves real traffic" />
  <arena-radio value="staging" label="Staging" />
  <arena-radio value="qa" label="QA" [disabled]="!canReachQa()" />
</arena-radio-group>
```

<!-- @api GENERATED from contracts/api/components/ArenaRadioGroup.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `ariaLabel*` | primitive | `string` |  | Names the group: what is being chosen, not that it is a choice. Required, and guarded at runtime: a radiogroup with no accessible name is announced unlabelled, and each option's own label says what that option is, never what the set is for. "Deployment target", not "Options". Distinct from `name`, which is the radios' shared form name and never reaches a screen reader. |
| `content` | slot |  |  | The Radios. An option never holds a selected state of its own -- the group owns it, and how the two are wired is each layer's business rather than this contract's. |
| `value` | primitive | `string` |  | The selected option's value. |
| `name` | primitive | `string` |  | Shared name for the underlying radios; generated when omitted. |
| `change` | event | `string` |  | A different option was chosen; carries its value. |

<!-- @api end -->

**The children pull; the parent does not push.** `arena-radio` injects a
`ArenaRadioGroupState` the group provides and reads the shared name and the selected value from it,
reporting a choice back through it. Nothing is injected into the option, which is why none of that
coordination is a member of either contract and why an option outside a group is a DI error rather
than a silently inert control.

**Do / Don't**
- **`ariaLabel` is required.** It names *what is being chosen*, "Deployment target", not
  "Options". Each option's own label says what that option is, never what the set is for, so a
  group without this is announced unlabelled.
- `ariaLabel` is not `name`. `name` is the radios' shared form name and never reaches a screen
  reader; it is generated per instance when omitted, which matters because **two groups sharing one
  name rove as a single group**.
- **The roving tab stop, the arrow keys and Space are the platform's, not Arena's.** The options
  are native `<input type="radio">` sharing one `name`, and that is the entire mechanism: the
  browser gives the group one tab stop, lands focus on the checked option, and moves selection with
  the arrows. Arena authors **no `tabindex` anywhere**: doing so would fight it.
- It works controlled or not. Pass `value` and it is yours; omit it and the group remembers the
  last choice itself. `change` fires either way.
- Wrapping an `arena-radio` in your own component or a `@for` block is fine, because projection reaches
  it however deep, because the child resolves the group through DI rather than by being a direct
  child. Nothing here inspects its own children, so nothing between them can break it.
- Don't put a lone `arena-radio` outside a group. A single radio is a checkbox with worse
  semantics, and this one will throw for want of its provider.

**By hand, in real Chromium**: the platform behaviour above is exactly what happy-dom cannot show,
so this is the only place it is checked at all. Run `bun run demos` and open
`/frameworks/angular/components/forms/arena-radio-group/ArenaRadioGroup.demo.generated.html`:
- Tab into the group **once**: focus lands on the checked option, and Tab again leaves the group
  entirely rather than walking the other options.
- Arrow Down/Right and Up/Left move the selection and wrap at both ends.
- The disabled option is skipped while arrowing, and cannot be reached by Tab.
- Tab in and the focused option's **ring** takes a gold focus ring, though the focused element
  is the `opacity-0 size-0` native input. The `ring` slot carries
  `[&:has(~input:focus-visible)]:shadow-[…]`, which reaches the input as a later sibling, so the
  input must stay after the ring in the template, and moving it removes the ring silently.
  `arena-checkbox` draws the identical ring the identical way.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-radio/ArenaRadio.prompt.md -->

One option inside an `arena-radio-group`. Standalone, `OnPush`, signal I/O. The host stays bare
and out of layout: the root is a real `<label>` wrapping a real `<input type="radio">`, which is
what gives the option its role, its name and its place in the group's arrow cycle without a line
of authored ARIA.

```html
<arena-radio value="production" label="Production" hint="Serves real traffic" />
<arena-radio value="staging" label="Staging" />
<arena-radio value="qa" label="QA" disabled />
```

<!-- @api GENERATED from contracts/api/components/ArenaRadio.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `value*` | primitive | `string` |  | This option's value, matched against the group's. |
| `label` | primitive | `string` |  | The option's label. |
| `hint` | primitive | `string` |  | A line of help under the label. |
| `disabled` | primitive | `boolean` | `false` | Blocks selection and dims the option. |

<!-- @api end -->

**Do / Don't**
- It has **no `checked` and no event**, and that is the contract rather than an omission. The
  option reads the selected value from the `ArenaRadioGroupState` its group provides and reports a
  choice back through it, so there is nothing for a consumer to wire per option. Bind
  `(change)` on the group.
- `value` is required and is what the group's `change` carries. Two options with the same value in
  one group is a group that cannot tell them apart.
- `label` is optional in the contract, and an option without one is announced by its value at
  best. Pass it.
- `hint` is a second line under the label, at the smaller type level. Use it for the consequence of
  choosing, "Serves real traffic", not to restate the label. The ring aligns to the top of the
  text precisely so a hint does not push it off centre.
- `disabled` sets the native attribute, so the browser skips this option while arrowing and it
  cannot be reached by Tab. The JS guard beside it exists because the `<label>` is clickable and a
  label carries no disabled state of its own.
- The ring and the dot are decoration; the input is the control. Don't attach a handler to either:
  the `<label>` already forwards a click, and a second handler double-reports.
- To toggle one thing on and off, this is the wrong control: use `arena-switch` for an immediate
  effect and `arena-checkbox` for a pending form value.

**By hand, in real Chromium**: the option's own visuals, on the group's page (`bun run demos`,
`/frameworks/angular/components/forms/arena-radio-group/ArenaRadioGroup.demo.generated.html`):
- Selecting changes **only** the ring's border colour and adds the dot; the ring's size and
  surface do not move, so the row does not shift by a pixel.
- With a hint present, the ring stays level with the first line of the label rather than centring
  against both lines.
- `disabled` dims the whole option, label and hint included, and the cursor is not-allowed over
  the text as well as the ring.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-select/ArenaSelect.prompt.md -->

Arena select, a styled **native** `<select>`. Standalone, `OnPush`, signal I/O. The host is
the field's column, label above, control below, so put `<arena-select>` straight into a form
row.

Native is the whole design, not a shortcut. The browser draws the popup, runs its keyboard and
gives a phone its own platform picker; Arena supplies the surface, the caret and the focus ring.
That is why it binds the `select` pattern rather than `combobox`, and why `aria-expanded`,
`aria-controls` and `aria-activedescendant` are absent, because authoring them would be a claim about a
popup this component does not own.

```html
<arena-select label="Environment" [options]="environments" [value]="env()" name="env"
              (change)="env.set($event)" />

<arena-select label="Customer" [options]="customers" [value]="customer()"
              placeholder="Choose a customer" icon="ph-bold ph-user"
              [error]="customerError()" (change)="customer.set($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSelect.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label` | primitive | `string` |  | Field label above the control. |
| `placeholder` | primitive | `string` |  | An empty-valued first option, drawn before the choices and unselectable once a real one is made -- "Choose a customer". It is an option rather than an attribute because a native select has no placeholder, and it is what makes "nothing chosen yet" distinguishable from "the first choice". |
| `options` | array | `readonly ArenaSelectOption[]` | `[]` | The choices, drawn as native options. |
| `value` | primitive | `string` |  | The selected option's value. |
| `disabled` | primitive | `boolean` | `false` | Blocks the control and dims it. |
| `required` | primitive | `boolean` | `false` | Must have a value for the form to submit. |
| `hint` | primitive | `string` |  | A line of help under the field. |
| `error` | primitive | `string` |  | Controlled error message. It is the whole validation surface here, unlike ArenaInput, which also takes a `validate` function: a native select offers a closed list, so there is no value to parse and nothing for a validator to reject that the options did not already prevent. |
| `valid` | primitive | `boolean` | `false` | Force the valid (green check) state. |
| `icon` | primitive | `string` |  | Phosphor class name drawn at the field's start. |
| `name` | primitive | `string` |  | Submitted with the form. |
| `change` | event | `string` |  | A different option was chosen; carries its value. |

<!-- @api end -->

**Validation is the same vocabulary `ArenaInput` carries, deliberately.** A form that mixes the two is
a form whose fields must report a failure the same way, or it gets validated by hand or not at
all. `hint` is a line of help, `error` is the controlled message, `valid` forces the green state,
and the state order is the same normative one: **error, then focus, then valid, then neutral**, so
an errored field stays crimson while it has focus. Arena names the note to the control with
`aria-describedby` and marks the control `aria-invalid`, so the failure is announced rather than
only drawn. `error` replaces `hint` rather than joining it: a field that still shows its advice
buries the failure under it.

**There is no `validate`, and that is not an omission.** `ArenaInput` takes one because a text field
holds a value the consumer must parse; a native select offers a closed list, so there is nothing
to reject that the options did not already prevent. Where the rule depends on something else on
the screen, hold `error` in your own state and pass it in, which is what a controlled message is
for.

**`placeholder` is an empty-valued first option, not an attribute**, because a native select has
none. It is disabled once a real choice is made, which is what keeps "nothing chosen yet"
distinguishable from "the first choice".

```ts
protected readonly environments: ArenaSelectOption[] = [
  { value: 'staging', label: 'Staging' },
  { value: 'production', label: 'Production' },
];
```

`label` is what names the control for assistive technology; Arena renders a real `<label for>`
pointing at the control's own generated id. It is optional in the contract, but a select with no
label and no surrounding `<label>` has no accessible name at all, so supply one or name it from
outside.

`change` carries the chosen **value**, not the event. The native `change` a `<select>` fires
shares that name, so Arena stops it inside the host: a consumer listening on an ancestor is told
once, by the output, and never by the raw DOM event. That is measured rather than asserted in
prose.

**Do / Don't**
- **Do** give every option a `value` distinct from its `label`. `value` is what submits and what
  `value` is matched against; `label` is free to read differently.
- **Do** pair it with `name` when the control is inside a real form. The attribute lands on the
  control, never on `<arena-select>`.
- **There is no `multiple`, and that is a decision rather than an omission.** A multi-selection
  is a *set* of values and `change` carries one `string`, so the member could only ever have set
  an attribute whose result the event could not report. A native multi-select is a list box shown
  open, a different control from the styled dropdown this is.
- **Don't** put more than a handful of options in it. A long or searchable list is
  `arena-command-palette`'s job, and a set of three or four mutually exclusive choices already
  visible on the page is `arena-segmented-control`'s.

**By hand, in real Chromium**: the popup is the browser's and happy-dom has none, so nothing
below is provable by a suite. Run `bun run demos` and open
`/frameworks/angular/components/forms/arena-select/ArenaSelect.demo.generated.html`:
- The popup opens on click and on Space, walks with the arrow keys and type-ahead, and commits on
  Enter, all of it the platform's, none of it Arena's.
- The caret sits inside the field's right padding and swallows no click: pressing it opens the
  control beneath it.
- The focus ring is Arena's `--focus-width` in `--color-secondary`, and the platform outline is
  gone.
- Disabled dims the whole column, label included, and the control refuses the pointer.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-switch/ArenaSwitch.prompt.md -->

Arena switch, an on/off setting that takes effect immediately, not a pending form value.
Standalone, `OnPush`, signal I/O. The host binds the root slot, so `<arena-switch>` is itself
the flex row its parent lays out. The control
is a real `<button type="button" role="switch">`: the platform supplies activation, the role
supplies the state.

```html
<arena-switch label="Auto-deploy on merge" [state]="auto()"
              (funcOn)="auto.set(true)" (funcOff)="auto.set(false)" />

<arena-switch label="Dark theme" [state]="dark()" iconOn="ph-bold ph-moon" iconOff="ph-bold ph-sun"
              (funcOn)="dark.set(true)" (funcOff)="dark.set(false)" />

<arena-switch label="Allow force pushes" confirm [state]="force()"
              (requestChange)="askThenApply()" />

<arena-switch label="Managed by policy" state disabled />
<arena-switch label="Compact rows" size="sm" orientation="vertical" [state]="compact()" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSwitch.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `state` | primitive | `boolean` | `false` | The current on/off value. Controlled: the consumer owns it and pushes it each render. |
| `orientation` | enum | `ArenaOrientation` | `"horizontal"` | Whether the switch lies horizontally or stands vertically. |
| `size` | enum | `ArenaSwitchSize` | `"md"` | The switch's overall size. |
| `iconOn` | primitive | `string` |  | A Phosphor class name for the glyph shown while on. Arena draws the aria-hidden `<i>`. |
| `iconOff` | primitive | `string` |  | A Phosphor class name for the glyph shown while off. |
| `label*` | primitive | `string` |  | The accessible name for the switch, also drawn beside it. |
| `disabled` | primitive | `boolean` | `false` | Whether the switch is inoperable. |
| `confirm` | primitive | `boolean` | `false` | When set, a change is not applied on the fly; it is requested through `requestChange` so the host can confirm it first. |
| `funcOn` | event |  |  | The switch was turned on. |
| `funcOff` | event |  |  | The switch was turned off. |
| `requestChange` | event |  |  | A change was requested while `confirm` is set: the host opens an ArenaConfirmDialog and, on confirmation, flips `state` (the requested value is always the negation of the current one). |

<!-- @api end -->

**Do / Don't**
- It is **controlled**. `state` is what the consumer owns; the component holds no copy, so a
  `funcOn` you ignore is a switch that visibly does not move.
- **`label` is required** and is the accessible name, the `aria-label` on the control and the
  text beside it. There is no unlabelled shape, which is why the input has no default.
- The events are three, and they are directional rather than a single toggle: `funcOn` and
  `funcOff` say which way it went, so a handler needs no copy of the old value to read.
- `confirm` **replaces** the two: nothing is applied, `requestChange` fires instead, and the host
  opens an `ArenaConfirmDialog` and sets `state` itself on confirmation. The requested value is always
  the negation of the current one, so the event carries no payload.
- **`confirm` alone diverts the activation**, never whether anything is listening.
  `confirm` set with no `(requestChange)` binding is a switch that
  does nothing at all. That is the accepted cost of that rule and the one worth paying, because what
  it replaced applied a guarded change silently. **No runtime guard can catch it**: "is anything
  subscribed?" is precisely the question Arena never asks, because at least one framework cannot answer it. The behaviour is
  pinned, so the fallback cannot come back unnoticed.
- `iconOn` and `iconOff` are Phosphor class-name strings drawn inside the knob, and only the
  current state's glyph is in the DOM. They are decoration; the knob is `aria-hidden`, and
  `aria-checked` is what carries the state.
- Use a switch for an immediate effect and `<arena-checkbox>` for a pending form value. A switch
  inside a form that only applies on submit is the wrong control.
- `orientation="vertical"` transposes the track. It exists for a dense sidebar; in a form row it
  reads as a mistake.
- Don't disable a switch to mean "you may not change this yet". A disabled switch is unreachable
  by Tab and announces no reason; `confirm` is the affordance for a change that needs a gate.

**By hand, in real Chromium**: none of these is provable in happy-dom. Run `bun run demos` and
open `/frameworks/angular/components/forms/arena-switch/ArenaSwitch.demo.generated.html`:
- The knob **slides** across the track over `--dur-state`/`--ease-state` rather than jumping, and
  the track's
  colour crossfades with it.
- Under `prefers-reduced-motion: reduce`, forced in DevTools' Rendering pane, **the knob stops
  travelling and the track colour still crossfades**. That is the intended answer for a state
  change: the travel is decorative and the colour is the report. `motion-reduce:transition-none`
  on the `knob` slot is what does it.
- At every size the knob clears the track's padding on both ends, and the vertical transpose
  travels down rather than across.
- The glyph is legible inside the knob at `sm`, which is the size that decides whether per-state
  icons are usable at all.
- Clicking the label toggles; clicking the label of a disabled switch does not.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/forms/arena-textarea/ArenaTextarea.prompt.md -->

Arena multi-line text field, label above, hint or error and an optional counter below.
Standalone, `OnPush`, signal I/O. The host binds the root slot, so `<arena-textarea>` is
itself the column its parent lays out. The control is
a real `<textarea>`, named by a real `<label for>`.

```html
<arena-textarea label="Release notes" [value]="notes()" (change)="notes.set($event)"
                hint="Markdown is supported" [rows]="6" />

<arena-textarea label="Summary" counter [maxLength]="280"
                [value]="summary()" (change)="summary.set($event)" />

<arena-textarea label="Commit message" autoResize
                [value]="message()" (change)="message.set($event)" />

<arena-textarea label="Reason" required [error]="reasonError()"
                [value]="reason()" (change)="reason.set($event)" />
<arena-textarea label="Generated changelog" readOnly [value]="changelog()" />
```

<!-- @api GENERATED from contracts/api/components/ArenaTextarea.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label` | primitive | `string` |  | Field label; the counter and error sit under the field. |
| `id` | primitive | `string` |  | The control's id, and what the label's `for` points at. Generated from `label` when omitted, as `ta-` followed by the label with each run of whitespace replaced by a single hyphen and the whole lowercased: the derivation ArenaInput.id states, under this component's own prefix. |
| `hint` | primitive | `string` |  | A line of help under the field. |
| `error` | primitive | `string` |  | Error message; turns the border crimson and shows below. |
| `required` | primitive | `boolean` | `false` | Marks the label and the control required. |
| `counter` | primitive | `boolean` | `false` | Shows a live length/maxLength count, which warns once the length is STRICTLY past nine tenths of `maxLength`; exactly at the share is not yet near the limit. |
| `autoResize` | primitive | `boolean` | `false` | Grows with the content instead of scrolling. |
| `value` | primitive | `string` |  | The controlled text. |
| `disabled` | primitive | `boolean` | `false` | Blocks editing and dims it. |
| `readOnly` | primitive | `boolean` | `false` | Shows the value but blocks editing. |
| `placeholder` | primitive | `string` |  | Shown when empty. |
| `name` | primitive | `string` |  | Submitted with the form. |
| `maxLength` | primitive | `number` |  | Caps the length; feeds the counter. |
| `rows` | primitive | `number` | `4` | Initial visible rows. |
| `change` | event | `string` |  | Edited; carries the new text. |

<!-- @api end -->

**Do / Don't**
- It is **controlled**, and Angular will not force the DOM back: ignore `change` and the box keeps
  what the user typed. Wire the signal.
- There is **no validator here**, unlike `arena-input`. `error` is the only route to the error
  state, and it is the consumer's to compute, which is why the field has two state arms rather
  than three and there is no valid (green check) state at all.
- The counter needs **both** `counter` and `maxLength`. A `maxLength` alone caps the field; it
  does not ask for the count to be shown. Past nine tenths of the cap the counter switches to the
  warning slot, a different slot, not a variant, which is why Arena draws two.
- `autoResize` forces `resize: none` and grows the box from its own `scrollHeight`.
  **It resizes on mount and on every programmatic change, not only while typing**, through an
  `afterRenderEffect` that reads `value()`, so a draft loaded from a server or a template
  inserted by a button sizes the box immediately. **`scrollHeight` is content plus padding and never the border**, so a
  border-box element needs `offsetHeight - clientHeight` added or the box lands short and keeps a
  permanent scrollbar: measured before the fix at 720x340, `scrollHeight` 199 set as the height
  left `clientHeight` 197 and a scrollbar on a box just grown past it. Both layers carry the term,
  and no suite can see it, because happy-dom has no layout and reports `scrollHeight` as `0`.
- `rows` is the *initial* height and still applies under `autoResize`; it is what the box is
  before it has content to measure.
- `required` and `readOnly` land on the native attributes rather than on `aria-required` and
  `aria-readonly`; a native control already reports both, and writing them twice is two claims
  that can disagree. `aria-multiline` is likewise absent on purpose: a `<textarea>` is multiline
  by being one.
- `change` is an output named after a native DOM event, so the control calls `stopPropagation()`
  on the native `change` and a commit does not read as a second edit. Bind on the
  `<arena-textarea>` itself; the native event never reaches an ancestor.
- The error line **replaces** the hint. The foot keeps an empty placeholder when there is neither,
  so the counter stays hard right instead of sliding under the label.
- `id` is derived from `label` as `ta-<slug>`, the derivation `ArenaTextarea.json` states. Note the
  prefix differs from `arena-input`'s `in-`, so the two never collide on a form that labels
  both the same.

**By hand, in real Chromium**: none of these is provable in happy-dom, and the first one cannot
be: happy-dom has no layout, so `scrollHeight` is `0` and a growing box and a broken one look
identical to any suite. Run `bun run demos` and open
`/frameworks/angular/components/forms/arena-textarea/ArenaTextarea.demo.generated.html`:
- **`autoResize`**: the box grows line by line as you type and shrinks again when you delete, with
  no scrollbar ever appearing. The one seeded with a long value is already tall on load; that is
  the `afterRenderEffect` at work: the box is sized before the first paint, not on first keystroke.
- Without `autoResize` the grip in the corner resizes vertically and not horizontally.
- The gold focus ring lands on the textarea itself, where `arena-input`'s lands on a wrapping
  group.
- The counter turns amber between 90% and 100% of the cap, and the field stops accepting input at
  the cap because `maxlength` is native.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-board-column/ArenaBoardColumn.prompt.md -->

One column of an `arena-board`: a named head with a count and a control, the stack of whatever you
project into it, and a footer for the one action that adds to it. Standalone, `OnPush`, signal
inputs. The host steps out of layout and the component renders the real `<section>`, so the column
is a cell of the board's grid rather than an element between the two.

```html
<arena-board-column title="In progress" [count]="3" summary="13 pts" [colorId]="1">
  <arena-icon-button action icon="ph-bold ph-dots-three" label="In progress options" size="sm" />
  @for (task of tasks(); track task.id) {
    <app-task-card [task]="task" />
  }
  <arena-button footer variant="ghost" size="sm" icon="ph-bold ph-plus">Add task</arena-button>
</arena-board-column>
```

The head's control is projected with the `action` marker and the footer's with `footer`;
everything else you project is the stack. `count` is passed rather than counted, because Arena
never decides what it draws from what you projected: one of those children may be a placeholder
and none of them is Arena's to read.

<!-- @api GENERATED from contracts/api/components/ArenaBoardColumn.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title*` | primitive | `string` |  | What this column is: a status, a stage, a person, a day. It is the head's text and the column's accessible name at once. Required and guarded at runtime rather than defaulted, because a column of a board is only ever read by what it groups, and an unnamed one is a pile. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h3"` | Which rung of the document outline the head's text takes. Only the element changes: its class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h3`, the card rung of the title ladder, because a board sits inside the region a section names and a column sits inside the board. The column's accessible name is separate and is unaffected, since it is the group's own and is carried whatever the head is drawn as. `none` is refused at runtime, the rule every component whose `title` is required follows: a title required because it names the thing it draws cannot also be told that the name is not one. |
| `count` | primitive | `number` |  | How many things are in the column, drawn beside the title in the numeric register. It is passed rather than counted, because Arena never derives what it draws from what a consumer projected: the column holds the consumer's own elements, one of which may be a placeholder and none of which Arena can read. |
| `summary` | primitive | `string` |  | One line under the head: the total the column adds up to, an estimate, a limit. A string rather than a number because the unit travels with it, and a column reading "19 pts" is one value and not two. |
| `colorId` | enum | `ArenaCatSlot` |  | An identity colour for the column, from the same categorical ramp ArenaTag and the charts read, so a status keeps its colour between a board, a table and a chart. It inks the head's mark and reaches the column as a custom property, `--arena-board-column-cat`, so an appearance that fills the whole head with it is a style plugin's to write and needs no member here. |
| `action` | slot |  |  | One control in the head: a menu, a filter, an add. It sits after the count, and the column draws nothing for it beyond the space it takes. |
| `content` | slot |  |  | The cards, stacked in order. Arena draws none of them: a board's card carries the product's own fields, so what is left once they are removed is the stack, which is what this draws. |
| `footer` | slot |  |  | The action that adds to this column, under the stack, where a board puts it because a new card lands at the bottom. Optional, and a column with none simply ends at its last card. |

<!-- @api end -->

**Do / Don't**
- **Do** bind the numbers, `[count]="3"` and `[colorId]="1"`, rather than writing them as bare
  attributes: both take a number and an unbound attribute hands them the string.
- **Do** give the same entity the same `colorId` everywhere: a status that is slot 3 on the board
  and slot 3 in the chart beside it is one thing said twice, which is what the ramp is for.
- **Do** put the add action in `footer`, not in the head. A new card lands at the bottom.
- **Don't** count the projected children yourself. Pass `count` from the same data you looped
  over, or the number and the stack drift the first time one of them is filtered.
- **Don't** use a column outside a board: it is a cell of that grid and takes its width from it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-board/ArenaBoard.prompt.md -->

The frame of a board: columns side by side, sharing the room equally and never narrower than
`minColumn`, scrolling sideways once they no longer fit. Standalone, `OnPush`, signal inputs. The
host IS the board, so it carries the group role, the name and the tab stop that make a scrolling
region reachable by keyboard at all.

```html
<arena-board label="Sprint 32 tasks by status">
  @for (status of statuses(); track status) {
    <arena-board-column [title]="status" [count]="byStatus()[status].length" [colorId]="slot(status)">
      <arena-icon-button action icon="ph-bold ph-plus" [label]="'Add to ' + status" size="sm" />
      @for (task of byStatus()[status]; track task.id) {
        <app-task-card [task]="task" />
      }
      <arena-button footer variant="ghost" size="sm" icon="ph-bold ph-plus">New</arena-button>
    </arena-board-column>
  }
</arena-board>
```

**The cards are yours.** A board's card carries the product's own fields, so Arena draws the
frame, the column and its head, and stops. **Nothing moves**: there is no drag and drop here, and
what a card does when it is picked up is a question about your data rather than about this frame.

<!-- @api GENERATED from contracts/api/components/ArenaBoard.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the board to assistive technology: what the columns are columns OF. "Sprint 32 tasks by status", never "Board". Required and guarded at runtime after trimming, the shape ArenaScroller.label carries for the same reason, since a group announced as a group tells a reader that focus moved and nothing about where it landed. |
| `content*` | slot |  |  | The columns, one ArenaBoardColumn each. Required and guarded at runtime: a board with no columns is a tab stop over nothing, which is the dead stop a component with a group role must not ship. |
| `minColumn` | primitive | `string` | `"var(--grid-min)"` | The narrowest a column may be before the board scrolls rather than squeezing. Columns share the room equally above it, so a board of four fills the width it is given and a board of twelve scrolls. It is a length rather than a step on the spacing scale, for the reason ArenaGrid.min is one: this is page geometry and the spacing scale models rhythm. The default is the same role a grid's cell reads, so a card is one width across a wall, a rail and a board. |

<!-- @api end -->

**Do / Don't**
- **Do** say what the columns are columns OF in `label`. It is the name a keyboard user lands on,
  and "Board" tells them nothing.
- **Do** leave `minColumn` alone unless a card needs more room than a grid cell: the default is
  the same width a card takes in a grid or a rail.
- **Don't** wrap it in a scroll container of your own. The board is the scrolling region, and a
  second one around it takes the keyboard's scroll away from the one that announces itself.
- **Don't** use it for a fixed set of panels that always fit. That is `arena-grid`, which wraps
  rather than scrolling.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-board/ArenaBoard.demo.generated.html`:
- Tab reaches the board itself, the ring lands on the whole frame, and the arrow keys scroll it.
- Columns share the width while they fit and stop at `minColumn`, after which the board scrolls.
- A column is as tall as its own stack: they do not stretch to match the tallest.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-figure/ArenaFigure.prompt.md -->

Arena figure, a framed piece of media with an optional caption. Standalone, `OnPush`, signal I/O.
The host takes itself out of layout with `display: contents` and the real `<figure>` is inside,
because a `<figcaption>` outside a `<figure>` is associated with nothing.

```html
<arena-figure [caption]="lot.farm + ', ' + lot.altitude + ' m'">
  <img media [src]="lot.image" [alt]="lot.farm + ', ' + lot.region" />
  <i fallback class="ph-bold ph-coffee-bean" aria-hidden="true"></i>
</arena-figure>
```

<!-- @api GENERATED from contracts/api/components/ArenaFigure.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `media` | slot |  |  | The picture itself, as the element you wrote: an img, a video, a canvas. It is clipped to the frame and meets its edges the way the style plugin says, which is why nothing here takes a source or an alternative text. Those belong to your element, and an image's alternative is editorial in a way nothing can derive. |
| `fallback` | slot |  |  | What the frame shows when there is no media, drawn centred and at rest rather than as an error: an icon standing for a category, a monogram, a shape. Absent along with media, the frame is an empty box of the right shape, which is what a loading wall wants. |
| `overlay` | slot |  |  | Content laid over the media, on the wash the overlay role paints, so a mark or a line of text stays readable against a picture nobody chose. It is inside the frame and the caption is under it, which is the whole difference between the two. |
| `caption` | primitive | `string` |  | A line under the frame, rendered as a real figcaption inside a real figure, so the association is the platform's rather than a class name's. Absent, the figure renders no caption element at all rather than an empty one. |
| `ratio` | primitive | `string` | `"var(--aspect-media)"` | The shape of the frame, as a CSS aspect ratio. The default is the role, so a style plugin answers it for every figure at once and a shop crops portrait where a gallery tiles square. Give it a value outright for the figure whose shape is not the plugin's to decide: a video is sixteen by nine whatever the page sounds like. |

<!-- @api end -->

**The three slots are attributes**, `media`, `fallback` and `overlay`, projected through the marker
directives every Arena component with named slots uses.

**Nothing here takes a source or an alternative text**, and that is the point. The picture is the
element you wrote, so `src`, `srcset`, `loading` and `alt` stay where the platform already asks for
them. An image's alternative is editorial: it says what the picture means on this page, which
nothing can derive from a file name.

**`ratio` defaults to the role.** A style plugin answers the shape of every figure at once, so a shop
crops portrait where a gallery tiles square, and the same markup follows. Pass a value outright
only for the figure whose shape is not the plugin's to decide, such as a video.

**`fallback` is a state and not an error.** It draws centred and at rest when there is no media.
With neither media nor fallback the frame is an empty box of the right shape, which is what a
loading wall wants.

**Do / Don't**
- **Do** put the alternative text on your own `<img>`, and leave it empty when the figure is
  decorative and the caption already says everything.
- **Do** remember the host carries no box. Put your layout on the element around it, which is the
  same rule every `display: contents` primitive in this package carries.
- **Don't** wrap it in a box of your own to size it. It fills the column it is in and takes its
  shape from `ratio`.
- **Don't** put a control in the overlay and expect it to be reachable before the caption. It is
  in the frame, which comes first in the reading order.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-figure/ArenaFigure.demo.generated.html`:
- The frame keeps its shape as the column narrows, and the picture crops rather than squashing.
- With no media, the fallback sits centred and reads as a placeholder rather than as an error.
- The overlay stays legible over the wash in both themes.
- With a screen reader running, the caption is announced with the figure and not as a stray line.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-grid/ArenaGrid.prompt.md -->

Arena grid, the one that picks its own column count from the room it is in so nobody has to pick a
breakpoint. Standalone, `OnPush`, signal I/O. The host **is** the grid, so `<arena-grid>` is the
element you place.

```html
<arena-grid gap="md">
  <arena-stat-card label="Open orders" [value]="open()" />
  <arena-stat-card label="Overdue" [value]="overdue()" tone="danger" />
  <arena-stat-card label="Collected today" [value]="collected()" />
</arena-grid>
```

<!-- @api GENERATED from contracts/api/components/ArenaGrid.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `min` | primitive | `string` | `"var(--grid-min)"` | The narrowest a cell may be before the count drops. It is the one number this component takes and it is page geometry rather than a step on the spacing scale, which models rhythm and not the width of a card. It is clamped against the container, so a minimum wider than the room available yields one full-width column instead of overflowing it. The default is a role rather than the arithmetic it used to spell, so a style plugin can answer how many cards a viewport shows: a gallery wants a dense wall and a ledger wants a wide column, from the same markup. |
| `gap` | enum | `ArenaGridGap` | `"md"` | The air between cells, on both axes. Named steps rather than a length, because rhythm is what the spacing scale is for and a grid is where a hand-picked one shows worst. Its steps are the page rhythm scale itself, so sm groups related cells, md sets two peers apart and lg reads as two sections, and none closes the gap entirely; a grid is that rhythm plus a grid, and nothing here is a number this component chose. |
| `maxWidth` | primitive | `string` |  | A ceiling on the grid's own width, centred in whatever contains it. Absent, it fills its container, which is what a grid nested inside a page should do; a page's own reading width is what this is for. |
| `content` | slot |  |  | The cells, one per child. Nothing is wrapped and nothing is measured: a child is a grid item exactly as it was written, so a card, a chart or a definition list all lay out the same way. |

<!-- @api end -->

**It replaces a hand-written column list, not a `minmax(0, 1fr)` in one.** A fixed column count
needs a threshold, and a threshold is a number somebody invented: six filter bars written by hand
end up with three different ones and none of them matches `--bp-*`. Here the floor is `min` and it
is clamped with `min(<min>, 100%)`, so a minimum wider than the container gives one full-width
column rather than an overflow. **This is also the answer to a media query in a `styles:` block**,
which cannot read a `var()` and so has to restate a threshold Arena already holds.

`gap` is four named steps, `none`, `sm`, `md`, `lg`, and not a length. Rhythm is what the spacing
scale is for, and a grid is where a hand-picked gap shows worst: two grids on one page with gaps a
step apart read as a mistake.

`maxWidth` caps the grid and centres it. Leave it off inside a page and set it on the one grid that
is the page's own reading width.

**Do / Don't**
- **Do** give it real children. Every child is one cell exactly as written; nothing is wrapped, so
  an `arena-card`, a chart and a definition list all land the same way.
- **Do** reach for it for a page's own layout. A component that has to fit the room it was given
  measures its container with `arenaContainerWidth`, which is a different question.
- **Don't** use it for a row of two or three controls. That is a flex row, and a grid there gives
  every control the same width whether or not that helps.
- **Don't** put a `min` on it that no card ever reaches. The count only drops when the room runs
  out, so a minimum nobody meets pins the grid at one column forever.
- **Don't** nest one to make a two-level layout. Two grids nested pick their counts independently
  and the cells stop lining up; give the outer one the cells it actually has.
- **Don't** wait for a fixed column count. A photo wall three across and a pair of lesson choices
  are both `grid-template-columns: repeat(N, 1fr)` on an element of your own, one line each, and a
  count Arena took would contradict what this component is: the number comes from the room rather
  than from a breakpoint somebody picked. Two products measured wanting one, and neither would
  have written less than the line they wrote.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-grid/ArenaGrid.demo.generated.html`:
- Narrow the window from wide to 390px: the count falls one step at a time and never overflows.
- At the narrowest, one column fills the width; the minimum is clamped rather than honoured.
- The four gaps are visibly four steps, and both axes get the same one.
- With a `maxWidth` set, the grid centres and stops growing; without one, it fills.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-hero/ArenaHero.prompt.md -->

Arena hero, the opening of a landing page. Standalone, `OnPush`, signal I/O. The host **is** the
hero, so `<arena-hero>` is the element you place. Its title takes the hero register, the top rung
of the title ladder and the only one above a page head.

```html
<arena-hero eyebrow="Single origin" title="Coffee that tells you where it grew"
  lede="Every lot is traceable to the farm, the altitude and the week it was picked.">
  <div actions>
    <arena-button variant="primary" size="lg" icon="ph-bold ph-storefront">Shop the lots</arena-button>
    <arena-button variant="ghost" size="lg" iconRight="ph-bold ph-arrow-right">How we buy</arena-button>
  </div>
  <arena-figure figure>
    <i fallback class="ph-bold ph-mountains" aria-hidden="true"></i>
  </arena-figure>
</arena-hero>
```

<!-- @api GENERATED from contracts/api/components/ArenaHero.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title*` | primitive | `string` |  | The one line the page is built around. Required, and guarded at runtime after trimming: a hero is that line plus its setting, and a hero without it is a figure with buttons under it. The guard trims first because the value it exists to catch is a present and useless one, not an absent one, which the type already refuses. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h1"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h1` because a hero opens the page it sits on and a landing page carries no other title. A page carrying a hero AND a page head has two candidates for one rung, and the ladder settles which yields rather than the markup order: the hero is the rung above, so it keeps the `h1` and the page head is what steps down. Nothing here reads the page to work that out, because what a component renders is never derived from what sits above it. `none` is refused at runtime, the rule every component whose `title` is required follows: a title required because it names the thing it draws cannot also be told that the name is not one. |
| `eyebrow` | primitive | `string` |  | A line above the title saying what kind of page this is. Same register as every other eyebrow in the system, so a style plugin that takes them out of the console's mono capitals takes this one with them. |
| `lede` | primitive | `string` |  | The paragraph under the title, held to a reading width rather than to the column's, because a line that runs the whole width of a hero loses its return sweep. Named lede and not description, since this is the sentence that carries the page and not a note about the heading. |
| `actions` | slot |  |  | What the page asks the reader to do, in a wrapping row under the lede. Arena draws the row; the consumer draws what sits in it, and one primary action beside one secondary is the shape this is sized for. |
| `figure` | slot |  |  | The picture, the mark or the shape beside the words, or behind them under the bleed layout. It is a slot rather than a source, so an ArenaFigure, an illustration or a single glyph all land the same way. |
| `layout` | enum | `ArenaHeroLayout` | `"split"` | How the words sit against the figure. Split puts them side by side and falls to one column when the room runs out, with no breakpoint deciding when; stacked keeps them in one column at every width, for a hero whose figure is a band rather than a partner; bleed lays the words on the figure, over the wash the media overlay role paints, which is the arrangement that needs that role to be readable. |
| `align` | enum | `ArenaHeroAlign` | `"start"` | Whether the words run from the start edge or are centred in their column. Centred is what a bleed hero usually wants and a split one usually does not, and it is a separate decision from the layout because a stacked hero can want either. |

<!-- @api end -->

**The two slots are attributes**, `actions` and `figure`, projected through the marker directives.
The actions slot takes one element, so wrap your buttons in a container of your own if there is
more than one.

**`split` falls to one column with no breakpoint deciding when.** The threshold is derived from
`--grid-min`, the role that already answers how narrow a card may get, so a style plugin that widens the
grid minimum widens when a hero splits: one decision about how dense a page is rather than two
that can disagree.

**`bleed` lays the words on the figure**, which is the arrangement that makes the media overlay
role load-bearing. Give the figure something that fills its box, and give the words
`align="center"` unless the picture has an empty corner they can sit in.

**It claims no `banner` landmark.** Banner is the site header, one per page, and a hero is content
inside the main region rather than the furniture around it. The heading is what a reader navigates
to.

**A page carrying a hero and a page head has two candidates for one `h1`, and the ladder says
which yields.** The hero is the rung above, so it keeps the `h1` and the page head takes
`headingLevel="h2"`. Neither component reads the page to work that out, because what an Arena
component renders never follows from what sits above it, so the screen that carries both is the
screen that has to say so. On its own the hero is right as it stands.

**Do / Don't**
- **Do** keep the lede to a sentence or two. It is held to a reading width rather than the
  column's, because a line that runs the whole width of a hero loses its return sweep.
- **Do** put one primary action beside one secondary. The row is sized for that shape.
- **Don't** leave a second `h1` on the page. The hero already opened it, so the page head beside
  it steps down and anything you write of your own starts at `h2`.
- **Don't** reach for `bleed` over a photograph with detail where the words go. The wash keeps
  text readable; it does not make a busy picture quiet.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-hero/ArenaHero.demo.generated.html`:
- Narrow the window from wide: the split falls to one column at one step and never overflows.
- Under `bleed`, the words stay readable over the wash in both themes.
- Under `align="center"` the whole column centres, including the actions row.
- With a screen reader running, the title is announced as a level one and the hero announces no
  landmark of its own.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-main/ArenaMain.prompt.md -->

Arena main, the page's principal landmark and nothing else. Standalone, `OnPush`. The host is
taken out of layout with `display: contents`, so the `<main>` inside it is what a parent lays out
and `<arena-main>` itself occupies nothing.

```html
<arena-skip-link label="Skip to content" />
<app-header />
<arena-main>
  <router-outlet />
</arena-main>
```

<!-- @api GENERATED from contracts/api/components/ArenaMain.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | What the page is for, once the furniture around it is taken away. It is optional and unguarded rather than required: a router that has not resolved its route yet renders nothing, and a landmark that threw during that frame would fail on the ordinary case rather than on a mistake. |

<!-- @api end -->

**It draws no box, and that is the whole design.** The recipe carries one declaration, `display:
block`, which is what a `<main>` already is. No width, no padding, no grid, no maximum: a page
whose main landmark is swapped for a plain `<div>` looks identical. Where things go stays the
container you own, which is what `PACKAGE.md` says and what this deliberately does not reopen.
What it says is only what the region IS.

**`.arena-shell__main` goes on a `<div>` around it, never on the component.** A shell whose growing
child should be the main region cannot hand its slack to this: the host is out of layout and the
`<main>` inside is Arena's element rather than yours, so there is no element here for the class to
land on. Wrap it, put the class on the wrapper, and the shell has a child that can take the slack.
Omitting the class because the component refuses it is the shape that gets shipped, and it reads
as a footer floating halfway up a short page.

**One per page.** A landmark that appears twice is two answers to "where does the content start",
and a reader jumping by landmark gets the first one. It carries no name for the same reason
`arena-app-bar` carries none and `arena-side-nav` requires one: a page has one main and a reader
reaches it by its role, while a page has several navs and each needs saying which.

**It is focusable programmatically, and that is not decoration.** The `<main>` takes
`tabindex="-1"`, which keeps it out of the tab order and lets focus be sent to it. An anchor
pointing at a container the platform will not focus scrolls the page and leaves focus exactly
where it was, so the next Tab continues from the nav the reader was trying to escape. That is the
failure that makes most skip links look like they work, and it is why the requirement sits on the
landmark rather than on the link.

**Its id is a constant Arena writes, `arena-main`.** Nothing is coordinated at the call site
because a page has one main: `arena-skip-link` points at that id and this writes it. Write your
own anchor against the same id if you need a second route in.

**Do / Don't**
- **Do** put it around the routed content, not around the shell. A `<main>` that contains the
  header and the nav names the whole page, which names nothing.
- **Do** give it the layout it needs from the container around it, or from an `arena-grid` inside.
- **Don't** reach for it as a wrapper for a section of a page. That is `arena-section`, which
  names a region and draws the heading for it.
- **Don't** write a second one for a route that renders inside another. The landmark is the
  shell's, once.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-main/ArenaMain.demo.generated.html`:
- The page looks the same with the component and with a plain `<div>` in its place.
- The accessibility pane shows one `main` landmark.
- Clicking a link to `#arena-main` moves focus into the region, which the focus ring on the next
  Tab is what proves: focus continues from inside the main rather than from the nav.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-scroller-item/ArenaScrollerItem.prompt.md -->

Arena scroller item, one cell of an `arena-scroller`: the box that carries the width the row
decided and the point the row settles on. Standalone, `OnPush`. The host **is** the cell.

```html
<arena-scroller label="Recently landed lots" itemWidth="calc(var(--sp-1) * 62)">
  @for (lot of arrivals(); track lot.id) {
    <arena-scroller-item><app-lot-card [lot]="lot" /></arena-scroller-item>
  }
</arena-scroller>
```

<!-- @api GENERATED from contracts/api/components/ArenaScrollerItem.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | What the cell holds, exactly as it was written. The item draws no surface, no line and no padding: it is a width and a snap point, and everything visible inside it is the consumer's or another component's. |

<!-- @api end -->

**Why the cell is a component rather than a rule on the row's children.** A row cannot reach
inside its children to size them, so the width has to land on the child itself. Several Arena
components take their host out of layout with `display: contents`, so a rule aimed at the row's
direct children lands on an element with no box, and whether it lands at all then depends on
which component the caller put in the row, with every gate green. The item is the box that is
always there, and its own host carries a real one.

**It draws nothing.** No surface, no line, no padding: a width and a snap point. Whatever is
visible in the cell came from what you projected into it.

**Do / Don't**
- **Do** put one per item, and let the card, the tile or the figure sit inside it.
- **Don't** set the width here. The row owns it, through `itemWidth`, so a rail of cells is one
  decision rather than one per cell.
- **Don't** reach for it outside an `arena-scroller`. Outside a row it is a box that reads a
  property nothing set.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-scroller-item/ArenaScrollerItem.demo.generated.html`:
- The cell is exactly as wide as the row's `itemWidth`, whatever it contains.
- Every cell is the same width and the same height, whatever component sits inside it.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-scroller/ArenaScroller.prompt.md -->

Arena scroller, the honest carousel: a row that scrolls, with no arrows pretending to be a
slideshow. Standalone, `OnPush`, signal I/O. The host **is** the scrolling region, so
`<arena-scroller>` is the element you place, and it is one tab stop with a group role and a name.

```html
<arena-scroller label="Recently landed lots" itemWidth="calc(var(--sp-1) * 62)">
  @for (lot of arrivals(); track lot.id) { <app-lot-card [lot]="lot" /> }
</arena-scroller>
```

<!-- @api GENERATED from contracts/api/components/ArenaScroller.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the row to assistive technology, and nothing else supplies it: a group announced as a group tells a reader that focus moved and nothing about where it landed. Required, and guarded at runtime after trimming, the shape ArenaTable.label carries for the same reason, since the value the guard exists to catch is a present and useless one. |
| `content*` | slot |  |  | The items in the row, one per child. Nothing is wrapped: a child is laid out exactly as it was written, at the width itemWidth names. Required, and guarded at runtime: an empty row is a tab stop over nothing, which is the dead stop a component with a group role must not ship. |
| `itemWidth` | primitive | `string` | `"var(--grid-min)"` | How wide each item is laid out, which a rail has to answer and a grid answers with the same role: the width of a card is one decision, and a wall of them and a row of them should not disagree about it. It is a length rather than a step on the spacing scale, for the reason ArenaGrid.min is one, and it reaches the children as a custom property because a row sets its items' width and cannot reach inside them. |
| `behaviour` | enum | `ArenaScrollerBehaviour` | `"snap"` | Whether the row settles on an item or wherever it was left. Snap by default, because a rail of equal-width cards left halfway across one is a card the reader has to finish scrolling by hand. Nothing moves on its own under either value, so neither answers prefers-reduced-motion and no pause control is owed. |

<!-- @api end -->

**Nothing moves on its own.** `snap` and `flow` both describe where a scroll SETTLES, not anything
that animates: `snap` lands on an item, `flow` lands wherever the reader left it. That is why no
pause control is owed under WCAG 2.2.2 and why `prefers-reduced-motion` has nothing to answer here.

**`itemWidth` reaches the children as a custom property on the host**, because a row sets its
items' width and cannot reach inside them. Every child is laid out at that width exactly as it was
written; nothing is wrapped. Its default is `--grid-min`, the same role `arena-grid` reads, so a
wall of cards and a row of the same cards agree about how wide a card is and a style plugin re-answers
both at once.

**`label` is required and guarded after trimming.** Focus lands on the row itself, and a group
announced as a group tells a reader that focus moved and nothing about where. The content slot is
required and guarded too: an empty row is a tab stop over nothing, and the guard runs once the
projected content is there rather than at construction, which is the only moment it can be counted.

**Do / Don't**
- **Do** give it a label that says what the row holds, not what it is. "Recently landed lots" is a
  name; "Scrolling row" is the role read twice.
- **Do** leave `itemWidth` alone unless the row genuinely wants a different card from the page's
  grid. The role is there so the two agree.
- **Don't** reach for it when everything fits. A scroll container that never scrolls is a tab stop
  the reader gains nothing from.
- **Don't** wrap the children in cells of your own to set their width. That is what `itemWidth` is,
  and a wrapper puts a box between the row and the card it is laying out.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-scroller/ArenaScroller.demo.generated.html`:
- Tab into the row: it takes focus as one stop, shows the focus ring, and the arrow keys scroll it.
- Under `snap`, releasing a drag mid-item settles on an item edge; under `flow` it stays put.
- Every child is the same width whatever it contains.
- With a screen reader running, focus on the row announces the label rather than the word group
  alone.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-section/ArenaSection.prompt.md -->

Arena section, a named region of a page: a heading, what sits around it, and the group it names.
Standalone, `OnPush`, signal I/O. The host **is** the section, so `<arena-section>` is the element
you place. It is the middle rung of the title ladder, under a page head and over a card.

```html
<arena-section eyebrow="This week" title="Landed recently"
  description="Everything that cleared customs since Monday.">
  <arena-button action variant="ghost" iconRight="ph-bold ph-arrow-right">See all</arena-button>
  <arena-grid>
    @for (lot of lots(); track lot.id) { <app-lot-card [lot]="lot" /> }
  </arena-grid>
</arena-section>
```

<!-- @api GENERATED from contracts/api/components/ArenaSection.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title*` | primitive | `string` |  | Names the region, both on screen and to assistive technology. Required, and guarded at runtime after trimming: a section is a heading over a group, and one with no heading is a stack, which css/rhythm.css already ships as a class. The guard trims first because the value it exists to catch is a present and useless one, not an absent one, which the type already refuses. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h2"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h2` because the section register is already a step under a page's title and a step over a card's, and this is that register said as structure rather than as a size. `none` is refused at runtime, the rule every component whose `title` is required follows: a title required because it names the thing it draws cannot also be told that the name is not one. |
| `content*` | slot |  |  | What the region holds. Required, and guarded at runtime: a section renders a heading naming a group, so a childless one renders a label for nothing. The guard counts the way the render path counts, so a child that is a false conditional counts as absent rather than as one. |
| `eyebrow` | primitive | `string` |  | A line above the title saying which part of the page this is. Same register as every other eyebrow in the system, so a style plugin that takes them out of the console's mono capitals takes this one with them. |
| `description` | primitive | `string` |  | A line under the title, in the muted ink. It sits below the head row rather than beside the title, because a sentence and an action competing for the same row is what makes a head wrap on a narrow screen. |
| `action` | slot |  |  | Trailing content in the head row, aligned to the end and to the title's own baseline. Arena draws the row; the consumer draws what sits in it. A link that leads to the whole of what the section shows a slice of is the ordinary case. |
| `rhythm` | enum | `ArenaSectionRhythm` | `"md"` | How far the head stands from the body. The steps are the page rhythm scale itself, so sm reads as one unit, md as a head over its own content and lg as a head over a region of the page, and none closes the distance entirely for a section whose body carries its own top edge. Nothing here is a number this component chose. |

<!-- @api end -->

**`title` and the content slot are both required, and both are guarded at runtime.** A section is a
heading over a group: with no heading it is a stack, which `css/rhythm.css` already ships as
`.arena-stack`, and with no children the heading names nothing. The title guard trims first,
because the value it exists to catch is a present and useless one rather than an absent one.

**The action slot is the `action` attribute**, projected through the marker directive every Arena
component with a trailing slot uses. Anything else you write lands in the body.

**The host is a plain section element and claims no landmark.** A section becomes a `region` in the
accessibility tree only once it has an accessible name, and a page where every section announced
itself would bury the two or three landmarks that matter. The heading is the structure a reader
navigates by, and it is the platform's own.

**A section nests, and `headingLevel` is how.** The default is `h2`, which is the section rung of
the title ladder and the right answer directly under a page head. A section inside another section
takes `headingLevel="h3"`, and so does the card register under it, or a reader walking headings
meets peers where the page holds a hierarchy. Nothing on screen moves with the value: the title's
class is the same at every rung, so the register a style plugin sets is untouched by the level the
outline takes. `none` is refused here, since a section is a heading over a group.

`rhythm` is the distance from the head to the body, in the same three named steps the page rhythm
scale carries, plus `none`. It is not the air between one section and the next: Arena draws no
outer margin on anything, so that stays yours to place with `.arena-stack--section`.

**Do / Don't**
- **Do** let `description` carry the sentence. Putting it in the action slot puts prose in a row
  sized for controls, and that row is what wraps first on a narrow screen.
- **Do** nest a section inside a page that already has an `arena-page-head`. The two registers are
  a step apart on purpose, and a style plugin moves them together.
- **Don't** reach for it when there is no title. That is `.arena-stack`, and the guard says so.
- **Don't** open a heading of your own inside the body at the level this one took. The section
  already opened one, and a reader walking headings will read two peers where there is one region.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-section/ArenaSection.demo.generated.html`:
- The eyebrow, the title and the description read as three registers and not as three sizes.
- The action sits on the title's own baseline, and drops under it rather than squeezing when the
  head runs out of room.
- The four rhythm steps are visibly four distances between the head and the body.
- With a screen reader running, the heading is announced as a level two, a section set to `h3`
  announces as a level three, and the section announces no landmark of its own at either.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-site-footer/ArenaSiteFooter.prompt.md -->

Arena site footer, the band across the bottom of every screen. Standalone, `OnPush`, signal I/O.
The host takes itself out of layout with `display: contents` and the real `<footer>` is inside,
because a contentinfo landmark has to be that element.

```html
<arena-site-footer note="© 2026 Meridian Roasters. Roasted in Bilbao.">
  <div>
    <arena-app-logo size="sm" name="Meridian" />
    <p>Single origin, traceable to the farm.</p>
  </div>
  <div>
    <h2>Shop</h2>
    <ul>@for (l of shopLinks(); track l.href) { <li><a [routerLink]="l.href">{{ l.label }}</a></li> }</ul>
  </div>
</arena-site-footer>
```

<!-- @api GENERATED from contracts/api/components/ArenaSiteFooter.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The columns, one per child, laid out by a grid that decides its own count from the room it is given rather than from a breakpoint anyone picked. A column of links, a signup, an address and a mark all land the same way. |
| `note` | primitive | `string` |  | The line under the columns, in the muted ink: the licence, the year, the company. Absent, the footer renders no line at all rather than an empty one. |

<!-- @api end -->

**One child is one column**, and the count comes from the room rather than from a breakpoint anyone
picked, the same way `arena-grid` decides its own. Nothing is wrapped: a column of links, a signup
form and an address all land as they were written.

**The band matches the bar at the top.** The fill and the hairline run edge to edge and the
contents stop at the page width, so the two ends of a page line up with each other.

**Do / Don't**
- **Do** give each column its own heading. A list of links with no name is a list a reader has to
  read to identify.
- **Do** put the licence and the year in `note`. It renders nothing at all when absent.
- **Don't** put a second `<footer>` at the top level of the page. Contentinfo is one per page.
- **Don't** reach for it as a card's footer. That is a slot on the card, and a `<footer>` inside a
  section is not this landmark.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-site-footer/ArenaSiteFooter.demo.generated.html`:
- Narrow the window: the column count falls one step at a time and never overflows.
- The note sits under the columns and takes the muted ink in both themes.
- The band lines up with the content above it at every width.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/layout/arena-skip-link/ArenaSkipLink.prompt.md -->

Arena skip link, the one control on a page that exists for a keyboard alone: it lets a reader step
over everything repeated on every screen and land in the content. Standalone, `OnPush`, signal I/O.
The host is taken out of layout with `display: contents`, so the anchor inside it is what the page
sees and `<arena-skip-link>` itself occupies nothing.

```html
<arena-skip-link label="Skip to content" />
<app-header />
<arena-side-nav ariaLabel="Sections">…</arena-side-nav>
<arena-main>
  <router-outlet />
</arena-main>
```

<!-- @api GENERATED from contracts/api/components/ArenaSkipLink.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | The words a reader reads when the link appears. Required, and guarded at runtime after trimming, the shape ArenaSideNav.ariaLabel carries for the same reason: this is text a person reads and nothing can derive it, and the guard trims first because the value it exists to catch is a present and useless one rather than an absent one, which the type already refuses. There is a defensible default in English and it is deliberately not given, because a default in one language is a wrong answer everywhere else and it is wrong silently. |

<!-- @api end -->

**Place it first, above everything it exists to skip.** That is the one of the four details it
cannot do for itself, and it is the one that decides whether the link works at all: tab order
follows the document, so a skip link written under a nav of nine destinations is reached on the
tenth Tab, by which point the reader has already been through everything the link was going to
save them. Write it as the first element of the shell.

**The other three are Arena's.** It is invisible until it takes focus and visible the moment it
does, through opacity rather than through mounting, so it is reachable by Tab at every moment and
nothing appears or disappears from the tree. It is fixed at the top of the page, on the layering
slot directly above `nav`, because a link that lands under a sticky header is a link nobody can
read. And the region it points at is focusable programmatically, which `arena-main` carries: an
anchor pointing at a container the platform will not focus scrolls the page and leaves focus
behind.

**It points at the page's `arena-main`, by an id Arena writes on both sides.** There is nothing to
coordinate at the call site and no id to pass, because a page has one main landmark. A page with a
skip link and no `arena-main` has a link to nowhere, and nothing can detect that from inside
either component, so it is the one thing to check by hand.

**Do / Don't**
- **Do** say where the reader lands, in the application's own words. "Skip to content" and "Skip
  to the order list" are both right; the second is better on a screen whose content has a name.
- **Do** write exactly one per page, next to the one `arena-main`.
- **Don't** put it inside the header or the nav to "keep the shell tidy". Inside either, it is
  reached after them and skips nothing.
- **Don't** give it a `class` to make it visible for testing. Press Tab, which is the state a
  reader actually meets.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/layout/arena-skip-link/ArenaSkipLink.demo.generated.html`:
- With the page freshly loaded, the first Tab reveals it and nothing else has focus before it.
- It draws over whatever is beneath it rather than pushing the page down.
- Enter moves focus into the main region, and the Tab after that continues from inside it.
- A second Tab away from it makes it invisible again with no layout moving.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-app-bar/ArenaAppBar.prompt.md -->

Arena app bar, the band across the top of every screen. Standalone, `OnPush`, signal I/O. The host
takes itself out of layout with `display: contents` and the real `<header>` is inside, because a
banner landmark has to be that element.

```html
<arena-app-bar>
  <a brand routerLink="/" aria-label="Meridian Roasters, home">
    <arena-app-logo size="sm" name="Meridian" />
  </a>
  <nav nav aria-label="Shop sections">
    @for (d of destinations(); track d.id) { <a [routerLink]="d.href">{{ d.label }}</a> }
  </nav>
  <div actions>
    <arena-icon-button icon="ph-bold ph-magnifying-glass" label="Search the catalogue" (click)="openSearch()" />
  </div>
</arena-app-bar>
```

<!-- @api GENERATED from contracts/api/components/ArenaAppBar.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `brand` | slot |  |  | The identity, at the start edge: an ArenaAppLogo, a wordmark, a mark. Wrap it in your own link if it should lead home; the bar draws no anchor of its own, which is what keeps a router's link out of a component that would have to swallow it. |
| `nav` | slot |  |  | The way through the site, between the brand and the actions. It is a slot and not a list of destinations because the links are the consumer's: they are their router's, and the navigation landmark around them is theirs to name, since a page with a side nav as well needs the two told apart. |
| `actions` | slot |  |  | What follows the reader everywhere, at the end edge: search, theme, basket, account. Arena draws the row; the consumer draws what sits in it. |
| `sticky` | primitive | `boolean` | `true` | Whether the bar stays at the top edge as the page scrolls. True by default, because a bar that carries the way through a site and scrolls away with the content is a bar the reader has to go back for. It takes the navigation layer of the stacking order, so a dialog and a sheet still cover it. |

<!-- @api end -->

**The three slots are attributes**, `brand`, `nav` and `actions`, projected through the marker
directives. Each takes one element, so wrap a row of controls in a container of your own.

**The bar spans the viewport and the band inside it does not.** The fill and the hairline run edge
to edge; the contents stop at the page width with a gutter either side, so they line up with
everything under them. Both lengths are the roles a style plugin re-answers, the same pair `.arena-band`
carries for markup you wrote yourself.

**The nav landmark is yours, and that is deliberate.** The links are your router's, and Arena never
wraps one. A page with a side nav as well has two navigation landmarks, and naming them apart is a
judgement about your page rather than about this component.

**Do / Don't**
- **Do** wrap the brand in your own link if it should lead home. The bar draws no anchor.
- **Do** remember the host carries no box, which is the rule every `display: contents` primitive in
  this package carries.
- **Don't** put a second `<header>` at the top level of the page. Banner is one per page.
- **Don't** reach for it inside a card or a dialog. A `<header>` nested in a section is not a
  banner, and this component is one.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-app-bar/ArenaAppBar.demo.generated.html`:
- Scroll the page: with `sticky` the bar holds the top edge and a dialog still covers it.
- Narrow the window: the row wraps to two lines rather than squeezing its controls.
- The band's contents line up with the content under the bar at every width.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-bottom-nav-item/ArenaBottomNavItem.prompt.md -->

One destination in an `arena-bottom-nav`: glyph above label, an equal share of the bar's width.
Standalone, `OnPush`, signal I/O. It renders no wrapper of its own, so the host declares
`display: contents` and the anchor or the button inside is what the bar lays out.

Which destination is active and how this one reports are settled with the parent it injects, so
nothing about that is a member here.

```html
<arena-bottom-nav-item id="orders" icon="ph-bold ph-receipt" label="Orders" href="/orders" [badge]="12" />
<arena-bottom-nav-item id="more" icon="ph-bold ph-dots-three" label="More" />
```

<!-- @api GENERATED from contracts/api/components/ArenaBottomNavItem.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `id*` | primitive | `string` |  | Identifies the destination. ArenaBottomNav.active names one of these, and the item whose id matches is the one marked aria-current="page". Required, and guarded with a falsy check rather than an absence check: a blank id can never match and is an omission wearing a value. |
| `label*` | primitive | `string` |  | What the item reads under its glyph, and the whole of its accessible name unless a badge adds a count to it. Required and falsy-guarded for the same reason. It is drawn rather than hidden: a bar of glyphs alone asks every reader to have learnt the icons, and the label is what makes the destination sayable. |
| `icon*` | primitive | `string` |  | A Phosphor class name drawn above the label. Arena draws the element, the consumer names the glyph. **The ACTIVE destination is drawn in the filled weight, and there is no member for it**: the item whose id matches ArenaBottomNav.active swaps whatever weight the string carries for `ph-fill`, so a consumer passes one string per destination rather than two and a conditional. It is Arena's convention, so Arena applies it, and passing `ph-fill` yourself changes nothing because the swap is idempotent. Required here where a sidebar leaves it optional: a bar of five equal columns has no room for a label long enough to stand alone, and one column without a glyph breaks the row's rhythm. |
| `badge` | primitive | `number` |  | A count drawn over the glyph's trailing corner: pending orders, unread notices. Zero draws nothing, because a badge reading 0 is a mark that says there is nothing to mark; above 99 it reads "99+", so a four-digit count cannot widen the column. A number rather than a string, because both rules are arithmetic and a caller who has already formatted the value has taken them away. It is NOT hidden from assistive technology, so the destination announces "Orders 12". |
| `href` | primitive | `string` |  | Present => the item renders an <a>; absent => a <button>. A control that navigates must be a link: openable in a new tab, address copyable, announced as a link. An item that only changes local state is a button. A primary click with no modifier is cancelled and reported through ArenaBottomNav's `nav`, so a router owns it; a modified or middle click is the browser's and reports nothing. |
| `disabled` | primitive | `boolean` | `false` | Whether the destination is drawn but cannot be reached. It reflects through `aria-disabled` rather than the native attribute, and rather than by not rendering the item at all: a destination a user can see and hear announced as unavailable is what tells them it exists. The anchor keeps its `href` so the case split stays what it is; what changes is that activation is refused and the state is announced. |

<!-- @api end -->

**`icon` is required here where a sidebar leaves it optional**, and the active weight is not a
member: the destination whose `id` matches the bar's `active` has whatever weight the string carries
swapped for `ph-fill`, so pass one string per destination rather than two and a conditional. Passing
`ph-fill` yourself changes nothing, because the swap is idempotent.

**`label` is drawn, not hidden.** A bar of glyphs alone asks every reader to have learnt the icons.

`href` decides the element: present renders an `<a>`, absent a `<button type="button">`. A
destination that navigates must be a link; an item that only opens a local sheet is a button.

`badge` is a number, and Arena applies the two rules: zero draws nothing, and anything above 99 reads
`99+` so the column cannot widen. It is announced, so the destination reads "Orders 12".

`disabled` draws the destination and refuses it, through `aria-disabled` rather than the native
attribute, so a reader still hears that it exists.

**Do / Don't**
- **Do** keep the label to one word where you can. The column is a fifth of a phone, and a long one
  truncates.
- **Don't** format the badge yourself. A string would take the two rules away.
- **Don't** write it outside an `arena-bottom-nav`. It injects the bar, so without one there is no
  provider and Angular throws rather than rendering a destination that can never be current.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-bottom-nav/ArenaBottomNav.demo.generated.html` at 390px:
- A destination with a badge of 0 shows none, one of 4821 shows `99+`, and neither widens its column.
- Tab reaches every destination once, in source order, and the disabled one announces itself as
  disabled rather than being skipped.
- A five-word label truncates with an ellipsis instead of pushing its neighbours out of line.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-bottom-nav/ArenaBottomNav.prompt.md -->

Arena bottom navigation, the bar of destinations pinned to the bottom of a phone screen. Standalone,
`OnPush`, signal I/O. The host **is** the bar, so `<arena-bottom-nav>` is the element you place.

Compound, the `arena-side-nav` shape and the opposite direction: nothing is pushed down. Each
`arena-bottom-nav-item` injects the bar and pulls its signals, so a consumer's own wrapper component
between the two still works.

```html
<arena-bottom-nav ariaLabel="Primary" [active]="route()" (nav)="go($event)">
  <arena-bottom-nav-item id="home" icon="ph-bold ph-house" label="Home" href="/" />
  <arena-bottom-nav-item id="orders" icon="ph-bold ph-receipt" label="Orders" href="/orders" [badge]="12" />
  <arena-bottom-nav-item id="clients" icon="ph-bold ph-users" label="Clients" href="/clients" />
  <arena-bottom-nav-item id="more" icon="ph-bold ph-dots-three" label="More" />
</arena-bottom-nav>
```

<!-- @api GENERATED from contracts/api/components/ArenaBottomNav.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `active` | primitive | `string` |  | The id of the current destination. The ArenaBottomNavItem whose id matches is marked aria-current="page" and draws its glyph in the filled weight, and no item is marked when it names none of them. |
| `ariaLabel*` | primitive | `string` |  | Names this navigation landmark. Required, and **guarded at runtime**: the guard trims before it decides, so a blank name is refused as well as an absent one, because a landmark present with no accessible name is the defect arriving through a value. A phone shell usually carries this bar AND a sidebar or a header, so two navigation landmarks share a page and the pattern asks each for a unique name; a constant default would satisfy the existence half and leave them indistinguishable. |
| `content` | slot |  |  | The destinations. One ArenaBottomNavItem each; which id is active and how each reports `nav` are the parent's to settle, and none of it is a member here. |
| `nav` | event | `string` |  | A destination was activated, carrying its id. Where the item has an href, Arena has already cancelled the anchor by the time this fires, so a listener routes and does not double-navigate; a modified click, a middle click and open-in-new-tab are the browser's and fire nothing, so a consumer who wires no listener still has a bar of real links. |

<!-- @api end -->

**It is not an `arena-side-nav` lying down.** A sidebar is a stack of indented rows with the glyph
before the label and arbitrary nesting; this is a row of equal columns with the glyph above the label
and no nesting at all. It is not `arena-tabs` either, which mounts every panel at once and announces
tablist/tab/tabpanel, and not `arena-segmented-control`, which is a radio group that chooses rather
than navigates.

Its geometry is Arena's tokens rather than a number: `--layout-bar` for the height, `--z-nav` for the
stacking slot, and `--pad-safe-bottom` so the row clears the home indicator on a device that has one.
Reserve the same height at the foot of the page it covers, or the last row of content sits under it.

**`ariaLabel` is required and guarded at runtime**, trimmed before it decides, so a blank one throws.
A phone shell usually carries this bar and a header or a sidebar too, so two navigation landmarks
share a page and each needs its own name.

**Do / Don't**
- **Do** give a destination an `href` when it is one. The item renders a real `<a>`, so it opens in a
  new tab, its address copies, and it is announced as a link.
- **Do** route in `(nav)`. Arena has already cancelled the primary click by the time it fires, so
  routing there navigates once; ctrl-click and middle-click stay the browser's and report nothing.
- **Don't** put `routerLink` on it. `RouterLink` decides by `tagName` and by `customElements`, and an
  Angular component is neither, so it would ignore the modifiers and add a second tab stop over the
  anchor already inside.
- **Don't** exceed five destinations. Every column takes an equal share, and a sixth makes the labels
  truncate before anyone has read them.
- **Don't** reach for it above a phone width. It covers the bottom of the viewport, and a wide screen
  has a sidebar's room.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-bottom-nav/ArenaBottomNav.demo.generated.html` at 390px:
- Primary click, ctrl+click, middle click and Enter on the same destination: the first and the last
  report once and navigate once, the other two open a tab and report nothing.
- The active destination's glyph is filled and its label takes the primary ink; the others do not.
- With the browser emulating a device inset, the row lifts by it and the bar grows rather than the
  labels moving under the home indicator.
- A `ArenaMenu` opened from the page paints over the bar, and an `ArenaSheet` does too.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-breadcrumbs/ArenaBreadcrumbs.prompt.md -->

Arena breadcrumb trail. Mono, wide-tracked, with the last crumb as the current page --
not a link, and carrying `aria-current="page"`. The landmark is a real `<nav>` inside a bare
`display: contents` host, with `aria-label` bound to the required `ariaLabel` input, the same
carve-out `arena-pagination` takes, because the `navigation` pattern offers `role="navigation"`
only for when a `<nav>` cannot be used. Use it where a hierarchy is deeper than tabs can show.

**A consumer attribute written on `<arena-breadcrumbs>` lands on the inert host, not on the
styled `<nav>`**, which is the price every carve-out pays and is why the default is to
host-bind.

`ariaLabel` is **required**: `input.required`, so Angular throws when it is missing. A constant
like `"Breadcrumb"` written straight into the `host` block names the
WIDGET rather than the trail and leaves two of these on one page indistinguishable as
landmarks. Say which hierarchy this is a trail through ("Project navigation").

A crumb renders as a real `<a href>` and splits its activations. The plain one is reported
through `navigate`, which carries the clicked `ArenaCrumb` alone: route from there and the browser
does not navigate underneath you. The rest keep working for a consumer who wires no listener
at all.

`href` is optional, and a crumb without one is drawn as a `<span>` rather than as an anchor. That
is the same branch the last crumb already takes, minus its `aria-current`: a level of the trail
that leads nowhere is not a link and does not take the pointer or the hover either. What it must
never be is an anchor to the page it sits on, which is a dead edge in the crawl graph and a target
the keyboard can reach and nothing happens on.

**Do not put `routerLink` on `arena-breadcrumbs`.** `RouterLink` decides whether it is on an
anchor from the host's `tagName`, and the anchor here is inside the component, so it would
ignore every modifier key and add a second tab stop over the crumb's own link. Route in the
handler instead:

```html
<arena-breadcrumbs ariaLabel="Project navigation" [items]="[
  { label: 'Clients', href: '/clients' },
  { label: 'Ardennes', href: '/clients/ardennes' },
  { label: 'Deployments' }
]" (navigate)="go($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaBreadcrumbs.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `ariaLabel*` | primitive | `string` |  | Names this navigation landmark. Required, and guarded at runtime: nothing can derive it, and the constant "Breadcrumb" it used to hardcode made two trails on one page indistinguishable as landmarks while satisfying the requirement mechanically. Say which hierarchy this is a trail through: "Project navigation", never "Breadcrumb". |
| `items*` | array | `readonly ArenaCrumb[]` |  | The trail, root first. The last entry is the current location and is never a link. |
| `separator` | primitive | `string` | `"/"` | Drawn between crumbs, never before the first. Arena draws it, in its own aria-hidden span. |
| `origin` | primitive | `string` |  | The scheme and host each crumb's href is resolved against in the structured data the component emits, as in "https://example.com". Absent, the relative href is published as it stands, which is valid and less well supported. It is a member rather than something read off the document because location.origin does not exist on a server, and a value that differs between the server render and the client one is the hydration hazard ArenaCalendar.timeZone already documents; a value the consumer passes cannot differ. One line per application, not per screen. It changes nothing a person sees. |
| `navigate` | event | `ArenaCrumb` |  | A non-current crumb was activated, carrying that crumb alone. The native MouseEvent is not forwarded, because a platform's own event type never travels in a payload; what the listener needs from it, the chance to route instead of navigating, arrives as behaviour rather than as data. Arena has already cancelled the anchor by the time this fires, so a listener routes and does not double-navigate. It fires for a primary click with no modifier and for Enter; ctrl-click, middle-click and open-in-new-tab are the browser's and fire nothing, so a consumer who wires no listener still has a working trail of real links. |

<!-- @api end -->

```ts
go(crumb: ArenaCrumb): void {
  this.router.navigateByUrl(crumb.href ?? '/');
}
```

**Do / Don't**
- Keep the last crumb non-navigable. A link to the page you are on is noise, and it
  breaks the trail's promise that everything to the left is somewhere else.
- Don't use breadcrumbs for steps in a flow. A trail describes where something *is*,
  not how far through it you are -- that is the coachmark's dots or a stepper.
- Don't truncate the middle of a trail to save space. Wrap it; the row already does.
- Don't reach for `(navigate)` to call `preventDefault()` -- it never receives the click
  event, and it does not need to: Arena has already cancelled the anchor by the time it fires.
- Don't route on a modified click. `(navigate)` never fires for one, and if it did, opening
  in the current tab is the opposite of what the reader asked for.

**Accessibility note:** the trail renders no `<ol>`/`<li>` wrapper, so a
screen reader gets no "list, N items" orientation cue that the WAI-ARIA APG's breadcrumb
structure would otherwise give. `nav[aria-label="Breadcrumb"]` and `aria-current="page"`
are what make the trail operable and named; the list semantics were judged a secondary
nicety, not an operability gap, and left out on that basis rather than by oversight.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-bulk-action-bar/ArenaBulkActionBar.prompt.md -->

Arena bulk actions bar. It renders only when `count` is above zero, states the size of
the selection in mono, and offers actions that operate on the set. A destructive
action stays outline in `--error` -- transparent at rest, the soft `--danger-soft`
tint only on hover -- like every risk trigger but one; the filled danger surface stays
`arena-confirm-dialog`'s alone. `count` and `actions` are required. Import `ArenaBulkAction`
from `@dravensoft/arena-angular` for the `actions` input's element type.

```html
<arena-bulk-action-bar [count]="selected().length" noun="deployments"
                       [actions]="[
                         { id: 'rerun', label: 'Re-run', icon: 'ph-bold ph-arrow-clockwise' },
                         { id: 'archive', label: 'Archive', icon: 'ph-bold ph-archive' },
                         { id: 'delete', label: 'Delete', icon: 'ph-bold ph-trash', destructive: true }
                       ]"
                       (run)="apply($event)" (clear)="selected.set([])" />
```

<!-- @api GENERATED from contracts/api/components/ArenaBulkActionBar.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `count*` | primitive | `number` |  | How many rows are selected. Zero renders no bar at all. |
| `noun` | primitive | `string` | `"items"` | What is being counted, plural: "items", "projects". |
| `actions*` | array | `readonly ArenaBulkAction[]` |  | The actions offered for the current selection. |
| `run` | event | `ArenaBulkAction` |  | An action was activated, carrying which one. |
| `layout` | enum | `ArenaBulkActionBarLayout` | `"auto"` | Whether the bar may stack. 'auto' measures its OWN container, not the viewport, and drops the count, the actions and Clear onto separate rows when one row does not fit; 'inline' keeps the single row at every width, for a bar in a place the consumer knows is wide. It is a member rather than something a consumer reaches in with CSS because the alternative is what happens without it: reordering the bar's own children by position, which puts focus order out of step with visual order and breaks the next time anything inside moves. Stacking here reorders nothing, so the tab order and the reading order stay the same order they are wide. |
| `clearable` | primitive | `boolean` | `true` | Whether the Clear control is drawn. Every layer gates on this member and never on whether anything listens for `clear`, because Arena never derives what it draws from what a consumer listens for. |
| `clear` | event |  |  | The Clear control was activated. |

<!-- @api end -->

`clearable` (default `true`) gates whether Clear is drawn. Every layer gates on this member
and never on whether anything listens for `clear`.

### It stacks when its own container is narrow

`layout` defaults to `auto`, which measures **the bar's own container** rather than the viewport
and drops the count, the actions and Clear onto separate rows below `--bp-sm`. Set `inline` when
the bar sits somewhere you know is wide.

**Stacking reorders nothing**, and that is the whole reason the member exists rather than a
consumer reaching in with CSS. Reordering the bar's children by position moves what is on screen
and leaves the tab sequence where it was, so the focus order and the reading order stop matching,
and it breaks again the next time anything inside the bar moves. Both layers assert that the
control order is identical in the two shapes.

**Do / Don't**
- Always offer Clear. A selection the user cannot see the edges of is a selection they
  will act on by accident.
- Put the destructive action last, and confirm it with `arena-confirm-dialog` -- the bar
  starts the action, it does not finish it.
- Don't hide the bar behind a menu. Its whole job is to be visible the moment a
  selection exists.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-command-palette/ArenaCommandPalette.prompt.md -->

Arena command palette, the keyboard accelerator behind Cmd/Ctrl+K. Type to filter,
arrow to a command, Enter to run it, Escape to leave, or hover a row to select it.
`hint` is searched but not shown, so a command can be found by a word that is not in
its label. `open` and `commands` are both `input.required`; the host must always bind
both. Each command's `icon` is a Phosphor class name Arena draws, not projected content.
The host owns `open` and the shortcut that sets it, and decides whether running a
command also closes the palette. The search field is an ARIA 1.2 combobox
wired to the row list as its listbox popup, so a screen reader announces which row is
active as you arrow through it.

```html
<arena-command-palette [open]="paletteOpen()" [commands]="commands"
                       (close)="paletteOpen.set(false)"
                       (run)="paletteOpen.set(false); dispatch($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaCommandPalette.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `open*` | primitive | `boolean` |  | Whether the palette is shown. Closed renders nothing. |
| `commands*` | array | `readonly ArenaCommand[]` |  | Every command the palette can find. Filtered by label and hint as the user types. |
| `placeholder` | primitive | `string` | `"Search for an action or project…"` | The search field's placeholder. |
| `maxResults` | primitive | `number` |  | How many matches the list shows at most. Absent, all of them. The ceiling applies AFTER the query has run over every command, which is what makes it different from the caller trimming `commands` before passing them: a trimmed list cannot match what was cut, and a capped one can, so the first rows are still the best the whole set has. It is the palette's rather than the domain's, because how many rows help before the list stops being an accelerator is a property of this control; a caller who caps their own collection has guessed at it once, for one collection, with no query in hand. It is not ranking: the order stays the order the caller passed, ungrouped first and then each group as it first appears. |
| `close` | event |  |  | The palette asked to be closed: Escape, the scrim, or a command having been run. |
| `run` | event | `ArenaCommand` |  | A command was activated, carrying which one. Emitted after close. For a command with `route` it fires for a primary click with no modifier and for Enter, both of which cancel the row's anchor first, so the two activations do the same thing and a host that routes here never navigates twice; a modified or middle click on such a row is the browser's, fires nothing and does not close the palette. |

<!-- @api end -->

**Do / Don't**
- Put every command's real shortcut in `shortcut`. The palette is where people learn
  the shortcuts that let them stop using the palette.
- Use `hint` for the synonyms people actually type: "logout" for "Sign out".
- Close the palette yourself in your `run` handler if that is what you want; the
  component does not assume it for you.
- Don't put destructive actions in the palette without a confirmation behind them. A
  palette entry is one Enter away from running.
- Don't make the palette the only way to reach something. It is an accelerator, not
  navigation.
- Don't express a condition as an attribute string. `open` carries the
  `booleanAttribute` transform, so a bare `open` and `[open]="true"` both
  mean true, and the one literal string `"false"` means false. Every *other* string is
  true, `"0"`, `"off"` and `"no"` all leave the palette open. Bind the expression
  (`[open]="paletteOpen()"`) rather than relying on the literal.

### Groups and routes

`group` heads a command's section. Commands with no group list first and ungrouped, then each
group in the order its first command appears, so a palette built by concatenating four
collections gets its headings back without the caller reordering anything. The heading is
drawn and also announced as the group's name, so it carries `aria-hidden` on the visible copy
rather than being read twice.

`route` says where running a command goes. With it the row renders an `<a href>`, so
ctrl-click, middle-click and open-in-new-tab work, which is what an accelerator over a list of
destinations owes a keyboard user. It keeps `role="option"`, because the listbox pattern
requires that of every row and losing it would break the arrow walk for the whole list: a
screen reader announces the row as an option rather than as a link, and that is the trade.

**With `route`, the mouse and the keyboard do the same thing, and that is the point.** The
row's plain activation reports through `(run)`, so a host that navigates in its `(run)` handler
navigates exactly once, whichever way the reader activated the row. A modified click opens the
destination itself and **leaves the palette open**, because a reader who asked for a second tab
did not ask to leave this one.

`maxResults` caps how many matches the list shows. **Reach for it instead of trimming
`commands` before you pass them**, which is the thing that does not work: a list cut to the
forty most recent invoices cannot match the one from March, and the query never gets the
chance. The cap runs after the search, so the rows are still the best the whole set has.

There is still no ranking member. A scoring function would be a `functionInput` in a contract
that declares no `kind: "input"`, and a better order is an improvement inside the component
rather than something a caller supplies; `maxResults` changes how many rows are shown and
never which ones come first.

### The shortcut is yours, and that is deliberate

The palette is named after Cmd/Ctrl+K and binds nothing. A global key binding belongs to the
application: it has to know which other surface owns the key, whether a dialog is already up,
and whether the reader is typing in a field. A component that took the key would fight the
host for it and win by accident of load order. Three lines in the shell:

```ts
@HostListener('document:keydown', ['$event'])
onKey(event: KeyboardEvent): void {
  if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
    event.preventDefault();
    this.paletteOpen.set(true);
  }
}
```

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-menu/ArenaMenu.prompt.md -->

Arena menu, a dropdown of actions hanging off a trigger the consumer draws. Standalone,
`OnPush`, signal I/O. The host wraps the trigger and nothing else; the panel lives in a
`@angular/cdk/overlay` pane on `document.body`.

That is the whole reason for the overlay: a menu's canonical home is an overflow row in a table
or a card, and an absolutely-positioned panel is clipped by the first `overflow: hidden`
ancestor. Arena uses the CDK for **position only**: the roles, the keys and the focus are
Arena's. The app must import `frameworks/angular/theme/arena-cdk.css` once, or the panel renders
unpositioned.

```html
<arena-menu [items]="rowActions" align="end" (select)="run($event)">
  <arena-icon-button trigger icon="ph-bold ph-dots-three-vertical" label="More actions" />
</arena-menu>
```

<!-- @api GENERATED from contracts/api/components/ArenaMenu.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `trigger*` | slot |  |  | The element that opens the menu. The consumer draws it -- an ArenaIconButton with ph-dots-three-vertical, a secondary ArenaButton -- so it is a slot, and it carries its own accessible name. |
| `items*` | array | `readonly ArenaMenuItem[]` |  | The entries, in order: activatable rows, dividers and group headers. |
| `align` | enum | `ArenaMenuAlign` | `"start"` | Which edge of the trigger the panel lines up with. |
| `select` | event | `ArenaMenuItem` |  | An entry was activated; carries the whole item. A disabled entry reports nothing, and a divider or a header cannot be activated at all. |

<!-- @api end -->

```ts
protected readonly rowActions: ArenaMenuItem[] = [
  { header: 'Build 482' },
  { label: 'Promote', icon: 'ph-bold ph-rocket-launch', shortcut: 'P' },
  { divider: true },
  { label: 'Delete', destructive: true },
];
```

`trigger` is a **projected slot**, marked with the bare `trigger` attribute, because the consumer
owns what the control looks like and what it is called. Arena writes `aria-haspopup="menu"` and
`aria-expanded` onto it, onto the **focusable element**, resolved by search rather than by
taking the host's first child. That distinction is load-bearing: an `<arena-button>` is
`display: contents`, so it is neither focusable nor in the accessibility tree, and the attributes
on it would reach nobody. It also stops its own native click, so the activation is bound to the
resolved control directly and never to the host.

Enter and Space are intercepted on the trigger and `preventDefault()`ed, so the platform does not
also synthesize a click and open the menu twice. Escape closes and returns focus to the trigger;
a pointer press outside the host **and** outside the pane closes without moving focus. Opening
moves focus to the first enabled row.

`select` carries the **whole item**, not a key, since `ArenaMenuItem` deliberately has no `id`. A divider
and a header are not rows at all and render no `menuitem`; a disabled row renders one and reports
nothing.

**Do / Don't**
- **Do** mark exactly one element with `trigger`, and one that is or contains a focusable
  control. Arena has nothing to hang the menu on otherwise.
- **Do** put the marker on the element `arena-menu` itself receives. Wrapping the control in
  another Arena component, an `arena-tooltip`, say, means the marker goes on the **wrapper**,
  since `<ng-content select="[trigger]">` matches what is projected and not what is nested
  inside it. The focusable control is still found by search, so the attributes land in the right
  place either way; what a misplaced marker loses is the projection, and the menu then renders no
  trigger at all.
- **Do** put destructive entries last, behind a `divider`. `destructive: true` draws the row in
  the danger ink and keeps it **outline**: a menu row is never a filled danger surface.
- **The trigger must be a control, not a picture of one.** An `arena-avatar`, a `<span>` or anything else that takes no focus receives the listeners and answers no key, so the menu
  opens on a pointer and a reader on a keyboard never reaches it. Arena reports that once at
  runtime; project an `arena-icon-button`, an `arena-button`, or your own element carrying a
  button role and a tabindex.
- **Do** reach for `align="end"` when the trigger sits at the right edge of its row, so the panel
  hangs inward instead of off the page. The CDK will flip it above the trigger near the bottom of
  the viewport on its own.
- **Don't** use `shortcut` expecting Arena to bind the key. It is display only, and the contract
  says so; the host binds it or nothing does.
- **Don't** put a form, a submenu or anything focusable beyond the rows into `items`. `ArenaMenuItem`
  is three shapes and none of them projects content; a menu that needs more is a dialog.

**By hand, in real Chromium**: none of this is provable in happy-dom, which has no layout and no
platform activation. Run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-menu/ArenaMenu.demo.generated.html`:
- The panel escapes an `overflow: hidden` ancestor and a scroll container, and repositions while
  that container scrolls.
- Near the bottom of the viewport it flips above its trigger; `align="end"` hangs it from the
  trigger's right edge.
- One Enter opens it **once**, and one Space does too; the double-open is exactly what the
  `preventDefault` is there to stop, and only a browser synthesizes the click that would cause
  it.
- A menu opened from inside an `arena-dialog` paints above the panel, and a tooltip on a row
  paints above the menu.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-page-head/ArenaPageHead.prompt.md -->

Arena page header: the display-weight title, an optional subtitle, and the page's
actions. It measures **itself**, not the viewport, and stacks below `--bp-sm`, a page
head inside a narrow panel stacks there too, on any screen. Actions are projected, so the
head lays out controls the consumer wrote rather than declaring a second button API of its own.

```html
<arena-page-head title="Deployments" subtitle="Everything shipped in the last 30 days" align="center">
  <arena-button actions variant="secondary">Export</arena-button>
  <arena-button actions>New deployment</arena-button>
</arena-page-head>
```

<!-- @api GENERATED from contracts/api/components/ArenaPageHead.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `title*` | primitive | `string` |  | The page title. Required: a page head with no title is a bug, not a state. |
| `headingLevel` | enum | `ArenaHeadingLevel` | `"h1"` | Which rung of the document outline the title takes. Only the element changes: the title's class is the same at every value, so the render is identical and no appearance follows from it. It defaults to `h1` because a page head is the page's own title and the screen it heads carries no other. Under a hero, the one rung above it on the title ladder, it takes `h2` and leaves the page's single `h1` to the hero; that is the one arrangement where the default is wrong, and it is a member rather than something read off the page, because what a component renders is never derived from what sits above it. `none` is refused at runtime, the rule every component whose `title` is required follows: a title required because it names the thing it draws cannot also be told that the name is not one. |
| `subtitle` | primitive | `string` |  | A muted line under the title. |
| `actions` | slot |  |  | Page-level controls, right-aligned in the head. |
| `align` | enum | `ArenaPageHeadAlign` | `"start"` | Cross-axis alignment of the actions block against the title, wide layout only. |

<!-- @api end -->

`title` is required: a page head with no title is a bug, not a state. `align` (default
`start`) governs only the wide layout's cross-axis alignment of the actions block against
the title; below `--bp-sm` the row always stacks and `align` has no effect. `arena-page-head`
applies no outer bottom margin; the parent composes that spacing.

Import `ArenaActions` from `@dravensoft/arena-angular` alongside `ArenaPageHead` in the
host component's `imports`,
`actions` is a directive, not a plain attribute, because it is how the page head
detects that actions were projected at all. Without it the attribute is inert, the
actions wrapper never renders, and the buttons silently disappear. `ArenaActions` is
shared: every primitive with a plural, toolbar-shaped projected slot imports the same
directive rather than declaring its own.

The measurement helper is public too. `arenaContainerWidth()` is exported from
`@dravensoft/arena-angular` for a consumer building their own responsive component: call it
from an injection context (a field initializer or the constructor), render the wide layout
while the width is still `null`, and compare against the breakpoint token rather than writing
a media query.

`arenaContainerWidth()` measures the caller's own host by default and takes an `ElementRef` when
the box to measure is a different one, so a component whose responsive question is about an
inner panel does not have to make that panel a component of its own. The injection context is
required either way, and not because of the element: `DestroyRef` disconnects the observer and
`afterNextRender` decides when there is a box to measure at all. For page CSS rather than a
component, write the media query yourself against the same three thresholds Arena uses,
480px, 768px and 1024px. A media query condition holds no `var()`, so there is no token form
of them to import.

**Do / Don't**
- Exactly one `arena-page-head` per screen. It emits the `h1`, and a page with two
  `h1`s has no outline. Under an `arena-hero`, which is the one rung above it on the title
  ladder, it takes `headingLevel="h2"` and leaves the page's single `h1` to the hero: it cannot
  see the hero, because what an Arena component renders never follows from what sits above it.
- Keep the subtitle to one line of orientation. It is not the place for instructions.
- Don't write a media query to stack it. It already stacks, on its own width, which is
  the measurement that is right more often.
- Mark **each** control with `actions`, as siblings. Arena lays them out in a wrapping
  row, and that row wraps its own children: a single `<div actions>` holding three buttons is
  one flex item, so it can never wrap, and three buttons overflow the page at 390px. One
  element per control is what makes the wrap reachable at all.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-pagination/ArenaPagination.prompt.md -->

# `arena-pagination`

Jumps between pages of a large set, the companion to a table or a long list. It renders a
*window* over the pages, never all of them, and elides the rest with a single `…`.

```html
<arena-pagination ariaLabel="Deployments" [page]="page()" [pageCount]="12"
                  (change)="page.set($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaPagination.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `page*` | primitive | `number` |  | The current page, 1-based. |
| `pageCount*` | primitive | `number` |  | How many pages there are. Required, and guarded at runtime: an ArenaPagination with no page count renders a window over nothing. |
| `ariaLabel*` | primitive | `string` |  | Names this navigation landmark. Required, and guarded at runtime: two paginated tables in one dashboard is a routine layout, and a shared constant name leaves them indistinguishable while satisfying the requirement mechanically. It was optional with a "ArenaPagination" default for one batch, which narrowed the gap rather than closing it: a name the caller omits is still the constant. Say what is being paged: "Deployments", not "Pages". |
| `change` | event | `number` |  | A page was chosen; carries the new 1-based page. Never fires for the current page, nor for a page outside 1..pageCount. |

<!-- @api end -->

`page`, `pageCount` and `ariaLabel` are all required, and the last two are **guarded at
runtime** rather than defaulted. `input.required` only proves something was bound:
`[ariaLabel]="row.title"` with an empty title, or `[pageCount]="0"`, both satisfy it and
neither is a pagination. So the component throws on each, a whitespace-only name, and a page
count that is not a whole number of at least one.

`ariaLabel` names the landmark, and nothing can derive it. Two paginated tables in one
dashboard is a routine layout, and a shared constant name leaves them indistinguishable while
satisfying `roles.label` mechanically. Say what is being paged, as in `"Deployments"`, not
`"Pages"`.

`change` carries the new 1-based page. It never fires for the page already shown, nor for a
page outside `1..pageCount`, so a handler can set its signal without re-checking either.

How wide the window is comes from the design layer, not from this component:
`--limit-pagination-siblings` says how many pages flank the current one, and the total width is
derived from it at the point of use. Both layers read the same token.

**Do / Don't**
- Place it under the table or list, aligned right or centred.
- For continuous feeds use "load more" or infinite scroll, not `arena-pagination`.
- Don't wrap it to add margin: the host is `display: contents`, so put the margin on a real
  element of your own around it.
- Don't hide the arrows at the ends. They are disabled there, which keeps the strip's width
  from changing as a consumer pages through it.

**By hand, in real Chromium**: `frameworks/angular/components/navigation/arena-pagination/ArenaPagination.demo.generated.html`,
served with `bun run demos`:
- Walk the 20-page strip to the middle and watch the window elide on **both** sides, then to
  each end and watch it elide on one side only.
- Tab through the strip. Every page and both arrows take focus in reading order, and each shows
  the browser's own focus ring; this component adds none of its own.
- At page 1 and at page 20 the outward arrow is dimmed and does not respond to a click, and the
  strip does not change width.
- The current page must be tellable from the others with the page desaturated, not by colour
  alone: it is the only filled surface in the row.
- With a screen reader, move by landmark: the two strips on the card announce as *Environments*
  and *Deployments*, never as two identical ones.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-segmented-control/ArenaSegmentedControl.prompt.md -->

Arena segmented control, a compact inline filter over mutually exclusive options. **A real radio
group, never a tab list**, and it carries no crimson: a filter never outweighs the action beside
it. Standalone, `OnPush`, signal I/O. The host **is** the track, so it carries `role="radiogroup"`,
the accessible name and the focus ring.

```html
<arena-segmented-control ariaLabel="Time range" [options]="ranges" [value]="range()"
                         (change)="range.set($event)" />

<arena-segmented-control ariaLabel="Status" size="sm" [options]="statuses"
                         defaultValue="failing" (change)="filter.set($event)" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSegmentedControl.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `options*` | array | `readonly ArenaSegmentOption[]` |  | The options, in order. Two to four with one-word labels. |
| `value` | primitive | `string` |  | The selected option's value. Omit and pass `defaultValue` to let it govern itself. |
| `defaultValue` | primitive | `string` |  | The initially selected value when uncontrolled. Defaults to the first option. |
| `size` | enum | `ArenaSegmentedControlSize` | `"md"` | Compact or default. |
| `ariaLabel*` | primitive | `string` |  | Names what is being filtered: "Time range", not "Filter". A radio group with no accessible name is announced unlabelled. |
| `name` | primitive | `string` |  | Shared name for the underlying radios; generated when omitted. |
| `change` | event | `string` |  | A different option was chosen; carries its value. |

<!-- @api end -->

```ts
readonly ranges: ArenaSegmentOption[] = [
  { value: '24h', label: '24h' },
  { value: '7d', label: '7d' },
  { value: '30d', label: '30d' },
];
```

**It replaces a Material control that got one thing wrong, and this one must not inherit it.**
`MatButtonToggleGroup` applies `role="group"` even in its exclusive single-selection mode, the
delegated entry carried a `roles.group` exception saying so, citing Material's own docs. Arena
renders `role="radiogroup"` itself, so this binding has **no exceptions**, and the compliance suite
asserts the role by name rather than by pattern so that a regression reads as what it is.

**Do / Don't**
- **`ariaLabel` is required** and names what is being *filtered*, "Time range", not "Filter". A
  radio group with no accessible name is announced unlabelled, and a name that only says the
  control is a filter satisfies the requirement while telling a screen-reader user nothing.
- **Two to four options with one-word labels.** The track stops being compact past that; a longer
  set is `arena-radio-group`, and a set that switches *views* rather than filtering one is
  `arena-tabs`.
- It works controlled or not: pass `value` and it is yours, or pass `defaultValue` and the track
  remembers its own choice. With neither, **the first option is selected**: a filter showing
  nothing selected over an unfiltered list is lying about itself.
- **The roving tab stop, the arrow keys and Space are the platform's.** Each segment is a native
  `<input type="radio">` inside its `<label>`, sharing one `name`. Arena authors no `tabindex`.
- `name` is the radios' shared form name, generated per instance when omitted, and never reaches a
  screen reader. Two tracks sharing one name rove as a single group.
- The focus ring is on the **track**, through `focus-within:`, because the element that takes focus
  is an `opacity-0 size-0` input. That is the whole reason the ring is not on the segment.
- Don't reach for it as a form field. It is a filter; a mutually exclusive answer inside a form,
  with labels that need room, is `arena-radio-group`.
- Don't give the selected segment the brand colour. It lifts on `bg-neutral` with a shadow instead,
  and no state of the control reaches for `primary` at all.

**By hand, in real Chromium**: the platform behaviour above is what happy-dom cannot show. Run
`bun run demos` and open
`/frameworks/angular/components/navigation/arena-segmented-control/ArenaSegmentedControl.demo.generated.html`:
- Tab into the track **once**: the ring appears around the whole track, not around a segment, and
  Tab again leaves it rather than walking the segments.
- Arrow keys move the selection along the track and wrap at both ends.
- The selected segment's shadow reads as a lift against the track's own surface at `sm` as well as
  `md`, `sm` is the size that decides whether the lift is visible at all.
- Two tracks on the page select independently, which is the generated `name` working.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-side-nav-collapsible/ArenaSideNavCollapsible.prompt.md -->

Arena side-nav collapsible, a disclosure inside an `arena-side-nav`: a trigger row that shows and
hides a group of destinations. Standalone, `OnPush`, signal I/O.

```html
<arena-side-nav-collapsible id="deploys" icon="ph-bold ph-rocket-launch" label="Deployments"
                            (toggle)="remember('deploys', $event)">
  <arena-side-nav-item id="prod" label="Production" href="/prod" />
  <arena-side-nav-item id="staging" label="Staging" href="/staging" />
</arena-side-nav-collapsible>
```

<!-- @api GENERATED from contracts/api/components/ArenaSideNavCollapsible.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `id*` | primitive | `string` |  | Identifies the group. The disclosure pattern needs two DOM ids that resolve -- the trigger's aria-controls must name the region, and the region's aria-labelledby must name the trigger -- and Arena derives both from this member, as `${id}-trigger` and `${id}-region`. Neither wiring is conditional: every collapsible has a trigger and a region, so there is no shape in which the id goes unused, and that is why it is required rather than optional. A group is a thing a consumer names anyway. Falsy-guarded as well as required: a blank id yields the pair `-trigger`/`-region`, which every other blank-id collapsible on the page would share, and duplicate ids make aria-controls resolve to the wrong element rather than to none. A consumer can address either element from outside as a consequence -- an aria-describedby, a deep link, a test hook -- but that is a benefit of the derivation, not the reason for it. |
| `label*` | primitive | `string` |  | What the trigger reads, and the accessible name of both the trigger and the region it controls. Required and falsy-guarded. |
| `icon` | primitive | `string` |  | A Phosphor class name drawn before the label. The caret that reports expanded-ness is Arena's own and is not this member. |
| `defaultExpanded` | primitive | `boolean` | `false` | Whether the group starts open. It is a seed, not a control: after the first render the state is the component's, and the group also opens itself when it comes to hold the active destination. |
| `content` | slot |  |  | What the group holds -- items, sections, further collapsibles. Each sits one nesting level deeper. |
| `toggle` | event | `boolean` |  | The trigger was pressed, carrying the state it moved to. It fires on a press ONLY: the automatic expansion that follows the active destination is Arena's decision rather than the user's, and reporting it here would be a lie a consumer persists. |

<!-- @api end -->

The trigger is a native `<button type="button">` carrying `aria-expanded` and an `aria-controls`
naming its region. **The region is always rendered** and hidden by the `hidden` attribute alone,
the preflight's `[hidden] { display: none !important }` outranks the region's own `flex`, so
nothing has to hide it a second time. `aria-controls` therefore never points at
nothing, and a collapsed region's links are out of the tab order because `hidden` removes them.

**It opens itself around the active destination, and that is not a press.** If any row anywhere in
its subtree is `active`, the group expands, including a group two levels up from the row. That
expansion is Arena's decision, so it reports **nothing** through `toggle`; reporting it would be a
lie a consumer persists. A user may then collapse a group holding the active destination and it
stays collapsed: the state is derived at the seed and owned by the user afterwards.

Enter and Space are **intercepted and prevented**, then toggle. That is one rule shared with
`arena-menu`: leaving them to the platform means the synthesized click fires too, and the group
opens twice in a browser while a suite sees it open once.

`defaultExpanded` seeds the first render only. `toggle` carries the state it moved to.

**Do / Don't**
- **Do** persist `toggle` if the rail should remember itself across a reload. Arena keeps no
  storage of its own.
- **Do** nest one inside another when the hierarchy has three levels. They are independent
  disclosures and neither closes the other.
- **Don't** read this as a treeview. There is no `aria-level`, no roving tab stop and no arrow
  navigation, and that is refused rather than missing, a nav landmark full of links is a set of
  disclosures, and the binding states the cost.
- **Don't** put a destination on the trigger itself. It opens a group; a row that navigates is an
  `arena-side-nav-item`.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-side-nav-item/ArenaSideNavItem.prompt.md -->

Arena side-nav item, one destination in an `arena-side-nav`. Standalone, `OnPush`, signal I/O.
The host declares `display: contents`
and the row itself is a real `<a>` or a real `<button>`, so the browser's own activation,
navigation and focus semantics are never re-implemented.

```html
<arena-side-nav-item id="projects" icon="ph-bold ph-squares-four" label="Projects" href="/projects" />
<arena-side-nav-item id="settings" icon="ph-bold ph-gear-six" label="Settings" />
```

<!-- @api GENERATED from contracts/api/components/ArenaSideNavItem.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `id*` | primitive | `string` |  | Identifies the destination. ArenaSideNav.active names one of these, and the item whose id matches is the one marked aria-current="page". Required, and guarded with a falsy check rather than an absence check: a blank id can never match and is an omission wearing a value. |
| `label*` | primitive | `string` |  | What the item reads, and the whole of its accessible name unless a badge adds a count to it. Required and falsy-guarded for the same reason. |
| `icon` | primitive | `string` |  | A Phosphor class name drawn before the label -- Arena draws the <i>, the consumer names the glyph. **The ACTIVE row is drawn in the filled weight, and there is no member for it**: the item whose id matches ArenaSideNav.active swaps whatever weight the string carries for `ph-fill`, so a consumer passes one string per destination rather than two and a conditional. It is Arena's convention, so Arena applies it, the same judgement that inverted ArenaPageHead's guidance rather than adding a boolean whose false nobody wants. Pass `ph-fill` yourself and nothing changes, since the swap is idempotent. |
| `disabled` | primitive | `boolean` | `false` | Whether the destination is drawn but cannot be reached -- one the consumer's rules lock, such as a feature the current plan does not include. It reflects through `aria-disabled` rather than the native attribute, and rather than by not rendering the item at all: an unavailable destination a user can see and hear announced as unavailable is what tells them it exists, which is the whole reason to draw it. The anchor keeps its `href` so the case split stays what it is -- what changes is that activation is refused and the state is announced. |
| `badge` | primitive | `number` |  | A count drawn at the row's trailing edge -- pending orders, unread notices. Zero draws nothing, because a badge reading 0 is a mark that says there is nothing to mark; above 99 it reads "99+", so a four-digit count cannot widen the column. A number rather than a string, because the two rules above are arithmetic and a caller who has already formatted the value has taken them away. It is NOT hidden from assistive technology, so the row announces "Orders 12": a count a screen-reader user cannot hear is a count that is not there, and aria-hidden on it would trade a real loss for a tidier name. What the 12 counts stays unsaid, because nothing can derive it and no member states it -- say it in the label where it matters. |
| `href` | primitive | `string` |  | Present => the item renders an <a>; absent => a <button>. A control that navigates must be a link -- openable in a new tab, address copyable, announced as a link. An item that only changes local state is a button. A primary click with no modifier is cancelled and reported through ArenaSideNav's `nav`, so a router owns it; a modified or middle click is the browser's and reports nothing. |

<!-- @api end -->

**`href` decides the element.** With one it renders an `<a>`; without one, a `<button
type="button">`. Both carry the same row styling, the same `aria-current="page"` when active, and
both report through the enclosing nav's `nav` output. The anchor's native navigation is **not**
suppressed, so a middle-click or a ctrl-click behaves as a link should.

That is also why the binding is `none` rather than `button`: no single interactive pattern applies
to a component that renders two different elements. What the rendered element carries comes from
the platform and from `ArenaSideNav`'s own `navigation` binding.

`id` and `label` are both **required and guarded at runtime**. `icon` is a Phosphor class name that
Arena draws as an `aria-hidden` `<i>`, the single-icon convention, never a projected node.

`aria-current="page"` is present on the active row and **absent** on the rest, never `false`.

**Do / Don't**
- **Do** write one item per destination, as a sibling. Depth comes from the containers around it,
  and an item never declares its own.
- **Do** use `href` when the destination is a real URL, even in a routed app. A nav made of buttons
  cannot be opened in a new tab.
- **Don't** wrap it in anything expecting the indent to survive, it will, because depth is pulled
  through DI rather than pushed, but a wrapper still changes the flex layout of the column.
- **Do** pass a count as `badge`, not as markup. The item takes no projected content, so the
  count is a number Arena draws at the trailing edge: zero draws nothing, and above 99 reads
  `99+`. Pass the raw number, because both of those rules are arithmetic and a string has
  already taken them away. Anything else a row might want, an avatar or a second line, is
  still a change to the contract rather than to a caller.

- **`disabled` draws the destination and refuses it.** It reflects through `aria-disabled` rather
  than by not rendering the item: an unavailable destination a user can see, and hear announced as
  unavailable, is what tells them it exists. The anchor keeps its `href`, so the shape does not
  change; what changes is that the click is prevented and the nav is never told to activate.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-side-nav-section/ArenaSideNavSection.prompt.md -->

Arena side-nav section, a labelled group of destinations inside an `arena-side-nav`. Standalone,
`OnPush`, signal I/O. The host **is**
the group: `role="group"` and the `aria-labelledby` that names it sit on it, with the heading
rendered inside.

```html
<arena-side-nav-section label="Workspace">
  <arena-side-nav-item id="members" label="Members" href="/members" />
  <arena-side-nav-item id="billing" label="Billing" href="/billing" />
</arena-side-nav-section>
```

<!-- @api GENERATED from contracts/api/components/ArenaSideNavSection.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `label*` | primitive | `string` |  | Names the group, both on screen and to assistive technology. Required, and guarded at runtime: a blank label leaves the group with no accessible name, which is the defect the guard exists to prevent arriving through a value that is present, so the guard trims before it decides. |
| `content*` | slot |  |  | The items in the group -- SideNavItems, further SideNavSections, SideNavCollapsibles. Each sits one nesting level deeper than the section itself. Required, and guarded at runtime: a section with no children is not a legal shape, and the guard counts the way the render path counts, so a child that is a false conditional counts as absent rather than as one. The ArenaAppLogo.mark shape -- a slot that is both declared required and enforced -- and not the ArenaTooltip.content one, which is declared required and deliberately left unguarded. |

<!-- @api end -->

**Its content is required, and it is the only slot in the repository that is.** A section renders a
heading naming the group, so a childless one labels nothing, it **throws** at content-init rather
than rendering. Slot required-ness is not comparable between layers and no gate can catch a caller
who omits it, which is why the guard is runtime code and not a declaration.

It is a container, so it **re-provides** the family's state at `depth + 1`: everything inside it
indents one step, including a nested section or a collapsible. Its own heading is indented at its
**own** depth, so it lines up with its siblings rather than with its children.

The binding is `none`: the group carries no interactive affordance of its own, and every control
inside it belongs to a child.

**Do / Don't**
- **Do** give it a `label` that names the group rather than describing it, "Workspace", not
  "Workspace links".
- **Do** nest sections when the hierarchy genuinely has two levels. The indent compounds and
  nothing needs configuring.
- **Don't** use one to add a visual gap. An empty section throws, and a section of one item is a
  heading that outweighs what it introduces.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-side-nav/ArenaSideNav.prompt.md -->

Arena side nav, the primary navigation landmark, and the root of a compound family that nests to
any depth. Standalone, `OnPush`, signal I/O. The host **is** the landmark: `role="navigation"`,
the accessible name and the column layout all sit on it.

```html
<arena-side-nav ariaLabel="Primary" [active]="route()" (nav)="go($event)">
  <arena-side-nav-item id="projects" icon="ph-bold ph-squares-four" label="Projects" href="/projects" />
  <arena-side-nav-section label="Workspace">
    <arena-side-nav-item id="members" label="Members" href="/members" />
    <arena-side-nav-collapsible id="deploys" icon="ph-bold ph-rocket-launch" label="Deployments">
      <arena-side-nav-item id="prod" label="Production" href="/prod" />
    </arena-side-nav-collapsible>
  </arena-side-nav-section>
</arena-side-nav>
```

<!-- @api GENERATED from contracts/api/components/ArenaSideNav.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `active` | primitive | `string` |  | The id of the current destination. The ArenaSideNavItem whose id matches is marked aria-current="page", and no item is marked when it names none of them. |
| `ariaLabel*` | primitive | `string` |  | Names this navigation landmark. Required, and guarded at runtime: the guard trims before it decides, so a blank name is refused as well as an absent one, because ariaLabel="" renders a landmark with no accessible name, which is the defect arriving through a value that is present. Guarded rather than defaulted: the navigation pattern asks each landmark on a page for a UNIQUE name, and a constant default satisfies the existence half while two sidebars on one page stay indistinguishable. Nothing can derive it either; what a nav is FOR is editorial. Say what it navigates -- "Primary", "Project settings" -- the ArenaTable.label and ArenaSegmentedControl.ariaLabel shape. |
| `content` | slot |  |  | The navigation tree. One ArenaSideNavItem per destination, optionally grouped by ArenaSideNavSection and ArenaSideNavCollapsible; where each child sits, which id is active and how it reports `nav` are the parent's to settle, and none of it is a member here. |
| `indentStep` | primitive | `number` | `3` | How far each nesting level indents, as a MULTIPLIER of --sp-1 rather than a length: the row at depth N is padded calc(var(--sp-1) * 3 + var(--sp-1) * indentStep * N). A CSS string was rejected -- a caller-supplied "1.5rem" is neither a token nor a derivation of one, so it would stop re-densifying inside .arena-compact, and no gate would catch it because the gate that forbids a bare length scans source and not the values a caller passes in. |
| `nav` | event | `string` |  | An item was activated, carrying its id. It carries the id alone, on the ArenaBreadcrumbs precedent that the platform event leaves the payload and the item travels by itself, and under the compound shape there is no item datum left to carry either, because the consumer wrote the element and already holds everything on it. Where the item has an href, Arena has already cancelled the anchor by the time this fires, so a listener routes and does not double-navigate; ctrl-click, middle-click and open-in-new-tab are the browser's and fire nothing, so a consumer who wires no listener still has a working column of real links. |

<!-- @api end -->

`ariaLabel` is **required and guarded at runtime**, because `input.required` is a compile-time
claim and a blank string satisfies it. Two navigation landmarks on one page must not share a name.

**Depth is pulled, not pushed, and that is the whole design.** Each container **provides** a
fresh `ArenaSideNavState` whose depth is its parent's plus one, and a row reads its own indent from
the nearest ancestor through DI. The consequence is worth knowing: **a consumer's own wrapper
component between two levels is harmless**, because DI walks past it, and so is a `@for`, and
so is any depth of projection. Nothing here inspects its own children, so nothing here can be
broken by what sits between them.

**A row declares its own id to the nearest state, and that is how a group knows it holds the
active destination.** The travel is the row's, not the group's, for the same reason the indent is:
a row is where its own `id` is bound, so it is the only place that value can be read without
asking a question about a child that has not been given one yet. So a group opens itself around
an active row it never sees, whether a `@for` built that row, a wrapper component holds it, or it
sits three levels down.

`indentStep` is a **number**, never a CSS string, a multiplier on `--sp-1`, not a length. A row at
depth N is padded `calc(var(--sp-1) * 3 + var(--sp-1) * indentStep * N)`, so the indent
re-densifies and re-themes with the token. Pass a step, never a length: a CSS string here
would survive the type and then stop tracking the density and the theme.

`active` is the id of the current destination and `nav` reports the id of the row pressed. An item
with `href` splits its activations: the plain one is reported through `nav`, so
`router.navigateByUrl` in that handler is the whole bridge and nothing navigates twice, and the
rest keep working for a consumer who wires no handler.

**Do not put `routerLink` on `arena-side-nav-item`.** `RouterLink` decides whether it is on an
anchor from the host's `tagName`, and the anchor here is inside the component, so it would ignore
every modifier key and add a second tab stop over the row's own link. Navigate in `(nav)` instead.

**Do / Don't**
- **Do** give each row a stable `id`. `active`, `nav` and the collapsible's own auto-expansion are
  all keyed by it.
- **Do** leave `indentStep` alone unless the rail is unusually narrow. Three is the step every
  Arena sidebar uses.
- **Don't** put a heading, a divider or a search box in as a child. The family is this component and its
  three kinds of child, and the landmark holds nothing else.
- **Don't** expect a treeview. Each collapsible is an independent disclosure, no `aria-level`, no
  roving tab stop, no arrow navigation, and that is refused rather than missing;
  `ArenaSideNavCollapsible.behaviour.json` states the cost.

### `active` is an id, and there is no route matcher

`active` names one of the ids you gave the items, and the item whose id matches is the one
marked `aria-current="page"`. It is **not** a path, and there is no `activeMatch` to say
whether it should be compared against each `href` whole or by prefix.

That was asked for and refused, and the reason is not that Arena would have to import
`@angular/router`: it would not, since a prefix comparison is arithmetic over data you pass
in. The reason is that the member would change what a *different* member means depending on
its own value, so `active` would name an id under one setting and a path under another, and
nothing could check which one a caller meant. A member that redefines its neighbour is a
member that cannot be read in isolation.

Compute the active id yourself. The `NavigationEnd` bridge that turns `router.url` into a
signal is yours in either design, because `router.url` is a property rather than a signal.
Write the bridge, then the comparison:

```ts
private readonly router = inject(Router);

readonly url = toSignal(
  this.router.events.pipe(filter((e) => e instanceof NavigationEnd), map(() => this.router.url)),
  { initialValue: this.router.url },
);

readonly active = computed(() => DESTINATIONS.find((d) => this.url().startsWith(d.href))?.id);
```

**Read `router.url` through the bridge and never in the template.** Reading the property
directly appears to work, because swapping the routed component marks the shell dirty as a
side effect of how `RouterOutlet` works, and a zoneless `OnPush` shell then re-renders anyway.
It stops the moment a navigation reuses the component it is already showing, which is what a
tab change or a parameter change does, and nothing reports it: the rail simply keeps the
previous destination lit.

**By hand, in real Chromium**: run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-side-nav/ArenaSideNav.demo.generated.html`:
- Each level steps in by exactly one `--sp-1 * indentStep`, and a row's icon stays aligned with its
  siblings' rather than with its parent's.
- Switching the active destination moves the ink and the weight, and opens the group holding it.
- The rail still reads at `.arena-compact`, where every indent shrinks with the token.

### The active row is filled, and you pass one string

The item whose `id` matches `active` draws its glyph in `ph-fill`, whatever weight the string
carries. Pass `icon="ph-bold ph-house"` once per destination; do not concatenate a weight
yourself against a condition, which is Arena's own convention reimplemented in every project
that adopts it. The swap is idempotent, so passing `ph-fill` yourself changes nothing.

**A misspelled `ph-` name renders an empty box, silently**, because an icon is a class name
and a class that matches no glyph is not an error. Nothing on your side catches that for you,
so check a name against the `@phosphor-icons/web` you installed if a wrong one would be
expensive.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-tab/ArenaTab.prompt.md -->

Arena tab, one view inside an `arena-tabs` strip. Standalone, `OnPush`, signal I/O. It exists
because a consumer's own content has to go inside **one** item of something Arena draws: the
moment there is one element per view, per-item projection stops being the problem it would be
otherwise.

```html
<arena-tabs [value]="view()" (change)="view.set($event)">
  <arena-tab value="overview" label="Overview">
    <arena-stat-card label="Uptime" value="99.98%" />
  </arena-tab>
  <arena-tab value="settings" label="Settings">…</arena-tab>
</arena-tabs>
```

<!-- @api GENERATED from contracts/api/components/ArenaTab.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `value*` | primitive | `string` |  | What this tab selects, and what the parent's `change` carries. |
| `label*` | primitive | `string` |  | What the tab reads. Arena draws the button; the consumer names it. |
| `content` | slot |  |  | What the panel shows while this tab is selected. ArenaTabs places it; ArenaTab never renders it, because a tabpanel may not sit inside a tablist. |

<!-- @api end -->

**It draws the panel, not the button.** `arena-tabs` renders the tablist and every tab button in
it from this component's `label`; `arena-tab`'s own host **is** the tabpanel. That split is not a
style choice, a tabpanel may not sit inside a tablist, so the two cannot be one element.

**Do / Don't**
- **`value` and `label` are both required.** `value` is what the parent's `change` carries;
  `label` is what the button reads.
- **It only works inside `arena-tabs`.** It injects the parent's state to learn whether it is
  selected and which ids wire it to its button; on its own it has nothing to inject and Angular
  reports it as a missing provider.
- **Values must be distinct within one strip.** The parent resolves both ids by finding the tab
  with that value, so a duplicate makes two panels answer to one button.
- **Its content mounts whether or not it is selected**, and is hidden rather than removed when it
  is not. Anything expensive belongs behind a guard inside the content, not behind the tab.
- It binds the `none` pattern, and that is not an absence: every requirement that applies to a tab
  is a clause of the `tabs` pattern, which `arena-tabs` binds and its suite verifies.
- Don't reach for `arena-tab` to make a panel you place yourself. It renders where the parent puts
  it, which is after the tablist and nowhere else.

**By hand, in real Chromium**: checked from the parent's page, since a tab alone renders nothing
useful. Run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-tabs/ArenaTabs.demo.generated.html`, then walk the checklist in
`ArenaTabs.prompt.md`.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->


<!-- frameworks/angular/components/navigation/arena-tabs/ArenaTabs.prompt.md -->

Arena tabs, a row of tabs and the panels they switch between, for **views of one subject**, never
for steps in a flow. Standalone, `OnPush`, signal I/O. A compound family: write one `arena-tab` per
view and `arena-tabs` draws the tablist, places the panels, and owns the keyboard.

```html
<arena-tabs [value]="view()" (change)="view.set($event)">
  <arena-tab value="overview" label="Overview">…</arena-tab>
  <arena-tab value="deployments" label="Deployments">…</arena-tab>
  <arena-tab value="settings" label="Settings">…</arena-tab>
</arena-tabs>

<arena-tabs defaultValue="deployments">
  <arena-tab value="overview" label="Overview">…</arena-tab>
  <arena-tab value="deployments" label="Deployments">…</arena-tab>
</arena-tabs>
```

<!-- @api GENERATED from contracts/api/components/ArenaTabs.json. Edit the contract, not this table. -->

**Members**, in contract order and under this layer's own names. `*` marks a required one.

| Member | Form | Type | Default | What it is |
|---|---|---|---|---|
| `content` | slot |  |  | The tabs. Which one is selected, which is the strip's tab stop, the ids wiring each to its panel and how the choice is reported are the strip's to settle, and none of it is a member here. EVERY tab's content mounts: one panel per tab is rendered and the inactive ones are hidden, because each tab's aria-controls must reference a tabpanel that exists. So a panel's side effects run immediately rather than on first selection. |
| `value` | primitive | `string` |  | The selected tab's value. Omit and pass `defaultValue` to let it govern itself. |
| `defaultValue` | primitive | `string` |  | The initially selected value when uncontrolled. Defaults to the first tab. |
| `change` | event | `string` |  | A different tab was chosen; carries its value. |

<!-- @api end -->

**The children pull; the parent pushes nothing.** `arena-tabs` provides an injectable
`ArenaTabsState` and each `arena-tab` injects it and pulls, its selected state, and the two ids
wiring it to its button. Nothing is pushed, and **no member of either contract describes any of it**. The state
object is not exported from the barrel: it is coordination, not API.

**Every panel mounts.** One `arena-tab` renders one tabpanel, and the unselected ones are hidden
rather than removed, because each tab's `aria-controls` must reference a tabpanel that exists,
a reference pointing at nothing is worse than an absent one. The consequence is real and the
contract states it: **a panel's side effects run immediately**, not on first selection. If a view
is expensive, guard it inside the view rather than expecting the tab to defer it.

**Do / Don't**
- **`value` and `label` are required on every `arena-tab`.** `label` is what the tab reads; Arena
  draws the button, the consumer names it.
- Controlled or not: pass `value` and it is yours, or pass `defaultValue` and the strip remembers
  its own choice. With neither, **the first tab wins**, so a panel is always showing.
- `change` fires only when a **different** tab is chosen. Re-selecting the active tab reports
  nothing.
- **The panels sit outside the tablist**, which is why `arena-tab` renders its content into its own
  host rather than into the row. A tabpanel inside a tablist is invalid, and the compliance suite
  asserts it by containment.
- **The host takes itself out of layout** with `display: contents`, so the tablist and the panels
  stack in the consumer's own flow instead of inside a box `arena-tabs` adds.
- **The roving tab stop and the arrow keys are Arena's**, through `@angular/cdk/a11y`'s
  `FocusKeyManager`: one tab stop into the strip, Left/Right walk and wrap, and the selection
  follows the focus. Up/Down do nothing on purpose, so a horizontal strip does not fight a vertical
  list nested near it.
- **The CDK reads the deprecated `event.keyCode`, not `event.key`.** A browser fills it in, so this
  works in Chromium; a synthetic event that omits it is ignored entirely. Any suite dispatching a
  key at this component must set `keyCode`; happy-dom leaves it `0`, so a suite that sets only
  `key` asserts nothing and passes.
- With no tabs at all it draws an **empty tablist and no tabpanel**, and guards nothing. A root
  promises nothing an empty render would break, but it must not ship an invalid one.
- Don't use it for steps in a sequence, or for anything a person should be able to open in a new
  window. Those are `arena-side-nav` items or links, not tabs.
- Don't fill the selected tab. It is marked by a crimson underline and by weight; a filled tab
  spends the view's primary accent on navigation.

**By hand, in real Chromium**: the keyboard is asserted for real, but the ink and the ring are not.
Run `bun run demos` and open
`/frameworks/angular/components/navigation/arena-tabs/ArenaTabs.demo.generated.html`:
- Tab into the strip **once**: the ring lands on the selected tab, and Tab again leaves the strip
  rather than walking the tabs.
- Left and Right walk the strip and wrap at both ends, and the panel below changes with them.
- The crimson underline sits flush on the strip's own hairline rule rather than floating above it.
- The panel's top gap does not change when switching tabs, the layout must not shift.
- Two strips on the page switch independently, which is the generated id base working.

<!-- @rules GENERATED for every prompt from one source. Edit it there, not here. -->

**The rules of the language hold in the code you write from this page, and no gate reads your application to enforce them.** An Arena component is not a styling surface: put no `class` of your own on it, read every value through its token rather than a raw colour or a bare `16px`, and never wrap it in your router's own link. The rest of the rules are in [`../../../../../skills/design/SKILL.md`](../../../../../skills/design/SKILL.md).

<!-- @rules end -->