@omkarux/vela 0.2.0

package/guidelines/components/button.md

@@ -0,0 +1,104 @@
+# Button
+
+Triggers an action — save, submit, delete, apply, cancel. Carries a text label and an
+optional **left** icon. `variant` encodes the action's consequence; `appearance` encodes
+visual weight.
+
+## When to use Button (vs. something else)
+
+- Action that stays in the page flow → **Button**.
+- Navigates to another page → a router `<Link>`, not a Button.
+- Flips a binary setting that takes effect immediately → **Toggle**.
+- Icon-only, no label → an Icon Button, which is **not in this kit**. Flag the gap.
+
+## Props
+
+```tsx
+<Button variant="primary" appearance="filled" size="regular" icon={<PlusIcon />}>
+  Save Changes
+</Button>
+```
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `variant` | `"primary" \| "standard" \| "destructive"` | `"standard"` | Consequence. **These three only.** |
+| `appearance` | `"filled" \| "hollow" \| "text-link"` | `"filled"` | Weight. **These three only.** `text-link` is primary-only. |
+| `size` | `"tiny" \| "regular" \| "large" \| "huge"` | `"regular"` | **These four only.** |
+| `disabled` | `boolean` | `false` | A state, not a variant. Leaves the tab order. |
+| `loading` | `boolean` | `false` | Shows an indicator, sets `aria-busy`, ignores clicks. |
+| `icon` | `ReactNode` | — | Always **left** of the label. There is no trailing slot. |
+| `type` | `"button" \| "submit"` | `"button"` | `"submit"` only for a form's commit button. |
+| `children` | `ReactNode` | — | Label. Verb-first, Title Case. |
+
+Every other native `<button>` attribute is forwarded, and the ref lands on the `<button>`.
+
+## Hard constraints (enforced by the type system)
+
+These are not review conventions — the compiler rejects them. `ButtonProps` is a
+discriminated union, so a violation is a build failure, not a bug report.
+
+- **`appearance="text-link"` requires `variant="primary"`.** No standard or destructive
+  text-link exists.
+- **`text-link` is `tiny` or `regular` only**, and **never carries an icon** (`icon?: never`).
+- **`text-link` is never underlined.** Colour carries the affordance; hover shifts colour.
+- **One `variant="primary" appearance="filled"` per page.** Pair it with hollow / text-link
+  for everything else. This one is a convention — the compiler cannot count buttons.
+- **Icons sit left only.**
+- **Width hugs content.** Never fix a button width.
+- **`destructive` encodes consequence, not emphasis.** Delete/revoke/remove only. Never
+  for "Cancel", never just to stand out.
+
+## Token bindings
+
+Container: `border-radius: var(--vela-radius-4)` — not a pill. Focus ring comes from
+`.vela-root :focus-visible`; do not add a per-button outline.
+
+| variant · appearance | Background | Text | Border |
+|---|---|---|---|
+| primary · filled | `--vela-btn-primary-bg` | `--vela-btn-primary-text` | same as bg |
+| primary · hollow | transparent | `--vela-btn-hollow-primary-text` | `--vela-btn-hollow-primary-border` |
+| primary · text-link | transparent | `--vela-text-link` | none |
+| standard · filled | `--vela-btn-standard-bg` | `--vela-btn-standard-text` | `--vela-btn-standard-border` |
+| standard · hollow | transparent | `--vela-btn-standard-text` | `--vela-btn-standard-border` |
+| destructive · filled | `--vela-btn-destructive-bg` | `--vela-btn-destructive-text` | same as bg |
+| destructive · hollow | transparent | `--vela-btn-destructive-hollow-text` | same as text |
+| disabled (any) | `--vela-btn-disabled-bg` | `--vela-btn-disabled-text` | `--vela-border-inactive` |
+
+`--vela-btn-destructive-bg` resolves to `red-700`, **not** `red-500`. See
+`foundations/color.md` — red-500 fails AA behind a white label.
+
+## Sizes
+
+| size | Height | H-padding | Icon | Font |
+|---|---|---|---|---|
+| tiny | `--vela-control-height-24` | `--vela-space-10` | `--vela-icon-12` | 12/18 |
+| regular | `--vela-control-height-35` | `--vela-space-15` | `--vela-icon-16` | 14/21 |
+| large | `--vela-control-height-40` | `--vela-space-20` | `--vela-icon-16` | 15/22 |
+| huge | `--vela-control-height-60` | `--vela-space-30` | `--vela-icon-16` | 16/24 |
+
+Label weight is **Regular 400 at every size**.
+
+## States
+
+- **Hover** — filled variants darken (lighten in dark mode) via their `-hover-bg` token.
+  `text-link` shifts colour and stays un-underlined.
+- **Focus** — the shared `:focus-visible` ring. Never `outline: none`.
+- **Disabled** — native `disabled`. Not focusable. Explain why in adjacent helper text.
+- **Loading** — the label **stays**, a spinner appears, `aria-busy="true"` is set, and the
+  button remains focusable while ignoring clicks. Swapping the label for a spinner would
+  strip the control's accessible name mid-request; disabling it would drop focus.
+
+## Anti-patterns
+
+- ❌ Two primary filled buttons on one page.
+- ❌ Pill-shaped buttons → `--vela-radius-4`.
+- ❌ `--vela-control-height-48` for huge → huge is 60px.
+- ❌ A 20px or 24px icon in a Button → 12 at tiny, 16 elsewhere.
+- ❌ Fixed button widths.
+- ❌ A trailing icon.
+- ❌ A destructive or standard text-link → primary only (will not compile).
+- ❌ Underlining a text-link.
+- ❌ `destructive` for emphasis on a harmless action.
+- ❌ Hardcoded colours → always `var(--vela-*)`.
+- ❌ SemiBold or Bold labels → Regular 400.
+- ❌ Non-verb labels ("Information", "Status") → if it is not an action, it is not a button.

package/guidelines/components/contextual-alert.md

@@ -0,0 +1,59 @@
+# Contextual Alert
+
+An inline banner carrying a severity. Lives in the page flow, next to the thing it is about
+— it is not a toast and not a modal.
+
+## When to use Contextual Alert
+
+- An event or condition the user must read, inline → **Contextual Alert**.
+- An object's ongoing health, usually in a table → **Status Indicator**.
+- Transient confirmation that floats and auto-dismisses → a Toast, **not in this kit**.
+- A blocking decision → a Modal, **not in this kit**. Flag the gap.
+
+## Props
+
+```tsx
+<ContextualAlert severity="major" title="Scan failed" onDismiss={close}>
+  Three assets could not be reached.
+</ContextualAlert>
+```
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `severity` | `"success" \| "info" \| "warning" \| "minor" \| "major" \| "critical"` | — | **Required. These six only.** |
+| `title` | `string` | — | Optional bold lead-in. |
+| `children` | `ReactNode` | — | **Required.** The body. |
+| `onDismiss` | `() => void` | — | Omit for alerts the user must not clear. |
+| `dismissLabel` | `string` | `"Dismiss"` | Accessible name for the close control. |
+
+## Hard constraints
+
+- **Six severities, no more.** There is no `"high"`, no `"error"`, no `"danger"`. Those
+  belong to the Risk taxonomy or to nothing. The compiler rejects them.
+- **`major` and `critical` announce assertively** (`role="alert"`, `aria-live="assertive"`);
+  everything else is polite (`role="status"`). This is derived from `severity` and is not
+  configurable — an info banner that interrupts a screen reader is a defect.
+- **No dismiss control unless `onDismiss` is passed.** A critical alert the user can clear
+  without acting is usually wrong.
+- Icon is chosen by severity and is `aria-hidden` — the text carries the meaning.
+
+## Token bindings
+
+Every level binds its own complete row: `--vela-bg-severity-*`,
+`--vela-border-severity-*`, `--vela-icon-severity-*`, `--vela-text-severity-*`.
+Never mix a severity background with a risk text colour.
+
+## Accessibility
+
+- Colour is never the only signal: each severity has a distinct icon **and** its label text.
+- Live-region politeness is derived from severity, as above.
+- The dismiss control is a real button with an accessible name.
+
+## Anti-patterns
+
+- ❌ `severity="high"` or `"error"` → not in the taxonomy (will not compile).
+- ❌ Using a risk token for the background → severity and risk are separate.
+- ❌ An info alert with `role="alert"` → interrupts for no reason.
+- ❌ Dismissible critical alerts with no other resolution path.
+- ❌ Conveying severity by colour alone.
+- ❌ Using this as a toast → it is inline and does not float.

package/guidelines/components/input.md

@@ -0,0 +1,65 @@
+# Input
+
+Single-line text entry with a label, optional hint, and an error state.
+
+## When to use Input
+
+- Single-line text or numeric-as-text → **Input**.
+- Multi-line → Text Area, **not in this kit**. Flag the gap.
+- Numeric with a spinner → Number Stepper, **not in this kit**. Flag the gap.
+- Choosing from a set → Radio or Dropdown, **not in this kit**.
+
+## Props
+
+```tsx
+<Input label="Tenant name" hint="Lowercase letters only" error={err} size="regular" />
+```
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | — | **Required.** |
+| `hint` | `string` | — | Helper text. Wired via `aria-describedby`. |
+| `error` | `string` | — | Presence sets the error state; the string is the message. |
+| `size` | `"tiny" \| "regular" \| "large"` | `"regular"` | **These three only.** |
+| `required` | `boolean` | `false` | Renders a `*` and sets the native attribute. |
+
+Every other native `<input>` attribute is forwarded; the ref lands on the `<input>`.
+
+## Hard constraints
+
+- **`label` is required.** An input with only a placeholder is not labelled.
+- **`error` is a message, not a boolean.** An error state with no explanation is not an
+  error state.
+- `aria-describedby` only ever references elements that are actually rendered — a dangling
+  reference is worse than none, and a test asserts this.
+
+## Token bindings
+
+Background `--vela-control-bg`; border `--vela-control-border`; hover
+`--vela-control-border-hover`; focus `--vela-control-border-active`; error
+`--vela-control-border-error`; placeholder `--vela-control-placeholder`. Radius
+`--vela-radius-4`.
+
+## Sizes
+
+| size | Height | Padding |
+|---|---|---|
+| tiny | `--vela-control-height-25` | `--vela-space-5` |
+| regular | `--vela-control-height-26` | `--vela-space-10` |
+| large | `--vela-control-height-35` | `--vela-space-10` |
+
+These are the **input family** heights and do not match Button's ramp. See
+`foundations/sizing.md`.
+
+## Accessibility
+
+- Label is a real `<label htmlFor>`.
+- Error state sets `aria-invalid` and the message is announced via `role="alert"`.
+- The `*` is `aria-hidden`; `required` carries the semantics.
+
+## Anti-patterns
+
+- ❌ Placeholder as the label.
+- ❌ `error={true}` with the message elsewhere → pass the message.
+- ❌ Turning the border red without `aria-invalid`.
+- ❌ Input `regular` (26px) next to Button `regular` (35px) without deliberate alignment.

package/guidelines/components/status-indicator.md

@@ -0,0 +1,48 @@
+# Status Indicator
+
+A coloured dot representing one of exactly five health states, usually in a table cell or
+next to an object name.
+
+## When to use Status Indicator
+
+- An object's ongoing health → **Status Indicator**.
+- An event the user must read → **Contextual Alert**.
+- A risk score → the Risk taxonomy, on a Token Pill (**not in this kit**). Flag the gap.
+
+## Props
+
+```tsx
+<StatusIndicator status="unhealthy" label="api-gateway-01" />
+```
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `status` | `"unknown" \| "healthy" \| "warning" \| "medium" \| "unhealthy"` | — | **Required. These five only.** |
+| `label` | `string` | — | Visible text. **Strongly preferred.** |
+| `size` | `"small" \| "regular"` | `"regular"` | **These two only.** |
+
+## Hard constraints
+
+- **Five states.** Not severity's six, not risk's three. There is no `"critical"` status and
+  no `"high"` status — the compiler rejects both.
+- **`medium` means degraded**, sitting between `warning` and `unhealthy`. It is not the
+  middle of a risk scale.
+- **Colour is never the only signal.** With no `label`, the component sets an `aria-label`
+  from the status ("Unhealthy", "Degraded", …) so the dot is never silent. With a `label`,
+  it does not duplicate it — the visible text is the accessible name.
+
+## Token bindings
+
+Fill is `--vela-signal-status-*` only. The dot uses `--vela-radius-full` — one of only two
+components allowed to.
+
+In light mode `warning` binds `yellow-700` and `medium` binds `orange-600` rather than the
+500s, so both clear 3:1 against the page. See `foundations/color.md`.
+
+## Anti-patterns
+
+- ❌ `status="critical"` → that is severity (will not compile).
+- ❌ Binding `--vela-signal-severity-*` to the dot → wrong taxonomy.
+- ❌ A bare dot in a table with no label and no header context.
+- ❌ Six or seven states → the set is closed at five.
+- ❌ `--vela-radius-full` borrowed for other components.

package/guidelines/components/tabs.md

@@ -0,0 +1,71 @@
+# Tabs
+
+Navigate between **different** content panels.
+
+## When to use Tabs (vs. something else)
+
+- Different content sections (Alerts / Assets / Audit) → **Tabs**.
+- The **same** dataset rendered differently (Grid / Dashboard / Chart) → **View Switcher**,
+  which is **not in this kit**. Flag the gap; do not substitute Tabs. If only the
+  *presentation* of one dataset changes, it is not Tabs.
+- Sequential steps → a Wizard, not Tabs.
+- More than ~7 panels → reconsider the information architecture.
+
+## Composition
+
+```tsx
+<Tabs defaultValue="alerts" onValueChange={setView}>
+  <Tabs.List aria-label="Views">
+    <Tabs.Trigger value="alerts" count={12}>Alerts</Tabs.Trigger>
+    <Tabs.Trigger value="assets">Assets</Tabs.Trigger>
+    <Tabs.Trigger value="audit" disabled>Audit</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Panel value="alerts">…</Tabs.Panel>
+  <Tabs.Panel value="assets">…</Tabs.Panel>
+</Tabs>
+```
+
+| Part | Prop | Type | Notes |
+|---|---|---|---|
+| `Tabs` | `defaultValue` | `string` | **Required.** |
+| | `value` / `onValueChange` | `string` / `(v) => void` | Controlled mode. |
+| | `size` | `"regular" \| "large"` | **These two only.** |
+| `Tabs.List` | `aria-label` | `string` | **Required.** |
+| `Tabs.Trigger` | `value` | `string` | Must match a Panel. |
+| | `count` | `number` | Optional numeric badge. |
+| | `disabled` | `boolean` | Skipped by arrow-key navigation. |
+| `Tabs.Panel` | `value` | `string` | Must match a Trigger. |
+
+## Hard constraints
+
+- **`Tabs.List` requires `aria-label`.** An unnamed tablist is unnavigable by screen reader,
+  so the type makes it impossible.
+- **Parts must be used inside `<Tabs>`.** They throw a named error otherwise, rather than
+  rendering something silently broken.
+- **Only the active panel renders.** Do not rely on hidden panels holding DOM state.
+- Controlled and uncontrolled are exclusive.
+
+## Token bindings
+
+Trigger rest `--vela-text-de-emphasized`; hover `--vela-text-default`; selected
+`--vela-text-link` with a 2px `--vela-border-active` underline. List rule
+`--vela-border-subtle`.
+
+## Accessibility
+
+This is the reason Tabs is more than a styled list:
+
+- Correct roles throughout: `tablist` / `tab` / `tabpanel`, with `aria-selected`,
+  `aria-controls` and `aria-labelledby` wired both ways.
+- **Roving tabindex** — the whole tablist is one Tab stop; Left/Right move between tabs and
+  Home/End jump to the ends. Disabled tabs are skipped, and the list wraps.
+- The panel is focusable so keyboard users land in the content after activating a tab.
+
+## Anti-patterns
+
+- ❌ Tabs for the same dataset in a different view → View Switcher.
+- ❌ `<Tabs.List>` without `aria-label` → will not compile.
+- ❌ Buttons in a `<div>` with click handlers → no roles, no keyboard, no announcement.
+- ❌ Every tab tabbable → use the roving tabindex the component already implements.
+- ❌ Tabs as page navigation → use real links so URLs work.
+- ❌ Keeping hidden panels mounted to preserve form state → lift the state instead.

package/guidelines/components/toggle.md

@@ -0,0 +1,53 @@
+# Toggle
+
+A binary setting that takes effect **immediately**. No Save step.
+
+## When to use Toggle
+
+- Notifications on/off, dark mode, "enable this rule" → **Toggle**.
+- Records intent until a Save click (accept terms, pick scope in a form) → **Checkbox**,
+  which is not in this kit. Flag the gap rather than substituting a Toggle.
+- More than two states → not a Toggle.
+
+## Props
+
+```tsx
+<Toggle label="Email alerts" checked={on} onChange={setOn} />
+```
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | — | **Required.** A switch with no name is unusable by screen reader. |
+| `checked` | `boolean` | — | Controlled. Omit for uncontrolled. |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial state. |
+| `onChange` | `(checked: boolean) => void` | — | Receives the **next** value. |
+| `disabled` | `boolean` | `false` | |
+| `labelPosition` | `"right" \| "left"` | `"right"` | |
+| `size` | `"tiny" \| "regular"` | `"regular"` | **These two only.** |
+
+## Hard constraints
+
+- **`label` is required and is a `string`.** Not optional, not `ReactNode`. The type system
+  makes an unlabelled switch impossible.
+- Controlled and uncontrolled are exclusive: pass `checked` **or** `defaultChecked`.
+- The change is immediate. Never pair a Toggle with a Save button that gates it.
+
+## Token bindings
+
+Track off `--vela-toggle-off-bg`; on `--vela-toggle-on-bg`; knob `--vela-toggle-knob`;
+disabled track `--vela-border-inactive`. Track radius is `--vela-radius-full` — one of only
+two components allowed to use it.
+
+## Accessibility
+
+- Renders a native `<button role="switch">` with `aria-checked`.
+- Enter and Space activate it; it is in the tab order.
+- The visible label is wired via `aria-labelledby` and is itself clickable.
+- Motion respects `prefers-reduced-motion`.
+
+## Anti-patterns
+
+- ❌ A Toggle behind a Save button → that is a Checkbox.
+- ❌ `<Toggle />` with no label → will not compile.
+- ❌ Toggles for more than two states.
+- ❌ A custom `<div>` with a click handler → loses role, keyboard and announcement.

package/guidelines/foundations/color.md

@@ -0,0 +1,67 @@
+# Foundation: Colour
+
+Two layers: **primitives** (raw scale) and **semantics** (role-named, resolving to
+primitives). **Always bind semantics.** Primitives exist so semantics can be re-pointed for
+theming; binding one directly defeats that and breaks dark mode.
+
+- ✅ `color: var(--vela-text-default)` — survives re-skinning
+- ⚠️ `color: var(--vela-grey-700)` — primitive; only when no semantic covers the role
+- ❌ `color: #191d1f` — never raw hex
+
+## Primitives (reference only)
+
+Families: `grey` (50–950), `primary` (300–600), `blue` (100–950), `green` (100–950),
+`red` (100–950), `critical` (100–950), `yellow` (100–950), `orange` (100–950),
+plus `--vela-black` (#191d1f, not pure black) and `--vela-white`.
+
+## Three separate status taxonomies — keep them apart
+
+Vela deliberately separates **severity** (events), **risk** (scoring), and **status** (the
+health dot). Do not interchange them. There is no "critical risk", no "high severity", and
+the dot states are neither.
+
+### Severity — 6 levels
+
+`success` · `info` · `warning` · `minor` · `major` · `critical`
+
+Every level defines a complete row: `--vela-bg-severity-*`, `--vela-border-severity-*`,
+`--vela-signal-severity-*`, `--vela-icon-severity-*`, `--vela-text-severity-*`,
+`--vela-border-severity-*-indicator`. **No cell is missing.** If a token you expect does not
+resolve, you have the wrong taxonomy, not a gap.
+
+### Risk — 3 levels
+
+`low` · `medium` · `high` — same six roles per level, prefixed `--vela-*-risk-*`.
+
+### Status — 5 dot fills
+
+`--vela-signal-status-` + `unknown` | `healthy` | `warning` | `medium` | `unhealthy`.
+One row, five swatches, no other roles. Status Indicator only.
+
+## Contrast is a constraint, not an aspiration
+
+Every foreground/background pair the kit ships is asserted against WCAG 2.1 AA in
+`src/styles/contrast.test.ts` — 4.5:1 for text, 3:1 for UI boundaries and non-text signals,
+**in both themes**. Run `npm run contrast` for the report.
+
+Consequences you will notice, all deliberate:
+
+- `--vela-btn-destructive-bg` is `red-700` (6.57:1), **not** `red-500`. Red-500 behind a white
+  label is 4.08:1 and fails AA. Do not "fix" it back to the signal colour.
+- `--vela-text-de-emphasized` is `grey-600` (4.90:1), not `grey-500` (3.47:1).
+- `--vela-text-severity-success` is `green-800` (6.68:1). `green-700` would technically pass at
+  4.87:1; green-800 is kept for headroom, so a future palette tweak cannot silently cross the
+  line. That is a judgement call, not a compliance requirement — recorded here as one.
+- Status dots use `yellow-700` (4.07:1) and `orange-600` (3.80:1), not the 500s, which sit at
+  2.59:1 and 2.78:1 on white.
+- Tightest shipped pair: the input border at 3.29:1 against a 3:1 minimum. Anything you add
+  below that is a regression.
+
+If you add a pair, add it to `PAIRS` in `scripts/contrast-core.mjs`. An unasserted pair is
+an unverified claim.
+
+## Both themes are real
+
+Dark mode re-points semantics only — no primitive is redefined, and a test fails the build if
+a raw hex appears in the dark block. Anything you write must therefore bind semantics, or it
+will simply not respond to the theme.

package/guidelines/foundations/radius.md

@@ -0,0 +1,17 @@
+# Foundation: Radius
+
+Four tokens, each with a scope. Using one outside its scope is drift.
+
+| Token | Value | Scope |
+|---|---|---|
+| `--vela-radius-3` | 3px | Small inner elements (dismiss buttons, inline chips) |
+| `--vela-radius-4` | 4px | **The default for every component** |
+| `--vela-radius-8` | 8px | Modal / dialog containers only |
+| `--vela-radius-12` | 12px | Top-level side panel outer edge only |
+| `--vela-radius-full` | 9999px | Status Indicator dots and the Toggle track only |
+
+## Anti-patterns
+
+- ❌ Pill-shaped buttons (`border-radius: 999px`) → buttons are `--vela-radius-4`.
+- ❌ `--vela-radius-full` on anything but a status dot or a toggle track.
+- ❌ `--vela-radius-8` on a card → cards are `--vela-radius-4`; 8 is for modals.

package/guidelines/foundations/sizing.md

@@ -0,0 +1,35 @@
+# Foundation: Sizing
+
+## Control heights
+
+| Token | Value | Used by |
+|---|---|---|
+| `--vela-control-height-24` | 24px | Button `tiny` |
+| `--vela-control-height-25` | 25px | Input `tiny` |
+| `--vela-control-height-26` | 26px | Input `regular` |
+| `--vela-control-height-35` | 35px | Button `regular`, Input `large` |
+| `--vela-control-height-40` | 40px | Button `large` |
+| `--vela-control-height-48` | 48px | Reserved |
+| `--vela-control-height-60` | 60px | Button `huge` |
+
+**Button and the input family do not share a height ramp.** A `regular` Button is 35px; a
+`regular` Input is 26px. Placing them on one row requires deliberate alignment — this is a
+known property of the system, not a bug to normalise away.
+
+## Icon sizes
+
+| Token | Value | Used by |
+|---|---|---|
+| `--vela-icon-12` | 12px | Button `tiny` |
+| `--vela-icon-16` | 16px | Button `regular`/`large`/`huge`, alert icons |
+| `--vela-icon-20` | 20px | Dismiss controls |
+| `--vela-icon-24` | 24px | Reserved |
+
+**Button icons do not scale past 16px.** 12 at tiny, 16 everywhere else. `huge` is 60px tall
+with a 16px icon — that is correct.
+
+## Anti-patterns
+
+- ❌ `--vela-control-height-48` for Button `huge` → huge is 60px.
+- ❌ `--vela-icon-20` or `-24` inside a Button → 12 or 16 only.
+- ❌ Fixed button widths → buttons hug their content.

package/guidelines/foundations/spacing.md

@@ -0,0 +1,28 @@
+# Foundation: Spacing
+
+A 5px-based scale. **`25` exists; `50` does not** — this is intentional, not an omission.
+
+| Token | Value | Typical use |
+|---|---|---|
+| `--vela-space-5` | 5px | Icon-to-label gap |
+| `--vela-space-10` | 10px | Control padding, tight stacks |
+| `--vela-space-15` | 15px | Default button padding, form gaps |
+| `--vela-space-20` | 20px | Section padding, tab gaps |
+| `--vela-space-25` | 25px | Wide inner padding |
+| `--vela-space-30` | 30px | Large button padding |
+| `--vela-space-40` | 40px | Section separation |
+| `--vela-space-60` | 60px | Page-level rhythm |
+| `--vela-space-80` | 80px | Page-level rhythm |
+
+## Rules
+
+- Values already carry `px`. `padding: var(--vela-space-10)` — never `calc(... * 1px)`.
+- **Do not interpolate.** There is no 35, no 50, no 70. If a layout seems to need one, you
+  are probably compensating for a wrong control height.
+- Use `gap` on a flex/grid parent rather than margins on children.
+
+## Anti-patterns
+
+- ❌ `padding: 12px` → use `--vela-space-10` or `--vela-space-15`.
+- ❌ `--vela-space-50` → does not exist; the scale skips it.
+- ❌ Margin-bottom stacks → use `gap`.

package/guidelines/foundations/typography.md

@@ -0,0 +1,34 @@
+# Foundation: Typography
+
+**Open Sans** for all UI text (Light 300, Regular 400, SemiBold 600).
+**Oswald** for large stat/number displays only. Both have system fallbacks.
+
+## The scale
+
+| Role | Size / Weight / Line-height | Class |
+|---|---|---|
+| H1 | 32 / 300 / 42 | `.vela-h1` |
+| H2 | 24 / 300 / 33 | `.vela-h2` |
+| H3 | 20 / 300 / 27 | `.vela-h3` |
+| H4 | 16 / 400 / 24 | `.vela-h4` |
+| H5 | 14 / 600 / 21 | `.vela-h5` |
+| H6 | 12 / 600 / 18 | `.vela-h6` |
+| Body | 14 / 400 / 21 | `.vela-body` |
+| Meta | 12 / 400 / 18, +0.3 tracking | `.vela-meta` |
+
+Note the weight inversion: H1–H3 are **Light 300** and get their prominence from size;
+H5–H6 are **SemiBold 600** and get theirs from weight. Do not "correct" H1 to bold.
+
+## Rules
+
+- Use the class that matches the **role**, not the one that matches the size you want.
+- Button labels are **Regular 400 at every size** — never SemiBold, never Bold.
+- Button labels are Title Case and verb-first: "Save Changes", not "Information".
+- Each size is a triple. Never take a size without its line-height.
+
+## Anti-patterns
+
+- ❌ `font-size: 15px` outside a Button `large` → not on the scale.
+- ❌ A bold H1 → H1 is Light 300.
+- ❌ SemiBold button labels → Regular 400 at every size.
+- ❌ Setting `font-family`/`font-size`/`line-height` by hand → use the class or the tokens.

package/guidelines/llms.txt

@@ -0,0 +1,33 @@
+# Vela Design System
+
+> A token-first React component kit. Two-layer colour architecture (primitives -> semantics),
+> three deliberately separate status taxonomies, full light and dark theming, zero runtime
+> dependencies. Every design constraint below is enforced by the TypeScript types, not by review.
+
+Read `overview.md` first: it maps a user need to a component and lists the choices agents
+most often get wrong. Then read the per-component file before generating any markup.
+
+## Hard rules (apply everywhere)
+- Bind SEMANTIC tokens (`var(--vela-text-default)`). Never a primitive (`--vela-grey-700`), never raw hex.
+- Numeric tokens already carry their unit. Use `var(--vela-space-10)`, never `calc(var(--vela-space-10) * 1px)`.
+- Prop sets are CLOSED. If a value is not in the component's Props table, it does not exist.
+- Never invent a component. If nothing fits, say so and name the closest match.
+- Severity, Risk and Status are three different taxonomies. Never cross them.
+
+## Docs
+- [Component catalogue and disambiguations](overview.md)
+- [Install and theming](setup.md)
+- [Token naming and lookup](tokens.md)
+- [Colour](foundations/color.md)
+- [Spacing](foundations/spacing.md)
+- [Sizing](foundations/sizing.md)
+- [Radius](foundations/radius.md)
+- [Typography](foundations/typography.md)
+
+## Components
+- [Button](components/button.md)
+- [Toggle](components/toggle.md)
+- [Input](components/input.md)
+- [Contextual Alert](components/contextual-alert.md)
+- [Status Indicator](components/status-indicator.md)
+- [Tabs](components/tabs.md)