# Components

Each component exists in React (`@enma-design/react` or `enma-design/react`) and as plain HTML classes (see recipes). Props match `index.d.ts`; the full API is in `enma.md`.

## Layout and containers

- **EnmaRoot:** sets the theme (`data-enma`) and mode (`data-theme`) for everything inside. One at the app root. `mode="home"` uses the theme's best mode; `canvas` paints the theme background. Don't nest roots to restyle one card.
- **Card:** `surface` (default container), `raised` (a group inside a surface), `hero` (the one hero per screen, flips text to on-hero and shows the theme's signature), `frame` (phone-level shell). Padding `none`, `sm` 12, `md` 16, `lg` 20. Don't stack cards inside cards inside cards.

## Actions

- **Button:** `secondary` by default, `primary` at most once per view, `ghost` for toolbars and low emphasis, `danger` for destructive actions. `size="lg"` with `block` for the main mobile action, `sm` in dense toolbars. `loading` shows a spinner and ignores clicks. Labels are verbs in sentence case, never "Click here" or "Submit".
- **IconButton:** one icon in a square button for toolbars and headers. `label` is required (accessible name and tooltip). Use a text button when a word is clearer.
- **Icon:** outline icons on a 24px grid, 1.75 stroke, `currentColor`, sizes 16, 20, 24. Give `label` only when it stands alone and carries meaning. In apps use Lucide at the same stroke. Never emoji.

## Numbers and data

- **Stat:** a number with label, unit, delta and sub line in the theme's number face. `hero` for the one big number (inside a hero card), `kpi` for tiles, `inline` inside rows. Counts up once on first view; screen readers get the full value at once. Units outside the number. Don't animate values that update every second.
- **Bars:** a short series (up to about 14 values) with one highlighted bar (default the last). No axes or gridlines. Always has a text summary.
- **LineChart:** a series over time, with an optional dashed comparison series ("this period vs last") and a soft area fill. Show a few axis labels, not every point.
- **Sparkline:** a word-sized trend beside a number, in a table cell or a KPI tile.
- **Donut:** one share of a whole (a goal, a course, a quota), with the value in the center. One per group, never a pie of many slices.
- **Progress:** a labelled bar for goals, uploads and limits, 0 to 100, with `valueText` like "4 of 5 sessions". Not for indeterminate waits; at most three stacked.
- **Table:** B2B data with quiet headers, hairline rows and right-aligned tabular numbers (`align: 'end'`, `numeric`). Status in a Badge. Always a `caption`. No zebra stripes, vertical borders or centered numbers. `framed={false}` inside a card.
- **Badge:** one or two words of status or a delta ("Paid", "+8%"), tones `neutral`, `accent`, `positive`, `negative`. A word, never color alone; at most two per row.

## Lists and navigation

- **ListGroup:** grouped rows on a raised panel (settings, exercises, recent items) with `ListGroup.Row` (`title`, `description`, `meta`, `leading`, `trailing`, `onClick` or `href` for a chevron). Rows are at least 44px. Don't mix actionable and static rows without a cue.
- **TabBar:** bottom navigation for mobile apps, three to five destinations, with labels. Never actions like "New" in the tab bar.
- **SegmentedControl:** two to four mutually exclusive views of the same content (Week, Month, Year). One tab stop; arrow keys move. Not for navigation between unrelated pages.

## Forms

- **TextField:** a labelled input with optional icon, hint and error. The error replaces the hint and says what to do ("Enter a full email address."). `sm` in toolbars, `lg` on mobile forms. Placeholders are real examples.
- **Switch:** an on/off setting that applies immediately. Use Checkbox when there is a Save button.
- **Checkbox:** a choice confirmed later, or a checklist item.

## Feedback and people

- **Toast:** a short confirmation or error after an action ("Invoice sent"), `neutral`, `positive` or `negative`, with at most one action. Bottom center on mobile, bottom right on desktop, about 4 seconds. Never the only place for a critical error.
- **Avatar:** a person's photo or initials, `sm` 28, `md` 36, `lg` 48. No decorative rings.