@omkarux/vela 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] — 2026-09-10
+
+### Fixed
+- **The release workflow could never publish.** It triggered only on pushes to `main` and on pull
+  requests, while the publish job gated on `refs/tags/v*` — so a tag push matched no trigger and
+  the job never ran. Tags are now listed explicitly.
+- Trusted publishing requires npm >= 11.5.1; Node 22 ships npm 10.x. The publish job now upgrades
+  npm first. Without it npm falls back to looking for a token and fails with `ENEEDAUTH`, which
+  reads like a credentials problem rather than a version one.
+
+- **`scripts/verify-pack.mjs` crashed on `npm pack --json`.** It assumed an array and indexed
+  `[0].filename` directly, which threw a bare `TypeError` when npm returned a different shape from
+  inside a lifecycle script. It now parses defensively and reports the actual output.
+- The publish job no longer re-runs the full gate. `prepublishOnly` fired inside `npm publish`,
+  repeating work the `verify` job had already done and putting a second failure surface inside the
+  publish step — which is what broke the first tagged release. The gate runs once, in `verify`.
+
+This release exists to prove the pipeline end to end. The tarball contents are unchanged from
+0.3.0 — but this one was built and published by CI from a git tag, with a provenance attestation
+tying it to the commit, rather than by hand from a laptop.
+
+## [0.3.0] — 2026-09-10
+
+### Added
+- **A `## Figma mapping` section in every component spec.** The contract now works in both
+  directions: each spec states which Figma variant property corresponds to which code prop, and —
+  more usefully — which behaviour has **no Figma expression at all** (Tabs' roving tabindex,
+  Contextual Alert's live-region politeness, Button's `disabled` state).
+- `llms.txt` now points at the companion Figma library and states the relationship plainly: the
+  library is *compiled from* this contract, not the source of it.
+
+### Companion Figma library
+`Vela Design System` — 223 variables across 4 collections mirroring the CSS architecture 1:1
+(Primitives / Color with Light+Dark / Sizing / Typography), 15 text styles, and 6 component sets
+totalling 62 variants. Every variable carries its `var(--vela-*)` name as Dev Mode code syntax.
+
+Three token gaps the Figma build surfaced, recorded rather than hidden:
+- Toggle track and knob geometry is literal in both CSS and Figma, not tokenised.
+- Status Indicator dot diameters (10px / 8px) are likewise literal.
+- Code Connect could not be wired: it requires an Organization or Enterprise Figma plan. The
+  component API is written into each component's Figma description instead, which surfaces in
+  Inspect on any plan.
+
 ## [0.2.0] — 2026-09-09
 
 ### Changed

package/guidelines/components/button.md

@@ -88,6 +88,25 @@ Label weight is **Regular 400 at every size**.
   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.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Button`. The component set is 24 variants:
+`Variant` (3) x `Appearance` (2) x `Size` (4), plus an `Icon` boolean property.
+
+| Figma property | Code prop | Notes |
+|---|---|---|
+| `Variant` | `variant` | primary / standard / destructive |
+| `Appearance` | `appearance` | filled / hollow |
+| `Size` | `size` | tiny / regular / large / huge |
+| `Icon` (boolean) | `icon` | Toggles the left icon layer. Boolean, not a variant axis — it changes visibility, not colour. |
+
+**`disabled` has no Figma axis, on purpose.** It is a *state*, not a variant — the Props table
+above says so, and adding it would push the matrix past 30 combinations for no gain.
+
+**`appearance="text-link"` is a separate component set**, not a third value of `Appearance`.
+That mirrors the type: `ButtonProps` is a discriminated union, and text-link is its own member
+with a narrower `size` and `icon?: never`. One union member, one component set.
+
 ## Anti-patterns
 
 - ❌ Two primary filled buttons on one page.

package/guidelines/components/contextual-alert.md

@@ -49,6 +49,20 @@ Never mix a severity background with a risk text colour.
 - Live-region politeness is derived from severity, as above.
 - The dismiss control is a real button with an accessible name.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Contextual Alert`. Six variants, one per severity,
+plus a `Dismissible` boolean.
+
+| Figma property | Code prop |
+|---|---|
+| `Severity` | `severity` |
+| `Dismissible` | `onDismiss` — presence of the handler, not a flag |
+
+The Figma icons are **placeholder glyphs** (circle / triangle / octagon). Production swaps in the
+real icons from `src/lib/icons.tsx`. The live-region politeness (`role="alert"` for major and
+critical, `role="status"` otherwise) is derived from severity in code and has no Figma expression.
+
 ## Anti-patterns
 
 - ❌ `severity="high"` or `"error"` → not in the taxonomy (will not compile).

package/guidelines/components/input.md

@@ -57,6 +57,21 @@ These are the **input family** heights and do not match Button's ramp. See
 - Error state sets `aria-invalid` and the message is announced via `role="alert"`.
 - The `*` is `aria-hidden`; `required` carries the semantics.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Input`. Twelve variants: `Size` (3) x `State` (4).
+
+| Figma property | Code prop |
+|---|---|
+| `Size` | `size` |
+| `State=default` | — |
+| `State=focus` | `:focus-visible`, not a prop |
+| `State=error` | `error` — a **message string**, not a boolean |
+| `State=disabled` | `disabled` |
+
+The Figma variants show the label, field and message rows together because the code component
+renders all three; a field mocked without its label will not match what ships.
+
 ## Anti-patterns
 
 - ❌ Placeholder as the label.

package/guidelines/components/status-indicator.md

@@ -39,6 +39,19 @@ 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`.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Status Indicator`. Ten variants: `Status` (5) x
+`Size` (2), plus a `Label` boolean.
+
+| Figma property | Code prop |
+|---|---|
+| `Status` | `status` |
+| `Size` | `size` |
+| `Label` (boolean) | `label` — hiding it in Figma means the code must supply the `aria-label` fallback |
+
+Dot diameters (10px / 8px) are **literal in both Figma and CSS**, not tokenised. Known gap.
+
 ## Anti-patterns
 
 - ❌ `status="critical"` → that is severity (will not compile).

package/guidelines/components/tabs.md

@@ -61,6 +61,23 @@ This is the reason Tabs is more than a styled list:
   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.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Tabs`. The component set is a single **Tab**, not the
+whole tablist: six variants, `State` (3) x `Size` (2), plus a `Count` boolean. Compose a tablist
+by placing Tab instances in a row.
+
+| Figma property | Code equivalent |
+|---|---|
+| `State=selected` | the active `value` on `<Tabs>` |
+| `State=disabled` | `disabled` on `<Tabs.Trigger>` |
+| `Size` | `size` on `<Tabs>` |
+| `Count` (boolean) | `count` on `<Tabs.Trigger>` |
+
+**The keyboard behaviour has no Figma expression.** Roving tabindex, arrow navigation, Home/End,
+and skipping disabled tabs exist only in code — which is exactly why the Figma library is not the
+source of truth for this component. The spec is.
+
 ## Anti-patterns
 
 - ❌ Tabs for the same dataset in a different view → View Switcher.

package/guidelines/components/toggle.md

@@ -45,6 +45,20 @@ two components allowed to use it.
 - The visible label is wired via `aria-labelledby` and is itself clickable.
 - Motion respects `prefers-reduced-motion`.
 
+## Figma mapping
+
+Library file: **Vela Design System** → page `Toggle`. Four variants: `State` (off/on) x `Size`
+(regular/tiny), plus a `Label text` text property.
+
+| Figma property | Code prop |
+|---|---|
+| `State` | `checked` / `defaultChecked` |
+| `Size` | `size` |
+| `Label text` | `label` |
+
+Track and knob geometry (34x20 / 26x15, knob 16 / 11) is **literal in both Figma and CSS** —
+it is not tokenised. That is a known gap, recorded rather than hidden.
+
 ## Anti-patterns
 
 - ❌ A Toggle behind a Save button → that is a Checkbox.

package/guidelines/llms.txt

@@ -14,6 +14,14 @@ most often get wrong. Then read the per-component file before generating any mar
 - 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.
 
+## Figma
+
+A matching Figma library exists: **Vela Design System**. It is *compiled from this contract*, not
+the source of it — 223 variables and 6 component sets mirroring the token architecture 1:1, with
+every variable carrying its `var(--vela-*)` name for Dev Mode. Each component's per-file
+`## Figma mapping` section states which Figma property corresponds to which prop, and which
+behaviour has no Figma expression at all.
+
 ## Docs
 - [Component catalogue and disambiguations](overview.md)
 - [Install and theming](setup.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omkarux/vela",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A token-first React component kit: two-layer color architecture, separate severity and risk taxonomies, full light and dark theming, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",