@omkarux/vela 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-09-10
+
+### Added
+- **A single token source.** `tokens/vela.tokens.json` (W3C Design Tokens 2025.10) now holds every
+  value once. `src/styles/tokens.*.css` are generated from it and were proven byte-identical to the
+  hand-written files before the switch. `npm run tokens:check` runs in the gate and fails if the
+  CSS is edited directly.
+- **Figma sync.** `npm run tokens:figma` generates a Plugin API script that creates-or-updates every
+  variable in the library by name — values per mode, aliases, scopes, descriptions and the
+  `var(--vela-*)` code syntax. Idempotent: 0 created / 223 updated on its first run against the live
+  file. This closes the gap where the Figma library was a one-time export that would drift from
+  the code. The REST route was not an option: writing variables needs an Enterprise plan.
+- The JSON ships in the package as `@omkarux/vela/tokens.json` for other stacks and tools
+  (Style Dictionary, Tokens Studio, Terrazzo all read the format).
+- 5 tests guard the pipeline: every CSS declaration has a source token and vice versa, no
+  dangling alias, primitives hold raw values and semantics hold aliases only, every token carries
+  its Figma name, and regenerating the CSS changes nothing.
+
+## [0.4.0] — 2026-09-10
+
+### Added
+- **Guidance for using the system on a stack that isn't React.** `guidelines/setup.md` and the
+  README now state plainly which layers travel and which don't: the tokens and the specs port
+  unchanged, the components do not. `npm i @omkarux/vela` followed by importing only
+  `tokens.css` gives an Angular, Vue, Svelte or server-rendered app the full palette, both
+  themes and the whole scale with no React in its dependency tree.
+- `llms.txt` now tells a coding agent the specs are implementation-independent, so an agent
+  generating Angular follows every rule here and translates only the syntax.
+
+### Changed
+- Stopped describing this as a "React component kit" in the README, the npm description and
+  `llms.txt`. It was accurate about the package and misleading about the method — React is the
+  boundary of *this implementation*, not of the approach, and conflating the two undersells the
+  contract, which is the part that actually ports.
+
 ## [0.3.1] — 2026-09-10
 
 ### Fixed

package/README.md

@@ -1,7 +1,8 @@
 # Vela
 
-A token-first React component kit. Six components, two themes, zero runtime dependencies —
-and every design rule in the documentation is enforced by the TypeScript compiler.
+A token-first design system. The tokens and the component specs are framework-agnostic;
+this repository is a **React implementation** of them. Six components, two themes, zero runtime
+dependencies — and every design rule in the documentation is enforced by the TypeScript compiler.
 
 ```bash
 npm install @omkarux/vela
@@ -100,6 +101,43 @@ npm run contrast   # WCAG report for both themes
 npm run verify     # typecheck + tests + build + pack-and-consume gate
 ```
 
+## Editing tokens — one source, three targets
+
+`tokens/vela.tokens.json` is the only place a value is written. It uses the W3C Design Tokens
+format (2025.10), ships inside the package as `@omkarux/vela/tokens.json`, and everything else is
+generated from it:
+
+```bash
+npm run tokens          # → src/styles/tokens.light.css + tokens.dark.body.css
+npm run tokens:figma    # → a Plugin API script that creates-or-updates every Figma variable
+npm run tokens:check    # fails if the CSS was hand-edited instead of the JSON (runs in CI)
+```
+
+Figma's REST API only lets Enterprise plans write variables, so the Figma half is a generated
+script run inside the file (through the Figma MCP or the Scripter plugin). It looks each variable
+up by collection and name, so re-running never duplicates: the first run against the live library
+reported 0 created / 223 updated, then created the 11 numeric tokens Figma had never had.
+
+## Using it on another stack
+
+Worth being precise about what travels and what doesn't:
+
+| Layer | Ports? |
+|---|---|
+| **Tokens** (`dist/tokens.css`) | **Entirely.** Plain CSS custom properties — Angular, Vue, Svelte, Rails, plain HTML. From the same source you could emit Swift, Kotlin or XML for native. |
+| **The contract** (`guidelines/`) | **Entirely.** Intent, closed prop sets, token bindings, accessibility, anti-patterns. Only the code samples are React-shaped. |
+| **Components** (`dist/index.js`) | **No.** One implementation per framework, by definition. |
+| **The contrast audit** (`npm run contrast`) | **Entirely.** It parses CSS and knows nothing about React. |
+
+So on Angular you would take `tokens.css` and `guidelines/` unchanged, and write the components
+against your own idioms — standalone components, signals, `ControlValueAccessor` for form controls.
+The closed prop sets become union input types with `strictTemplates` enabled, which buys most of
+what the discriminated unions buy here.
+
+This is not a limitation to work around. If an organisation runs more than one framework, no
+framework's components can be the source of truth for the others — **the only thing that can be
+shared is the contract**, which is the argument this repository exists to make.
+
 ## Scope
 
 Six components, chosen to exercise every foundation and both status taxonomies. Not yet

package/guidelines/llms.txt

@@ -1,8 +1,13 @@
 # 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.
+> A token-first design system. 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.
+>
+> THESE SPECS ARE FRAMEWORK-AGNOSTIC. The published package is a React implementation of them, and
+> the code samples below are React — but the tokens, the closed prop sets, the taxonomies and the
+> accessibility rules hold for any implementation. If you are generating for Angular, Vue or
+> Svelte, follow every rule here and translate only the syntax.
 
 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.

package/guidelines/setup.md

@@ -59,6 +59,20 @@ fallbacks in the font stack, so the kit degrades rather than breaks if you do no
 
 ## Framework
 
-React 18.3+ / 19. Components are plain functional components consuming `--vela-*` tokens.
-There is no CSS-in-JS runtime, no Tailwind requirement, and no icon-library dependency —
-the token layer is plain CSS custom properties and works in any framework.
+**This package:** React 18.3+ / 19. Plain functional components consuming `--vela-*` tokens.
+No CSS-in-JS runtime, no Tailwind requirement, no icon-library dependency.
+
+**Any other framework:** the token layer and the specs port unchanged; the components do not.
+
+```bash
+npm install @omkarux/vela   # then import only the tokens
+```
+```ts
+import '@omkarux/vela/tokens.css'
+```
+
+That gives an Angular, Vue, Svelte or server-rendered app the full two-layer palette, both themes,
+the spacing and sizing scales and the type ramp — with no React in the dependency tree. Build the
+components against your own framework's idioms and hold them to `guidelines/`, which is written to
+be implementation-independent. On Angular, the closed prop sets become union input types with
+`strictTemplates` enabled; that buys most of what the discriminated unions buy in React.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@omkarux/vela",
-  "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.",
+  "version": "0.5.0",
+  "description": "A token-first design system: framework-agnostic tokens and component specs with a React implementation. Two-layer color architecture, separate severity and risk taxonomies, light and dark theming, WCAG AA asserted in CI, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
   "author": "Omkar Khadamkar",
@@ -26,18 +26,23 @@
     "./styles.css": "./dist/vela.css",
     "./tokens.css": "./dist/tokens.css",
     "./guidelines/*": "./guidelines/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./tokens.json": "./tokens/vela.tokens.json"
   },
   "files": [
     "dist",
     "guidelines",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "tokens"
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && npm run build:js && npm run build:css",
+    "tokens": "node scripts/build-tokens.mjs",
+    "tokens:figma": "node scripts/sync-figma.mjs",
+    "tokens:check": "node scripts/build-tokens.mjs && git diff --exit-code -- src/styles/tokens.light.css src/styles/tokens.dark.body.css",
+    "build": "npm run clean && npm run tokens && npm run build:js && npm run build:css",
     "build:js": "vite build",
     "build:css": "node scripts/build-css.mjs",
     "predev": "npm run build:css",
@@ -48,7 +53,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "contrast": "node scripts/contrast-report.mjs",
-    "verify": "npm run typecheck && npm run test && npm run build && node scripts/verify-pack.mjs",
+    "verify": "npm run tokens:check && npm run typecheck && npm run test && npm run build && node scripts/verify-pack.mjs",
     "prepublishOnly": "npm run verify"
   },
   "peerDependencies": {

package/tokens/layout.dark.txt

@@ -0,0 +1,152 @@
+  /* ============================================================================
+     DARK THEME
+     Note what is NOT here: primitives. Not one raw hex is redefined below.
+     Dark mode is achieved entirely by re-pointing semantic tokens onto a
+     different part of the same scale. That is the return on the two-layer
+     architecture — and the reason components never bind primitives directly.
+     Contrast ratios are asserted in src/styles/contrast.test.ts.
+     ============================================================================ */
+  color-scheme: dark;
+
+  /* ---- Surface ---- */
+  @bg-global
+  @bg-container
+  @bg-raised
+  @bg-hover
+  @bg-tooltip
+  @bg-inactive
+  @bg-selected
+  @primary-tint
+  @primary-active-bg
+
+  /* ---- Border ---- */
+  @border-default
+  @border-subtle
+  @border-active
+  @border-inactive
+  @border-action
+
+  /* ---- Text ---- */
+  @text-default
+  @text-heading
+  @text-de-emphasized
+  @text-inactive
+  @text-link
+  @text-on-brand
+  @text-on-tint
+  @text-error
+
+  /* ---- Icon ---- */
+  @icon-default
+  @icon-strong
+  @icon-selected
+  @icon-disabled
+  @icon-on-brand
+
+  /* ---- Button ---- */
+  @btn-primary-bg
+  @btn-primary-hover-bg
+  @btn-primary-border
+  @btn-primary-text
+  @btn-standard-bg
+  @btn-standard-hover-bg
+  @btn-standard-text
+  @btn-hollow-primary-text
+  @btn-hollow-primary-border
+  @btn-disabled-bg
+  @btn-disabled-text
+
+
+  @btn-destructive-bg
+  @btn-destructive-hover-bg
+  @btn-destructive-text
+  @btn-destructive-hollow-text
+  @btn-standard-border
+  @btn-hollow-hover-bg
+
+  /* ---- Form control ---- */
+  @control-bg
+  @control-border
+  @control-border-hover
+  @control-border-active
+  @control-border-error
+  @control-bg-disabled
+  @control-placeholder
+  @toggle-off-bg
+  @toggle-on-bg
+  @toggle-knob
+
+  /* ---- Severity (6) ---- */
+  @bg-severity-success
+  @border-severity-success
+  @signal-severity-success
+  @icon-severity-success
+  @text-severity-success
+  @border-severity-success-indicator
+
+  @bg-severity-info
+  @border-severity-info
+  @signal-severity-info
+  @icon-severity-info
+  @text-severity-info
+  @border-severity-info-indicator
+
+  @bg-severity-warning
+  @border-severity-warning
+  @signal-severity-warning
+  @icon-severity-warning
+  @text-severity-warning
+  @border-severity-warning-indicator
+
+  @bg-severity-minor
+  @border-severity-minor
+  @signal-severity-minor
+  @icon-severity-minor
+  @text-severity-minor
+  @border-severity-minor-indicator
+
+  @bg-severity-major
+  @border-severity-major
+  @signal-severity-major
+  @icon-severity-major
+  @text-severity-major
+  @border-severity-major-indicator
+
+  @bg-severity-critical
+  @border-severity-critical
+  @signal-severity-critical
+  @icon-severity-critical
+  @text-severity-critical
+  @border-severity-critical-indicator
+
+  /* ---- Risk (3) ---- */
+  @bg-risk-low
+  @border-risk-low
+  @signal-risk-low
+  @icon-risk-low
+  @text-risk-low
+  @border-risk-low-indicator
+
+  @bg-risk-medium
+  @border-risk-medium
+  @signal-risk-medium
+  @icon-risk-medium
+  @text-risk-medium
+  @border-risk-medium-indicator
+
+  @bg-risk-high
+  @border-risk-high
+  @signal-risk-high
+  @icon-risk-high
+  @text-risk-high
+  @border-risk-high-indicator
+
+  /* ---- Status (5 dots) ---- */
+  @signal-status-unknown
+  @signal-status-healthy
+  @signal-status-warning
+  @signal-status-medium
+  @signal-status-unhealthy
+
+  /* ---- Focus ---- */
+  @focus-ring-color

package/tokens/layout.light.txt

@@ -0,0 +1,293 @@
+/* ============================================================================
+   VELA — Design tokens
+   Two layers: primitives (raw scale values) and semantics (role-named).
+   Always bind to semantics. Primitives exist so semantics can be re-pointed
+   for theming — binding a primitive directly defeats the entire architecture.
+   Numeric tokens carry their unit. Use them directly; never calc(... * 1px).
+   ============================================================================ */
+
+:root {
+  color-scheme: light;
+
+  /* ---- Primitives: neutral ---- */
+  @black
+  @white
+  @grey-50
+  @grey-100
+  @grey-200
+  @grey-300
+  @grey-400
+  @grey-500
+  @grey-600   /* AA-safe de-emphasized text on white */
+  @grey-700
+  @grey-800
+  @grey-850
+  @grey-900
+  @grey-950
+
+  /* ---- Primitives: brand / blue ---- */
+  @primary-300
+  @primary-400
+  @primary-500
+  @primary-600
+  @blue-100
+  @blue-150
+  @blue-300
+  @blue-500
+  @blue-700
+  @blue-950
+
+  /* ---- Primitives: red / critical ---- */
+  @red-100
+  @red-300
+  @red-500
+  @red-700
+  @red-950
+  @critical-100
+  @critical-300
+  @critical-500
+  @critical-700
+  @critical-950
+
+  /* ---- Primitives: yellow / orange / green ---- */
+  @yellow-100
+  @yellow-300
+  @yellow-500
+  @yellow-600
+  @yellow-700
+  @yellow-800
+  @yellow-950
+  @orange-100
+  @orange-300
+  @orange-500
+  @orange-600 /* AA-safe status dot on white */
+  @orange-700
+  @orange-950
+  @green-100
+  @green-300
+  @green-500
+  @green-700
+  @green-800  /* AA-safe success text on green-100 */
+  @green-950
+
+  /* ---- Semantic: surface ---- */
+  @bg-global
+  @bg-container
+  @bg-raised
+  @bg-hover
+  @bg-tooltip
+  @bg-inactive
+  @bg-selected
+  @primary-tint
+  @primary-active-bg
+
+  /* ---- Semantic: border ---- */
+  @border-default
+  @border-subtle
+  @border-active
+  @border-inactive
+  @border-action
+
+  /* ---- Semantic: text ---- */
+  @text-default
+  @text-heading
+  @text-de-emphasized
+  @text-inactive
+  @text-link
+  @text-on-brand
+  @text-on-tint
+  @text-error
+
+  /* ---- Semantic: icon ---- */
+  @icon-default
+  @icon-strong
+  @icon-selected
+  @icon-disabled
+  @icon-on-brand
+
+  /* ---- Semantic: button ---- */
+  @btn-primary-bg
+  @btn-primary-hover-bg
+  @btn-primary-border
+  @btn-primary-text
+  @btn-standard-bg
+  @btn-standard-hover-bg
+  @btn-standard-text
+  @btn-hollow-primary-text
+  @btn-hollow-primary-border
+  @btn-disabled-bg
+  @btn-disabled-text
+
+
+  /* ---- Semantic: destructive button ----
+     NOTE: red-500 on white is 4.08:1 and fails WCAG AA for normal text.
+     Destructive filled therefore binds red-700 (6.57:1). This is a
+     deliberate divergence from a naive "use the signal color" mapping. */
+  @btn-destructive-bg
+  @btn-destructive-hover-bg
+  @btn-destructive-text
+  @btn-destructive-hollow-text
+  @btn-standard-border
+  @btn-hollow-hover-bg
+
+  /* ---- Semantic: form control ---- */
+  @control-bg
+  @control-border
+  @control-border-hover
+  @control-border-active
+  @control-border-error
+  @control-bg-disabled
+  @control-placeholder
+  @toggle-off-bg
+  @toggle-on-bg
+  @toggle-knob
+
+  /* ============================================================================
+     SEVERITY — 6 levels. Describes events and alerts.
+     Never interchange with Risk or Status. There is no "high severity".
+     Every level defines the full row: bg, border, signal, icon, text, indicator.
+     ============================================================================ */
+  @bg-severity-success
+  @border-severity-success
+  @signal-severity-success
+  @icon-severity-success
+  @text-severity-success
+  @border-severity-success-indicator
+
+  @bg-severity-info
+  @border-severity-info
+  @signal-severity-info
+  @icon-severity-info
+  @text-severity-info
+  @border-severity-info-indicator
+
+  @bg-severity-warning
+  @border-severity-warning
+  @signal-severity-warning
+  @icon-severity-warning
+  @text-severity-warning
+  @border-severity-warning-indicator
+
+  @bg-severity-minor
+  @border-severity-minor
+  @signal-severity-minor
+  @icon-severity-minor
+  @text-severity-minor
+  @border-severity-minor-indicator
+
+  @bg-severity-major
+  @border-severity-major
+  @signal-severity-major
+  @icon-severity-major
+  @text-severity-major
+  @border-severity-major-indicator
+
+  @bg-severity-critical
+  @border-severity-critical
+  @signal-severity-critical
+  @icon-severity-critical
+  @text-severity-critical
+  @border-severity-critical-indicator
+
+  /* ============================================================================
+     RISK — 3 levels. Describes scoring. There is no "critical risk".
+     ============================================================================ */
+  @bg-risk-low
+  @border-risk-low
+  @signal-risk-low
+  @icon-risk-low
+  @text-risk-low
+  @border-risk-low-indicator
+
+  @bg-risk-medium
+  @border-risk-medium
+  @signal-risk-medium
+  @icon-risk-medium
+  @text-risk-medium
+  @border-risk-medium-indicator
+
+  @bg-risk-high
+  @border-risk-high
+  @signal-risk-high
+  @icon-risk-high
+  @text-risk-high
+  @border-risk-high-indicator
+
+  /* ============================================================================
+     STATUS — 5 health states. Status Indicator dots only. Neither of the above.
+     ============================================================================ */
+  @signal-status-unknown
+  @signal-status-healthy
+  @signal-status-warning
+  @signal-status-medium
+  @signal-status-unhealthy
+
+  /* ---- Spacing: 5px base. 25 exists; 50 does not. ---- */
+  @space-5
+  @space-10
+  @space-15
+  @space-20
+  @space-25
+  @space-30
+  @space-40
+  @space-60
+  @space-80
+
+  /* ---- Icon sizes ---- */
+  @icon-12
+  @icon-16
+  @icon-20
+  @icon-24
+
+  /* ---- Control heights ---- */
+  @control-height-24
+  @control-height-25
+  @control-height-26
+  @control-height-35
+  @control-height-40
+  @control-height-48
+  @control-height-60
+
+  /* ---- Radius ---- */
+  @radius-3
+  @radius-4
+  @radius-8
+  @radius-12
+  @radius-full
+
+  /* ---- Typography: family & weight ---- */
+  @font-family-primary
+  @font-family-display
+  @font-weight-light
+  @font-weight-regular
+  @font-weight-semibold
+
+  /* ---- Typography: scale (size / weight / line-height triples) ---- */
+  @text-h1-size   --vela-text-h1-weight: 300; --vela-text-h1-line-height: 42px;
+  @text-h2-size   --vela-text-h2-weight: 300; --vela-text-h2-line-height: 33px;
+  @text-h3-size   --vela-text-h3-weight: 300; --vela-text-h3-line-height: 27px;
+  @text-h4-size   --vela-text-h4-weight: 400; --vela-text-h4-line-height: 24px;
+  @text-h5-size   --vela-text-h5-weight: 600; --vela-text-h5-line-height: 21px;
+  @text-h6-size   --vela-text-h6-weight: 600; --vela-text-h6-line-height: 18px;
+  @text-body-size --vela-text-body-weight: 400; --vela-text-body-line-height: 21px;
+  @text-meta-size --vela-text-meta-weight: 400; --vela-text-meta-line-height: 18px;
+  @text-meta-tracking
+
+  @text-button-tiny-size    --vela-text-button-tiny-line-height: 18px;
+  @text-button-regular-size --vela-text-button-regular-line-height: 21px;
+  @text-button-large-size   --vela-text-button-large-line-height: 22px;
+  @text-button-huge-size    --vela-text-button-huge-line-height: 24px;
+
+  @text-tab-size       --vela-text-tab-line-height: 19px;
+  @text-tab-large-size --vela-text-tab-large-line-height: 25px;
+
+  /* ---- Focus ---- */
+  @focus-ring-width
+  @focus-ring-offset
+  @focus-ring-color
+
+  /* ---- Motion (respects reduced-motion in components.css) ---- */
+  @duration-fast
+  @duration-base
+  @ease-standard
+}