@omkarux/vela 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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,26 @@ npm run contrast   # WCAG report for both themes
 npm run verify     # typecheck + tests + build + pack-and-consume gate
 ```
 
+## 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.4.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",