@omkarux/vela 0.2.0

package/guidelines/overview.md

@@ -0,0 +1,48 @@
+# Component overview
+
+Pick the component by **what the user is doing**, not by what looks closest. Match the need
+below, then open the per-component file for props, tokens, and anti-patterns.
+
+## Catalogue
+
+| Component | Use it for | File |
+|---|---|---|
+| Button | Triggering an action (save, submit, delete, apply) | `components/button.md` |
+| Toggle | A binary setting that takes effect immediately | `components/toggle.md` |
+| Input | Single-line text entry | `components/input.md` |
+| Contextual Alert | Inline severity banner (success/info/warning/minor/major/critical) | `components/contextual-alert.md` |
+| Status Indicator | A health dot for one of five states | `components/status-indicator.md` |
+| Tabs | Navigate between different content panels | `components/tabs.md` |
+
+## Disambiguations (where AI usually picks wrong)
+
+- **Toggle vs Checkbox** — immediate effect (notifications on/off, dark mode) → **Toggle**.
+  Records intent until a Save click → **Checkbox**. Checkbox is not in this kit; flag the gap.
+- **Tabs vs View Switcher** — different content sections → **Tabs**. The *same* dataset
+  rendered differently (Grid / Dashboard / Chart) → **View Switcher**, which is not in this
+  kit. If only the presentation of one dataset changes, do not reach for Tabs.
+- **Contextual Alert vs Status Indicator** — an event the user must read → **Alert**.
+  An object's ongoing health, usually in a table cell → **Status Indicator**.
+- **Severity vs Risk vs Status** — three taxonomies, never interchangeable.
+  Severity (6 levels) describes *events*. Risk (3 levels) describes *scoring*. Status
+  (5 states) is the dot only. There is no "high severity" and no "critical risk".
+
+## If no component fits
+
+Do not invent one silently. State that the kit has no component for the need and pick the
+closest match while flagging the gap. Not yet specced: Checkbox, Radio, Dropdown List,
+Select List, Token Pill, Number Stepper, Text Area, Modal, Tooltip, Icon Button,
+Actions Dropdown, View Switcher. Flag rather than guess.
+
+## How each component file is structured
+
+Intent → When to use → Props (closed sets) → Hard constraints → Token bindings → Sizes →
+Typography → States → Accessibility → Anti-patterns. Read the Anti-patterns block.
+
+## Cross-cutting rules
+
+- **Bind semantic tokens**, never primitives or hex.
+- **Numeric tokens carry their unit** — use directly, never `calc(... * 1px)`.
+- **Closed prop sets** — never add variants, sizes or appearances beyond the Props table.
+- **Both themes are real.** Never hardcode a colour that only works in light mode.
+- **Colour is never the only signal** (WCAG 1.4.1) — always pair it with text or an icon.

package/guidelines/setup.md

@@ -0,0 +1,64 @@
+# Setup
+
+## Install
+
+```bash
+npm install @omkarux/vela
+```
+
+`react` and `react-dom` (v18.3 or v19) are peer dependencies — the consuming app supplies
+them. Vela has **zero runtime dependencies** of its own.
+
+## Import the stylesheet once, at the app root
+
+```tsx
+import '@omkarux/vela/styles.css'
+```
+
+The barrel deliberately does **not** import CSS, so the JS bundle carries no style side
+effects and the consuming app keeps control of style ordering and SSR.
+
+Need only the tokens (to style your own components against the same scale)?
+
+```tsx
+import '@omkarux/vela/tokens.css'
+```
+
+## Wrap your app
+
+```tsx
+<div className="vela-root">{children}</div>
+```
+
+Base typography, colour and focus treatment are scoped to `.vela-root` so the kit never
+fights a host app's global stylesheet. It can wrap the whole app or any subtree.
+
+## Theming
+
+Three states, handled for you:
+
+| Root attribute | Result |
+|---|---|
+| *(none)* | Follows the OS via `prefers-color-scheme` |
+| `data-theme="light"` | Forced light, even if the OS is dark |
+| `data-theme="dark"` | Forced dark, even if the OS is light |
+
+```tsx
+document.documentElement.setAttribute('data-theme', 'dark')
+```
+
+Dark mode is implemented by re-pointing semantic tokens onto a different part of the same
+scale — **no primitive is redefined and no raw hex appears in the dark block**. A test
+asserts this (`src/styles/contrast.test.ts`), because it is the property that makes a third
+theme cheap rather than a rewrite.
+
+## Fonts
+
+Open Sans (300/400/600) for UI text; Oswald for large stat displays. Both have system
+fallbacks in the font stack, so the kit degrades rather than breaks if you do not load them.
+
+## 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.

package/guidelines/tokens.md

@@ -0,0 +1,69 @@
+# Token naming and lookup
+
+Every token is `--vela-<layer>-<role>[-<modifier>]`. Learn the shape and you can find a token
+without grepping the stylesheet.
+
+## The two layers
+
+| Layer | Looks like | Bind it? |
+|---|---|---|
+| **Primitive** | `--vela-grey-700`, `--vela-red-500` | ❌ Almost never — only when no semantic covers the role |
+| **Semantic** | `--vela-text-default`, `--vela-bg-severity-major` | ✅ Always |
+
+Primitives exist so semantics can be re-pointed for theming. Binding a primitive directly is
+what breaks dark mode, and it is the single most common drift in generated code.
+
+## Decision tree
+
+1. **What am I colouring?** → `text` / `bg` / `border` / `icon` / `signal`
+2. **In what context?** → nothing (global), `severity-*`, `risk-*`, `status-*`, `btn-*`, `control-*`
+3. **What state?** → nothing (default), `-hover`, `-active`, `-inactive`, `-disabled`
+
+`--vela-` + step 1 + step 2 + step 3. Examples:
+
+- Body copy → `--vela-text-default`
+- The background of a critical alert → `--vela-bg-severity-critical`
+- The border of an input while focused → `--vela-control-border-active`
+- The dot for an unhealthy node → `--vela-signal-status-unhealthy`
+
+## Frequency: what you will actually reach for
+
+These cover the overwhelming majority of real usage. Reach past them only deliberately.
+
+| Token | Use |
+|---|---|
+| `--vela-text-default` | Almost all body text |
+| `--vela-text-heading` | Headings only |
+| `--vela-text-de-emphasized` | Secondary/meta text |
+| `--vela-bg-global` | Page background |
+| `--vela-bg-container` | Cards, panels, raised surfaces |
+| `--vela-border-default` | Standard 1px borders |
+| `--vela-border-subtle` | Dividers and rules |
+| `--vela-space-10` / `-15` / `-20` | Most padding and gaps |
+| `--vela-radius-4` | Default corner on every component |
+
+## Numeric tokens already carry their unit
+
+```css
+padding: var(--vela-space-10);              /* ✅ */
+padding: calc(var(--vela-space-10) * 1px);  /* ❌ produces "10px * 1px" */
+```
+
+Applies to `--vela-space-*`, `--vela-icon-*`, `--vela-control-height-*`, `--vela-radius-*`
+and every typography size / line-height.
+
+## Correct and incorrect
+
+```css
+/* ✅ semantic, survives a theme change */
+.thing { color: var(--vela-text-default); background: var(--vela-bg-container); }
+
+/* ⚠️ primitive — only when genuinely no semantic covers the role */
+.thing { color: var(--vela-grey-700); }
+
+/* ❌ raw hex — invisible to theming, fails in dark mode */
+.thing { color: #49555a; }
+
+/* ❌ crossing taxonomies — there is no "high" severity */
+.thing { background: var(--vela-bg-severity-high); }
+```

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@omkarux/vela",
+  "version": "0.2.0",
+  "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",
+  "author": "Omkar Khadamkar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omkarpkh/vela.git"
+  },
+  "homepage": "https://github.com/omkarpkh/vela#readme",
+  "bugs": {
+    "url": "https://github.com/omkarpkh/vela/issues"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/vela.css",
+    "./tokens.css": "./dist/tokens.css",
+    "./guidelines/*": "./guidelines/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "guidelines",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && npm run build:js && npm run build:css",
+    "build:js": "vite build",
+    "build:css": "node scripts/build-css.mjs",
+    "predev": "npm run build:css",
+    "dev": "vite --config vite.demo.config.ts",
+    "predemo:build": "npm run build:css",
+    "demo:build": "vite build --config vite.demo.config.ts",
+    "test": "vitest run",
+    "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",
+    "prepublishOnly": "npm run verify"
+  },
+  "peerDependencies": {
+    "react": "^18.3 || ^19",
+    "react-dom": "^18.3 || ^19"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^26.5.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^26.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "react",
+    "component-library",
+    "accessibility"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}