@vyantra/tokens 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +367 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,367 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# `@vyantra/tokens`
|
|
4
|
+
|
|
5
|
+
**Design tokens for the Vyantra design system**
|
|
6
|
+
Colors · Typography · Spacing · Shadows · Radius · Motion
|
|
7
|
+
|
|
8
|
+
[](https://www.npmjs.com/package/@vyantra/tokens)
|
|
9
|
+
[](../../LICENSE)
|
|
10
|
+
[](https://bundlephobia.com/package/@vyantra/tokens)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## What is this?
|
|
17
|
+
|
|
18
|
+
`@vyantra/tokens` is the foundation of the Vyantra design system. It ships a single CSS file that defines every design decision as a CSS custom property (variable) — colors, spacing, typography, shadows, radius, and motion.
|
|
19
|
+
|
|
20
|
+
**Everything in the system uses these tokens. You never hardcode a value.**
|
|
21
|
+
|
|
22
|
+
```css
|
|
23
|
+
/* ✅ Do this */
|
|
24
|
+
color: var(--color-text-primary);
|
|
25
|
+
padding: var(--spacing-4);
|
|
26
|
+
|
|
27
|
+
/* ❌ Never this */
|
|
28
|
+
color: #111827;
|
|
29
|
+
padding: 16px;
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
# npm
|
|
38
|
+
npm install @vyantra/tokens
|
|
39
|
+
|
|
40
|
+
# pnpm
|
|
41
|
+
pnpm add @vyantra/tokens
|
|
42
|
+
|
|
43
|
+
# yarn
|
|
44
|
+
yarn add @vyantra/tokens
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Quick Start
|
|
50
|
+
|
|
51
|
+
### In a React / Vite app
|
|
52
|
+
|
|
53
|
+
Import the CSS **once** at the root of your app — usually `main.tsx` or `index.tsx`.
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
// main.tsx
|
|
57
|
+
import '@vyantra/tokens/css';
|
|
58
|
+
import { createRoot } from 'react-dom/client';
|
|
59
|
+
import App from './App';
|
|
60
|
+
|
|
61
|
+
createRoot(document.getElementById('root')!).render(<App />);
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### In a plain HTML project
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<head>
|
|
68
|
+
<link rel="stylesheet" href="node_modules/@vyantra/tokens/dist/tokens.css" />
|
|
69
|
+
</head>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### In a CSS / SCSS file
|
|
73
|
+
|
|
74
|
+
```css
|
|
75
|
+
@import '@vyantra/tokens/css';
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
After that, every token is available as a CSS variable anywhere in your project.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Token Categories
|
|
83
|
+
|
|
84
|
+
### 🎨 Colors
|
|
85
|
+
|
|
86
|
+
Tokens follow a two-layer architecture:
|
|
87
|
+
|
|
88
|
+
| Layer | Purpose | Example |
|
|
89
|
+
|-------|---------|---------|
|
|
90
|
+
| **Primitives** | Raw palette values. Never use directly. | `--primitive-blue-600` |
|
|
91
|
+
| **Semantics** | Role-based names. Use these in components. | `--color-primary` |
|
|
92
|
+
|
|
93
|
+
#### Surfaces & Backgrounds
|
|
94
|
+
|
|
95
|
+
| Token | Light | Dark | Use for |
|
|
96
|
+
|-------|-------|------|---------|
|
|
97
|
+
| `--color-bg` | `#ffffff` | `#0c0d11` | Page background |
|
|
98
|
+
| `--color-bg-subtle` | `#f9fafb` | `#111318` | Sidebar, cards |
|
|
99
|
+
| `--color-bg-muted` | `#f3f4f6` | `#181920` | Input backgrounds |
|
|
100
|
+
| `--color-bg-emphasis` | `#e5e7eb` | `#1f2029` | Hover states |
|
|
101
|
+
| `--color-bg-inverse` | `#111827` | `#f0f1f5` | Tooltips, badges |
|
|
102
|
+
|
|
103
|
+
#### Borders
|
|
104
|
+
|
|
105
|
+
| Token | Use for |
|
|
106
|
+
|-------|---------|
|
|
107
|
+
| `--color-border` | Default borders, dividers |
|
|
108
|
+
| `--color-border-strong` | Emphasized borders |
|
|
109
|
+
| `--color-border-focus` | Focus rings |
|
|
110
|
+
|
|
111
|
+
#### Text
|
|
112
|
+
|
|
113
|
+
| Token | Use for |
|
|
114
|
+
|-------|---------|
|
|
115
|
+
| `--color-text-primary` | Main body text |
|
|
116
|
+
| `--color-text-secondary` | Supporting text, labels |
|
|
117
|
+
| `--color-text-tertiary` | Hints, placeholders |
|
|
118
|
+
| `--color-text-disabled` | Disabled text |
|
|
119
|
+
| `--color-text-inverse` | Text on dark surfaces |
|
|
120
|
+
| `--color-text-link` | Hyperlinks |
|
|
121
|
+
|
|
122
|
+
#### Intent Colors
|
|
123
|
+
|
|
124
|
+
Each intent (primary, secondary, success, warning, danger, info, neutral) ships a full set of tokens:
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
--color-{intent} → solid background
|
|
128
|
+
--color-{intent}-hover → hover state
|
|
129
|
+
--color-{intent}-active → pressed state
|
|
130
|
+
--color-{intent}-subtle → very light tint (soft buttons, alerts)
|
|
131
|
+
--color-{intent}-muted → light tint
|
|
132
|
+
--color-{intent}-border → border color
|
|
133
|
+
--color-{intent}-text → text on subtle/muted backgrounds
|
|
134
|
+
--color-on-{intent} → text on solid backgrounds (always readable)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Available intents:** `primary` · `secondary` · `success` · `warning` · `danger` · `info` · `neutral`
|
|
138
|
+
|
|
139
|
+
Example usage:
|
|
140
|
+
|
|
141
|
+
```css
|
|
142
|
+
.my-badge {
|
|
143
|
+
background: var(--color-success-subtle);
|
|
144
|
+
color: var(--color-success-text);
|
|
145
|
+
border: 1px solid var(--color-success-border);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
.my-cta-button {
|
|
149
|
+
background: var(--color-primary);
|
|
150
|
+
color: var(--color-on-primary);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
.my-cta-button:hover {
|
|
154
|
+
background: var(--color-primary-hover);
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
### 📐 Spacing
|
|
161
|
+
|
|
162
|
+
4px base unit. Use for padding, margin, gap, width, height.
|
|
163
|
+
|
|
164
|
+
| Token | Value | Pixels |
|
|
165
|
+
|-------|-------|--------|
|
|
166
|
+
| `--spacing-px` | `1px` | 1 |
|
|
167
|
+
| `--spacing-0-5` | `2px` | 2 |
|
|
168
|
+
| `--spacing-1` | `4px` | 4 |
|
|
169
|
+
| `--spacing-1-5` | `6px` | 6 |
|
|
170
|
+
| `--spacing-2` | `8px` | 8 |
|
|
171
|
+
| `--spacing-2-5` | `10px` | 10 |
|
|
172
|
+
| `--spacing-3` | `12px` | 12 |
|
|
173
|
+
| `--spacing-3-5` | `14px` | 14 |
|
|
174
|
+
| `--spacing-4` | `16px` | 16 |
|
|
175
|
+
| `--spacing-5` | `20px` | 20 |
|
|
176
|
+
| `--spacing-6` | `24px` | 24 |
|
|
177
|
+
| `--spacing-7` | `28px` | 28 |
|
|
178
|
+
| `--spacing-8` | `32px` | 32 |
|
|
179
|
+
| `--spacing-10` | `40px` | 40 |
|
|
180
|
+
| `--spacing-12` | `48px` | 48 |
|
|
181
|
+
| `--spacing-16` | `64px` | 64 |
|
|
182
|
+
| `--spacing-20` | `80px` | 80 |
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
### 🔤 Typography
|
|
187
|
+
|
|
188
|
+
| Token | Value | Use for |
|
|
189
|
+
|-------|-------|---------|
|
|
190
|
+
| `--font-sans` | Geist, system-ui | All body text |
|
|
191
|
+
| `--font-mono` | Geist Mono, JetBrains Mono | Code, numbers |
|
|
192
|
+
| `--text-2xs` | `0.625rem` (10px) | Micro labels |
|
|
193
|
+
| `--text-xs` | `0.75rem` (12px) | Captions, badges |
|
|
194
|
+
| `--text-sm` | `0.875rem` (14px) | Body small, buttons |
|
|
195
|
+
| `--text-md` | `1rem` (16px) | Body default |
|
|
196
|
+
| `--text-lg` | `1.125rem` (18px) | Body large |
|
|
197
|
+
| `--text-xl` | `1.25rem` (20px) | Subheadings |
|
|
198
|
+
| `--text-2xl` | `1.5rem` (24px) | Section headings |
|
|
199
|
+
| `--text-3xl` | `1.875rem` (30px) | Page headings |
|
|
200
|
+
| `--text-4xl` | `2.25rem` (36px) | Display |
|
|
201
|
+
| `--weight-regular` | `400` | Normal text |
|
|
202
|
+
| `--weight-medium` | `500` | UI labels, buttons |
|
|
203
|
+
| `--weight-semibold` | `600` | Headings |
|
|
204
|
+
| `--weight-bold` | `700` | Strong emphasis |
|
|
205
|
+
| `--leading-none` | `1` | Icon buttons |
|
|
206
|
+
| `--leading-tight` | `1.25` | Headings |
|
|
207
|
+
| `--leading-normal` | `1.5` | Body text |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
### 🔘 Border Radius
|
|
212
|
+
|
|
213
|
+
| Token | Value | Use for |
|
|
214
|
+
|-------|-------|---------|
|
|
215
|
+
| `--radius-none` | `0px` | Sharp corners |
|
|
216
|
+
| `--radius-xs` | `2px` | Subtle rounding |
|
|
217
|
+
| `--radius-sm` | `4px` | Chips, tags |
|
|
218
|
+
| `--radius-md` | `6px` | Buttons, inputs (default) |
|
|
219
|
+
| `--radius-lg` | `8px` | Cards |
|
|
220
|
+
| `--radius-xl` | `12px` | Large cards, modals |
|
|
221
|
+
| `--radius-2xl` | `16px` | Panels |
|
|
222
|
+
| `--radius-full` | `9999px` | Pill shapes |
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
### 🌑 Shadows
|
|
227
|
+
|
|
228
|
+
| Token | Use for |
|
|
229
|
+
|-------|---------|
|
|
230
|
+
| `--shadow-xs` | Subtle lift (inputs) |
|
|
231
|
+
| `--shadow-sm` | Cards, dropdowns |
|
|
232
|
+
| `--shadow-md` | Modals, popovers |
|
|
233
|
+
| `--shadow-lg` | Dialogs, elevated sheets |
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
### ⚡ Motion / Duration
|
|
238
|
+
|
|
239
|
+
| Token | Value | Use for |
|
|
240
|
+
|-------|-------|---------|
|
|
241
|
+
| `--duration-fast` | `100ms` | Hover states |
|
|
242
|
+
| `--duration-normal` | `150ms` | Most transitions |
|
|
243
|
+
| `--duration-slow` | `200ms` | Panel open/close |
|
|
244
|
+
| `--duration-slower` | `300ms` | Page transitions |
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Theming
|
|
249
|
+
|
|
250
|
+
### Light / Dark (built-in)
|
|
251
|
+
|
|
252
|
+
Both themes are included out of the box. Set `data-theme` on your `<html>` or any container:
|
|
253
|
+
|
|
254
|
+
```html
|
|
255
|
+
<!-- Light (default) -->
|
|
256
|
+
<html>
|
|
257
|
+
|
|
258
|
+
<!-- Dark -->
|
|
259
|
+
<html data-theme="dark">
|
|
260
|
+
|
|
261
|
+
<!-- Dark only inside a specific section -->
|
|
262
|
+
<section data-theme="dark">
|
|
263
|
+
...
|
|
264
|
+
</section>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
> Light theme is the default — no attribute needed. All semantic tokens automatically update when the theme changes.
|
|
268
|
+
|
|
269
|
+
### Custom Theme
|
|
270
|
+
|
|
271
|
+
Override any semantic token on your own selector — no need to touch the package:
|
|
272
|
+
|
|
273
|
+
```css
|
|
274
|
+
/* Brand override */
|
|
275
|
+
[data-theme="brand"] {
|
|
276
|
+
--color-primary: #e11d48; /* rose-600 */
|
|
277
|
+
--color-primary-hover: #be123c;
|
|
278
|
+
--color-primary-subtle: #fff1f2;
|
|
279
|
+
--color-primary-text: #9f1239;
|
|
280
|
+
--color-on-primary: #ffffff;
|
|
281
|
+
}
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
```html
|
|
285
|
+
<div data-theme="brand">
|
|
286
|
+
<!-- All @vyantra/ui components here use your brand colors automatically -->
|
|
287
|
+
</div>
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## JavaScript / TypeScript Tokens
|
|
293
|
+
|
|
294
|
+
If you need token values in JavaScript (for Tailwind config, Storybook, or theming logic), you can import them as typed objects:
|
|
295
|
+
|
|
296
|
+
```ts
|
|
297
|
+
import { allTokens, type TokenName, type TokenValue } from '@vyantra/tokens';
|
|
298
|
+
|
|
299
|
+
console.log(allTokens['color-primary']); // '#2563eb'
|
|
300
|
+
|
|
301
|
+
// Fully typed
|
|
302
|
+
const token: TokenName = 'spacing-4'; // ✅ autocompletes
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Using in Tailwind CSS
|
|
308
|
+
|
|
309
|
+
```js
|
|
310
|
+
// tailwind.config.js
|
|
311
|
+
import tokens from '@vyantra/tokens';
|
|
312
|
+
|
|
313
|
+
export default {
|
|
314
|
+
theme: {
|
|
315
|
+
extend: {
|
|
316
|
+
colors: {
|
|
317
|
+
primary: 'var(--color-primary)',
|
|
318
|
+
'primary-subtle': 'var(--color-primary-subtle)',
|
|
319
|
+
danger: 'var(--color-danger)',
|
|
320
|
+
// add as many as you need
|
|
321
|
+
},
|
|
322
|
+
spacing: {
|
|
323
|
+
1: 'var(--spacing-1)',
|
|
324
|
+
2: 'var(--spacing-2)',
|
|
325
|
+
4: 'var(--spacing-4)',
|
|
326
|
+
// ...
|
|
327
|
+
},
|
|
328
|
+
borderRadius: {
|
|
329
|
+
sm: 'var(--radius-sm)',
|
|
330
|
+
md: 'var(--radius-md)',
|
|
331
|
+
full: 'var(--radius-full)',
|
|
332
|
+
},
|
|
333
|
+
},
|
|
334
|
+
},
|
|
335
|
+
};
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Package Contents
|
|
341
|
+
|
|
342
|
+
```
|
|
343
|
+
@vyantra/tokens
|
|
344
|
+
├── dist/
|
|
345
|
+
│ ├── tokens.css ← All CSS variables (import this)
|
|
346
|
+
│ ├── index.js ← JS token objects (ESM)
|
|
347
|
+
│ ├── index.cjs ← JS token objects (CJS)
|
|
348
|
+
│ └── index.d.ts ← TypeScript types
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## Peer Dependencies
|
|
354
|
+
|
|
355
|
+
None. This package has zero runtime dependencies.
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
## Changelog
|
|
360
|
+
|
|
361
|
+
See [CHANGELOG.md](../../CHANGELOG.md) for release notes.
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
<div align="center">
|
|
366
|
+
Part of the <strong>Vyantra Design System</strong> · <a href="https://github.com/ashishvora1997/vyantra-ui">GitHub</a> · <a href="https://vyantra.dev">Docs</a>
|
|
367
|
+
</div>
|