@rainersoft/design-tokens 1.0.3 → 1.0.5

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.
Files changed (11) hide show
  1. package/README.md +550 -544
  2. package/dist/index.d.ts +315 -25
  3. package/dist/index.mjs +1 -1115
  4. package/dist/index.mjs.map +1 -1
  5. package/formats/tailwind.config.ts +4 -3
  6. package/formats/tokens.json +2 -2
  7. package/package.json +32 -32
  8. package/tokens/utilities.ts +114 -8
  9. package/dist/index.cjs +0 -1190
  10. package/dist/index.cjs.map +0 -1
  11. package/dist/index.d.cts +0 -5853
package/README.md CHANGED
@@ -1,544 +1,550 @@
1
- # @rainersoft/design-tokens
2
-
3
- <div align="center">
4
-
5
- ![Version](https://img.shields.io/badge/version-3.0.0-blue)
6
- ![License](https://img.shields.io/badge/license-MIT-green)
7
- ![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue)
8
- ![Size](https://img.shields.io/badge/size-<5KB-success)
9
-
10
- **Enterprise-grade design tokens for modern design systems**
11
-
12
- [Getting Started](#-installation) • [Documentation](#-documentation) • [Storybook](#-storybook---visualização-dos-tokens) • [Roadmap](./docs/roadmap.md)
13
-
14
- </div>
15
-
16
- ---
17
-
18
- ## 📖 Overview
19
-
20
- `@rainersoft/design-tokens` é uma biblioteca profissional de design tokens que define a linguagem visual do RainerSoft Design System. Agnóstica de tecnologia, escalável e pronta para produção.
21
-
22
- ### ✨ Features
23
-
24
- - 🎨 **Temas Light & Dark** - Paletas profissionais para qualquer contexto
25
- - 🚀 **Zero Dependencies** - Pura performance, sem bloat
26
- - 📦 **Múltiplos Formatos** - Tailwind, CSS Vars, JSON universal
27
- - 🎯 **Type-Safe** - 100% TypeScript com tipos completos
28
- - 🌐 **Platform Agnostic** - Use em web, mobile, desktop, jogos
29
- - ♿ **Acessível** - WCAG AA compliant por padrão
30
- - 📏 **8pt Grid** - Sistema de espaçamento consistente
31
- - 🎭 **Cyberpunk Theme** - Dark mode com efeitos neon
32
- - 📚 **Storybook** - Documentação visual interativa de todos os tokens
33
-
34
- ---
35
-
36
- ## 🚀 Installation
37
-
38
- ```bash
39
- pnpm add @rainersoft/design-tokens
40
- ```
41
-
42
- ```bash
43
- npm install @rainersoft/design-tokens
44
- ```
45
-
46
- ```bash
47
- yarn add @rainersoft/design-tokens
48
- ```
49
-
50
- ---
51
-
52
- ## 🔄 Migração do Pacote Antigo
53
-
54
- Se você estava usando `rainer-design-tokens` ou `@rainer/design-tokens`, migre para o novo escopo da organização:
55
-
56
- ```bash
57
- # Remover pacote antigo
58
- pnpm remove rainer-design-tokens
59
- # ou
60
- pnpm remove @rainer/design-tokens
61
-
62
- # Instalar novo pacote
63
- pnpm add @rainersoft/design-tokens
64
- ```
65
-
66
- **Atualizar importações:**
67
- ```typescript
68
- // Antes
69
- import { tokens } from 'rainer-design-tokens';
70
- // ou
71
- import { tokens } from '@rainer/design-tokens';
72
-
73
- // Depois
74
- import { tokens } from '@rainersoft/design-tokens';
75
- ```
76
-
77
- > **Nota**: O pacote antigo continuará disponível por um período de transição, mas recomendamos migrar para `@rainersoft/design-tokens` para receber atualizações futuras.
78
-
79
- ---
80
-
81
- ## 🎯 Quick Start
82
-
83
- ### TypeScript/JavaScript
84
-
85
- ```typescript
86
- import { tokens, lightTheme, darkTheme } from '@rainersoft/design-tokens';
87
-
88
- // Use tokens diretamente
89
- const primaryColor = tokens.colors.light.primary.base; // #0891b2
90
- const spacing = tokens.spacing['4']; // 1rem
91
- const fontSize = tokens.typography.headings.h1.fontSize; // 2.25rem
92
-
93
- // Ou use temas
94
- const theme = lightTheme;
95
- console.log(theme.colors.background.primary); // #ffffff
96
- ```
97
-
98
- ### Tailwind CSS
99
-
100
- ```typescript
101
- // tailwind.config.ts
102
- import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
103
-
104
- export default {
105
- ...tailwindConfig,
106
- content: ['./src/**/*.{js,ts,jsx,tsx}'],
107
- };
108
- ```
109
-
110
- ```tsx
111
- // Use as classes
112
- <div className="bg-brand text-text-primary p-4 rounded-lg shadow-md">
113
- Hello World
114
- </div>
115
- ```
116
-
117
- ### CSS Variables
118
-
119
- ```css
120
- /* Import CSS vars */
121
- @import '@rainersoft/design-tokens/formats/css-vars.css';
122
-
123
- /* Use variables */
124
- .button {
125
- background: var(--color-brand-primary);
126
- padding: var(--spacing-4);
127
- border-radius: var(--radius-md);
128
- }
129
- ```
130
-
131
- ### 📚 Storybook - Visualização dos Tokens
132
-
133
- O Storybook da lib é focado **apenas em design tokens**, não em componentes UI.
134
-
135
- ```bash
136
- pnpm run storybook
137
- ```
138
-
139
- Acesse `http://localhost:6006` para explorar:
140
- - 🎨 **ColorPalette** - Paletas completas (Light & Dark themes)
141
- - 🎭 **ThemePreview** - Preview dos temas mostrando tokens trabalhando juntos
142
- - 📝 **Typography** - Sistema de tipografia completo
143
- - 📏 **Spacing** - Escala de espaçamento (8pt grid)
144
- - 🔲 **Radius** - Raios de borda
145
- - 🌑 **Shadows** - Sombras e efeitos glow
146
-
147
- > **Nota**: Componentes UI (Button, Card, etc.) devem estar no Storybook do frontend, não aqui. Veja [Estrutura do Storybook](./docs/ESTRUTURA_STORYBOOK.md) para mais detalhes.
148
-
149
- ---
150
-
151
- ## 📁 Structure
152
-
153
- ```
154
- @rainersoft/design-tokens/
155
- │
156
- ├── 📄 index.ts # Ponto de entrada principal da biblioteca
157
- ├── 📄 package.json # Configuração do pacote npm
158
- ├── 📄 pnpm-lock.yaml # Lock file do pnpm
159
- ├── 📄 tsconfig.json # Configuração TypeScript
160
- ├── 📄 tsup.config.ts # Configuração do bundler tsup
161
- ├── 📄 LICENSE # Licença MIT
162
- ├── 📄 README.md # Este arquivo
163
- │
164
- ├── 🔧 Configurações
165
- │ ├── .npmrc # Configuração pnpm (isolamento workspace)
166
- │ ├── .gitignore # Arquivos ignorados pelo Git
167
- │ ├── .npmignore # Arquivos ignorados na publicação npm
168
- │ ├── .prettierrc.json # Configuração Prettier
169
- │ ├── .eslintrc.json # Configuração ESLint
170
- │ ├── .cspell.json # Configuração CSpell (verificação ortográfica)
171
- │ └── .env # Variáveis de ambiente (local, não commitado)
172
- │
173
- ├── 🎯 tokens/ # FONTE ÚNICA DE VERDADE (JSON + TypeScript)
174
- │ ├── index.ts # Exportações principais dos tokens
175
- │ ├── accessibility.ts # Utilitários de acessibilidade (WCAG)
176
- │ ├── utilities.ts # Utilitários e helpers
177
- │ ├── colors/
178
- │ │ ├── light.json # Paleta do tema claro
179
- │ │ └── dark.json # Paleta do tema escuro (cyberpunk)
180
- │ ├── typography.json # Sistema de tipografia completo
181
- │ ├── spacing.json # Escala de espaçamento (8pt grid)
182
- │ ├── radius.json # Escala de raio de borda
183
- │ └── shadows.json # Sombras e efeitos glow
184
- │
185
- ├── 🎨 themes/ # Temas compostos
186
- │ ├── index.ts # Exportações dos temas
187
- │ ├── light.ts # Tema claro profissional
188
- │ └── dark.ts # Tema escuro cyberpunk
189
- │
190
- ├── 📤 formats/ # FORMATOS GERADOS AUTOMATICAMENTE
191
- │ ├── tailwind.config.ts # Configuração Tailwind (gerado)
192
- │ ├── css-vars.css # CSS custom properties (gerado)
193
- │ └── tokens.json # Export JSON universal (gerado)
194
- │
195
- ├── 🔧 scripts/ # Scripts de build e utilitários
196
- │ ├── build-formats.ts # Orquestrador principal de build
197
- │ ├── build-css.ts # Gera CSS variables
198
- │ ├── build-tailwind.ts # Gera Tailwind config
199
- │ ├── build-tokens-json.ts # Gera tokens.json
200
- │ ├── prepare-publish.js # Prepara publicação npm
201
- │ ├── setup-github.sh # Setup GitHub Actions
202
- │ ├── fix-storybook.ps1 # Script PowerShell para Storybook
203
- │ └── update-dates.ts # Atualiza datas na documentação
204
- │
205
- ├── 📚 stories/ # Stories do Storybook (apenas tokens)
206
- │ ├── assets/ # Assets das stories
207
- │ ├── Accessibility.stories.tsx # Documentação de acessibilidade
208
- │ ├── ColorPalette.stories.tsx # Paleta completa de cores
209
- │ ├── ColorStates.stories.tsx # Estados de cores
210
- │ ├── ThemePreview.stories.tsx # Preview dos temas
211
- │ ├── Typography.stories.tsx # Sistema de tipografia
212
- │ ├── TypographyHierarchy.stories.tsx # Hierarquia tipográfica
213
- │ ├── Spacing.stories.tsx # Escala de espaçamento
214
- │ ├── Radius.stories.tsx # Raios de borda
215
- │ ├── Shadows.stories.tsx # Sombras e efeitos
216
- │ └── *.mdx # Documentação MDX das stories
217
- │
218
- ├── ⚙️ .storybook/ # Configuração do Storybook
219
- │ ├── main.ts # Configuração principal
220
- │ └── preview.tsx # Preview e temas do Storybook
221
- │
222
- ├── 📦 dist/ # Saída compilada (TypeScript)
223
- │ ├── index.js # CommonJS bundle
224
- │ ├── index.mjs # ESM bundle
225
- │ ├── index.d.ts # TypeScript definitions
226
- │ ├── index.d.mts # ESM TypeScript definitions
227
- │ └── *.map # Source maps
228
- │
229
- └── 📖 docs/ # Documentação completa
230
- ├── INDICE.md # Índice geral da documentação
231
- ├── ESTRUTURA.md # Estrutura detalhada da biblioteca
232
- ├── ESTRUTURA_STORYBOOK.md # Estrutura do Storybook
233
- ├── SISTEMA_BUILD.md # Sistema de build automatizado
234
- ├── guidelines.md # Guidelines de uso
235
- ├── GUIA_TOKENS_EXPANDIDOS.md # Guia dos tokens expandidos
236
- ├── GUIA_MIGRACAO.md # Guia de migração
237
- ├── PUBLICACAO.md # Guia de publicação
238
- ├── CONFIGURACAO_PNPM.md # Configuração pnpm
239
- ├── CONTRIBUINDO.md # Guia de contribuição
240
- ├── STORYBOOK.md # Documentação do Storybook
241
- ├── RESUMO_ESTRUTURA.md # Resumo da estrutura
242
- ├── HISTORICO_MUDANCAS.md # Histórico de mudanças
243
- └── roadmap.md # Roadmap do projeto
244
- ```
245
-
246
- ### 🎯 Princípio: JSON como Fonte Única de Verdade
247
-
248
- - ✅ **Edite apenas**: `tokens/*.json` (arquivos JSON na pasta `tokens/`)
249
- - ✅ **Edite também**: `tokens/*.ts` (utilitários e helpers em TypeScript)
250
- - ✅ **Formats são gerados**: Execute `pnpm run build:formats`
251
- - ❌ **NÃO edite manualmente**: `formats/*` (serão sobrescritos pelo build)
252
- - ⚙️ **Configurações**: Arquivos `.npmrc`, `.eslintrc.json`, `.prettierrc.json`, etc. na raiz
253
-
254
- ---
255
-
256
- ## 🎨 Color System
257
-
258
- ### Light Theme
259
- ```typescript
260
- {
261
- primary: { base: '#0891b2', hover: '#06b6d4', active: '#0891b2' },
262
- secondary: { base: '#9333ea', hover: '#a855f7', active: '#9333ea' },
263
- accent: { base: '#db2777', hover: '#e11d48', active: '#db2777' },
264
- status: { success: '#22c55e', error: '#ef4444', warning: '#f59e0b', info: '#3b82f6' }
265
- }
266
- ```
267
-
268
- ### Dark Theme (Cyberpunk)
269
- ```typescript
270
- {
271
- primary: { base: '#00e6ff', hover: '#33eeff', active: '#00e6ff' },
272
- secondary: { base: '#7d00ff', hover: '#9333ea', active: '#7d00ff' },
273
- accent: { base: '#ff006e', hover: '#ff3385', active: '#ff006e' },
274
- effects: { glowCyan: '0 0 20px rgba(0, 230, 255, 0.5)' }
275
- }
276
- ```
277
-
278
- ---
279
-
280
- ## 📏 Typography
281
-
282
- Sistema hierárquico completo com headings, subtítulos, body, captions, buttons e labels:
283
-
284
- ```typescript
285
- {
286
- headings: {
287
- h1: { fontSize: '2.25rem', fontWeight: '700', lineHeight: '1.2' },
288
- h2: { fontSize: '1.875rem', fontWeight: '600', lineHeight: '1.3' },
289
- // ... h3, h4, h5, h6
290
- },
291
- body: {
292
- large: { fontSize: '1.125rem', lineHeight: '1.75' },
293
- medium: { fontSize: '1rem', lineHeight: '1.5' },
294
- small: { fontSize: '0.875rem', lineHeight: '1.5' }
295
- },
296
- // ... subtitle, caption, button, label, code
297
- }
298
- ```
299
-
300
- ---
301
-
302
- ## 🌓 Theme Switching
303
-
304
- ```tsx
305
- // React example
306
- function ThemeToggle() {
307
- const [theme, setTheme] = useState('light');
308
-
309
- const toggleTheme = () => {
310
- const newTheme = theme === 'light' ? 'dark' : 'light';
311
- setTheme(newTheme);
312
- document.documentElement.classList.toggle('dark');
313
- };
314
-
315
- return <button onClick={toggleTheme}>Toggle Theme</button>;
316
- }
317
- ```
318
-
319
- ---
320
-
321
- ## 📚 Documentation
322
-
323
- 📖 **[Documentação Completa](./docs/INDICE.md)** - Índice geral de toda a documentação
324
-
325
- ### Guias Principais
326
-
327
- - [**Guidelines**](./docs/guidelines.md) - Como usar os tokens
328
- - [**ESTRUTURA.md**](./docs/ESTRUTURA.md) - Estrutura detalhada da biblioteca
329
- - [**SISTEMA_BUILD.md**](./docs/SISTEMA_BUILD.md) - Sistema de build automatizado
330
- - [**Roadmap**](./docs/roadmap.md) - Futuras features e versões
331
- - [**GUIA_TOKENS_EXPANDIDOS**](./docs/GUIA_TOKENS_EXPANDIDOS.md) - Guia dos tokens expandidos (cores e tipografia)
332
- - [**GUIA_MIGRACAO**](./docs/GUIA_MIGRACAO.md) - Guia de migração para v3.0.0
333
- - [**PUBLICACAO**](./docs/PUBLICACAO.md) - Guia de publicação no GitHub/npm
334
-
335
- ### Storybook
336
-
337
- - [**STORYBOOK.md**](./docs/STORYBOOK.md) - Documentação visual dos tokens
338
- - [**ESTRUTURA_STORYBOOK.md**](./docs/ESTRUTURA_STORYBOOK.md) - Separação entre tokens e componentes
339
-
340
- ### Referência Rápida
341
-
342
- - [**RESUMO_ESTRUTURA.md**](./docs/RESUMO_ESTRUTURA.md) - Resumo da estrutura
343
- - [**HISTORICO_MUDANCAS.md**](./docs/HISTORICO_MUDANCAS.md) - Histórico de mudanças
344
-
345
- ---
346
-
347
- ## 🎯 Use Cases
348
-
349
- ### ✅ Perfect For
350
-
351
- - 🌐 Websites e aplicações web
352
- - 📱 Aplicativos mobile (React Native, Flutter)
353
- - 🖥️ Aplicações desktop (Electron, Tauri)
354
- - 🎮 Interfaces de jogos (Unity, Unreal, Godot)
355
- - 🎨 Design systems corporativos
356
- - 🚀 MVPs e protótipos rápidos
357
-
358
- ### ❌ Not Included
359
-
360
- Esta biblioteca contém **apenas tokens**, não componentes UI.
361
-
362
- Para componentes, use:
363
- - [shadcn/ui](https://ui.shadcn.com/) com estes tokens
364
- - [Radix UI](https://www.radix-ui.com/) + custom styling
365
- - Sua própria biblioteca de componentes
366
-
367
- ---
368
-
369
- ## 🔧 Integration Examples
370
-
371
- ### Next.js + Tailwind
372
-
373
- ```typescript
374
- // tailwind.config.ts
375
- import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
376
-
377
- export default tailwindConfig;
378
- ```
379
-
380
- ```tsx
381
- // app/layout.tsx
382
- export default function RootLayout({ children }: { children: React.Node }) {
383
- return (
384
- <html lang="pt-BR" className="dark">
385
- <body>{children}</body>
386
- </html>
387
- );
388
- }
389
- ```
390
-
391
- ### Vite + CSS
392
-
393
- ```typescript
394
- // main.ts
395
- import '@rainersoft/design-tokens/formats/css-vars.css';
396
- ```
397
-
398
- ### shadcn/ui
399
-
400
- ```typescript
401
- // Use tokens as base for shadcn/ui theming
402
- import { tokens } from '@rainer/design-tokens';
403
-
404
- export const shadcnTheme = {
405
- primary: tokens.colors.light.primary.base,
406
- secondary: tokens.colors.light.secondary.base,
407
- accent: tokens.colors.light.accent.base,
408
- // ... map other tokens
409
- };
410
- ```
411
-
412
- ---
413
-
414
- ## 📦 Exports
415
-
416
- ```typescript
417
- // Main tokens
418
- import { tokens } from '@rainer/design-tokens';
419
-
420
- // Individual token categories
421
- import {
422
- lightThemeColors,
423
- darkThemeColors,
424
- typographyTokens,
425
- spacingTokens,
426
- radiusTokens,
427
- shadowTokens
428
- } from '@rainersoft/design-tokens/tokens';
429
-
430
- // Themes
431
- import { lightTheme, darkTheme } from '@rainersoft/design-tokens/themes';
432
-
433
- // Formats
434
- import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
435
- ```
436
-
437
- ---
438
-
439
- ## 🧪 Development
440
-
441
- ```bash
442
- # Install dependencies
443
- pnpm install
444
-
445
- # Build tokens (gera formats + compila TypeScript)
446
- pnpm run build
447
-
448
- # Gerar apenas formatos (CSS, Tailwind, JSON)
449
- pnpm run build:formats
450
-
451
- # Gerar formatos individuais
452
- pnpm run build:css # Gera formats/css-vars.css
453
- pnpm run build:tailwind # Gera formats/tailwind.config.ts
454
- pnpm run build:tokens-json # Gera formats/tokens.json
455
-
456
- # Storybook (visualização dos tokens)
457
- pnpm run storybook # Inicia Storybook em http://localhost:6006
458
- pnpm run build-storybook # Gera build estático do Storybook
459
-
460
- # Run tests
461
- pnpm test
462
-
463
- # Type check
464
- pnpm run type-check
465
-
466
- # Lint
467
- pnpm run lint
468
-
469
- # Clean
470
- pnpm run clean # Remove dist/
471
- pnpm run clean:all # Remove node_modules, lock, dist, etc.
472
- ```
473
-
474
- ### 🔄 Workflow de Desenvolvimento
475
-
476
- 1. **Edite os tokens** em `tokens/*.json` (fonte única de verdade)
477
- 2. **Edite utilitários** em `tokens/*.ts` se necessário (accessibility, utilities)
478
- 3. **Execute o build**: `pnpm run build:formats` (gera formatos)
479
- 4. **Os formatos são gerados automaticamente** em `formats/`
480
- 5. **Compile o TypeScript**: `pnpm run build` (já inclui build:formats + tsup)
481
- 6. **Visualize no Storybook**: `pnpm run storybook` para ver todos os tokens de forma interativa
482
- 7. **Execute testes**: `pnpm test` antes de commitar
483
- 8. **⚠️ IMPORTANTE**: Sempre commit `dist/` após build (veja [PUBLICACAO.md](./docs/PUBLICACAO.md#-por-que-dist-está-commitado))
484
-
485
- ### 📚 Storybook - Visualização dos Tokens
486
-
487
- O Storybook da lib documenta **apenas design tokens**, não componentes UI.
488
-
489
- **Stories disponíveis:**
490
- - 🎨 **ColorPalette** - Paletas completas de cores (Light & Dark)
491
- - 🎭 **ThemePreview** - Preview dos temas mostrando tokens em ação
492
- - 📝 **Typography** - Sistema completo de tipografia
493
- - 📏 **Spacing** - Escala de espaçamento (8pt grid)
494
- - 🔲 **Radius** - Raios de borda
495
- - 🌑 **Shadows** - Sombras e efeitos glow
496
-
497
- **Separação de responsabilidades:**
498
- - ✅ **Este Storybook**: Apenas tokens (cores, tipografia, espaçamento, etc.)
499
- - ✅ **Storybook do Frontend**: Componentes UI (Button, Card, Input, etc.)
500
-
501
- Para mais detalhes sobre a estrutura, consulte [**Estrutura do Storybook**](./docs/ESTRUTURA_STORYBOOK.md).
502
-
503
- ---
504
-
505
- ## 🤝 Contributing
506
-
507
- Contributions are welcome! Please read our [Contributing Guide](./docs/CONTRIBUINDO.md) first.
508
-
509
- ---
510
-
511
- ## 📄 License
512
-
513
- MIT © [Rainer Teixeira](https://github.com/RainerTeixeira)
514
-
515
- ---
516
-
517
- ## 🔗 Links
518
-
519
- - **GitHub**: [RainerTeixeira/rainer-design-tokens](https://github.com/RainerTeixeira/rainer-design-tokens)
520
- - **NPM**: [@rainersoft/design-tokens](https://www.npmjs.com/package/@rainersoft/design-tokens)
521
- - **Website**: [rainersoft.com.br](https://rainersoft.com.br)
522
- - **Email**: suporte@rainersoft.com.br
523
-
524
- ## 🛠️ Tech Stack
525
-
526
- - **Language**: TypeScript 5.3+ (strict mode)
527
- - **Package Manager**: pnpm 9+
528
- - **Build Tool**: tsup (TypeScript bundler)
529
- - **Linter**: ESLint + TypeScript ESLint
530
- - **Formatter**: Prettier
531
- - **Testing**: Jest
532
- - **Documentation**: Storybook 10
533
- - **Publish**: GitHub Actions (GitHub Packages + npm)
534
-
535
- ---
536
-
537
- <div align="center">
538
-
539
- **Made with ❤️ by Rainer Teixeira**
540
-
541
- ![Built with TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue)
542
- ![Enterprise Ready](https://img.shields.io/badge/Enterprise-Ready-success)
543
-
544
- </div>
1
+ # @rainersoft/design-tokens
2
+
3
+ <div align="center">
4
+
5
+ ![Version](https://img.shields.io/badge/version-1.0.5-blue)
6
+ ![License](https://img.shields.io/badge/license-MIT-green)
7
+ ![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue)
8
+ ![Size](https://img.shields.io/badge/size-<5KB-success)
9
+
10
+ **Enterprise-grade design tokens for modern design systems**
11
+
12
+ [Getting Started](#-installation) • [Documentation](#-documentation) • [Storybook](#-storybook---visualização-dos-tokens) • [Roadmap](./docs/roadmap.md)
13
+
14
+ </div>
15
+
16
+ ---
17
+
18
+ ## 📖 Overview
19
+
20
+ `@rainersoft/design-tokens` é uma biblioteca profissional de design tokens que define a linguagem visual do RainerSoft Design System. Agnóstica de tecnologia, escalável e pronta para produção.
21
+
22
+ ### ✨ Features
23
+
24
+ - 🎨 **Temas Light & Dark** - Paletas profissionais para qualquer contexto
25
+ - 🚀 **Zero Dependencies** - Pura performance, sem bloat
26
+ - 📦 **Múltiplos Formatos** - Tailwind, CSS Vars, JSON universal
27
+ - 🎯 **Type-Safe** - 100% TypeScript com tipos completos
28
+ - 🌐 **Platform Agnostic** - Use em web, mobile, desktop, jogos
29
+ - ♿ **Acessível** - WCAG AA compliant por padrão
30
+ - 📏 **8pt Grid** - Sistema de espaçamento consistente
31
+ - 🎭 **Cyberpunk Theme** - Dark mode com efeitos neon
32
+ - 🎬 **Animações** - Keyframes e animações prontas (accordion, slide-in, fade-in)
33
+ - 📚 **Storybook** - Documentação visual interativa de todos os tokens
34
+
35
+ ---
36
+
37
+ ## 🚀 Installation
38
+
39
+ ```bash
40
+ pnpm add @rainersoft/design-tokens
41
+ ```
42
+
43
+ ```bash
44
+ npm install @rainersoft/design-tokens
45
+ ```
46
+
47
+ ```bash
48
+ yarn add @rainersoft/design-tokens
49
+ ```
50
+
51
+ ---
52
+
53
+ ## 🔄 Migração do Pacote Antigo
54
+
55
+ Se você estava usando `rainer-design-tokens` ou `@rainer/design-tokens`, migre para o novo escopo da organização:
56
+
57
+ ```bash
58
+ # Remover pacote antigo
59
+ pnpm remove rainer-design-tokens
60
+ # ou
61
+ pnpm remove @rainer/design-tokens
62
+
63
+ # Instalar novo pacote
64
+ pnpm add @rainersoft/design-tokens
65
+ ```
66
+
67
+ **Atualizar importações:**
68
+ ```typescript
69
+ // Antes
70
+ import { tokens } from 'rainer-design-tokens';
71
+ // ou
72
+ import { tokens } from '@rainer/design-tokens';
73
+
74
+ // Depois
75
+ import { tokens } from '@rainersoft/design-tokens';
76
+ ```
77
+
78
+ > **Nota**: O pacote antigo continuará disponível por um período de transição, mas recomendamos migrar para `@rainersoft/design-tokens` para receber atualizações futuras.
79
+
80
+ ---
81
+
82
+ ## 🎯 Quick Start
83
+
84
+ ### TypeScript/JavaScript
85
+
86
+ ```typescript
87
+ import { tokens, lightTheme, darkTheme } from '@rainersoft/design-tokens';
88
+
89
+ // Use tokens diretamente
90
+ const primaryColor = tokens.colors.light.primary.base; // #0891b2
91
+ const spacing = tokens.spacing['4']; // 1rem
92
+ const fontSize = tokens.typography.headings.h1.fontSize; // 2.25rem
93
+
94
+ // Ou use temas
95
+ const theme = lightTheme;
96
+ console.log(theme.colors.background.primary); // #ffffff
97
+ ```
98
+
99
+ ### Tailwind CSS
100
+
101
+ ```typescript
102
+ // tailwind.config.ts
103
+ import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
104
+
105
+ export default {
106
+ ...tailwindConfig,
107
+ content: ['./src/**/*.{js,ts,jsx,tsx}'],
108
+ };
109
+ ```
110
+
111
+ ```tsx
112
+ // Use as classes
113
+ <div className="bg-brand text-text-primary p-4 rounded-lg shadow-md">
114
+ Hello World
115
+ </div>
116
+ ```
117
+
118
+ ### CSS Variables
119
+
120
+ ```css
121
+ /* Import CSS vars */
122
+ @import '@rainersoft/design-tokens/formats/css-vars.css';
123
+
124
+ /* Use variables */
125
+ .button {
126
+ background: var(--color-brand-primary);
127
+ padding: var(--spacing-4);
128
+ border-radius: var(--radius-md);
129
+ }
130
+ ```
131
+
132
+ ### 📚 Storybook - Visualização dos Tokens
133
+
134
+ O Storybook da lib é focado **apenas em design tokens**, não em componentes UI.
135
+
136
+ ```bash
137
+ pnpm run storybook
138
+ ```
139
+
140
+ Acesse `http://localhost:6006` para explorar:
141
+ - 🎨 **ColorPalette** - Paletas completas (Light & Dark themes)
142
+ - 🎭 **ThemePreview** - Preview dos temas mostrando tokens trabalhando juntos
143
+ - 📝 **Typography** - Sistema de tipografia completo
144
+ - 📏 **Spacing** - Escala de espaçamento (8pt grid)
145
+ - 🔲 **Radius** - Raios de borda
146
+ - 🌑 **Shadows** - Sombras e efeitos glow
147
+ - 🎬 **Animations** - Animações e keyframes (accordion, slide-in, fade-in)
148
+
149
+ > **Nota**: Componentes UI (Button, Card, etc.) devem estar no Storybook do frontend, não aqui. Veja [Estrutura do Storybook](./docs/ESTRUTURA_STORYBOOK.md) para mais detalhes.
150
+
151
+ ---
152
+
153
+ ## 📁 Structure
154
+
155
+ ```
156
+ @rainersoft/design-tokens/
157
+ │
158
+ ├── 📄 index.ts # Ponto de entrada principal da biblioteca
159
+ ├── 📄 package.json # Configuração do pacote npm
160
+ ├── 📄 pnpm-lock.yaml # Lock file do pnpm
161
+ ├── 📄 tsconfig.json # Configuração TypeScript
162
+ ├── 📄 tsup.config.ts # Configuração do bundler tsup
163
+ ├── 📄 LICENSE # Licença MIT
164
+ ├── 📄 README.md # Este arquivo
165
+ │
166
+ ├── 🔧 Configurações
167
+ │ ├── .npmrc # Configuração pnpm (isolamento workspace)
168
+ │ ├── .gitignore # Arquivos ignorados pelo Git
169
+ │ ├── .npmignore # Arquivos ignorados na publicação npm
170
+ │ ├── .prettierrc.json # Configuração Prettier
171
+ │ ├── .eslintrc.json # Configuração ESLint
172
+ │ ├── .cspell.json # Configuração CSpell (verificação ortográfica)
173
+ │ └── .env # Variáveis de ambiente (local, não commitado)
174
+ │
175
+ ├── 🎯 tokens/ # FONTE ÚNICA DE VERDADE (JSON + TypeScript)
176
+ │ ├── index.ts # Exportações principais dos tokens
177
+ │ ├── accessibility.ts # Utilitários de acessibilidade (WCAG)
178
+ │ ├── utilities.ts # Utilitários e helpers
179
+ │ ├── colors/
180
+ │ │ ├── light.json # Paleta do tema claro
181
+ │ │ └── dark.json # Paleta do tema escuro (cyberpunk)
182
+ │ ├── typography.json # Sistema de tipografia completo
183
+ │ ├── spacing.json # Escala de espaçamento (8pt grid)
184
+ │ ├── radius.json # Escala de raio de borda
185
+ │ ├── shadows.json # Sombras e efeitos glow
186
+ │ └── animations.json # Animações e keyframes
187
+ │
188
+ ├── 🎨 themes/ # Temas compostos
189
+ │ ├── index.ts # Exportações dos temas
190
+ │ ├── light.ts # Tema claro profissional
191
+ │ └── dark.ts # Tema escuro cyberpunk
192
+ │
193
+ ├── 📤 formats/ # FORMATOS GERADOS AUTOMATICAMENTE
194
+ │ ├── tailwind.config.ts # Configuração Tailwind (gerado)
195
+ │ ├── css-vars.css # CSS custom properties (gerado)
196
+ │ └── tokens.json # Export JSON universal (gerado)
197
+ │
198
+ ├── 🔧 scripts/ # Scripts de build e utilitários
199
+ │ ├── build-formats.ts # Orquestrador principal de build
200
+ │ ├── build-css.ts # Gera CSS variables
201
+ │ ├── build-tailwind.ts # Gera Tailwind config
202
+ │ ├── build-tokens-json.ts # Gera tokens.json
203
+ │ ├── prepare-publish.js # Prepara publicação npm
204
+ │ ├── setup-github.sh # Setup GitHub Actions
205
+ │ ├── fix-storybook.ps1 # Script PowerShell para Storybook
206
+ │ ├── update-dates.ts # Atualiza datas na documentação
207
+ │ └── update-version.ts # Atualiza versão no README automaticamente
208
+ │
209
+ ├── 📚 stories/ # Stories do Storybook (apenas tokens)
210
+ │ ├── assets/ # Assets das stories
211
+ │ ├── Accessibility.stories.tsx # Documentação de acessibilidade
212
+ │ ├── ColorPalette.stories.tsx # Paleta completa de cores
213
+ │ ├── ColorStates.stories.tsx # Estados de cores
214
+ │ ├── ThemePreview.stories.tsx # Preview dos temas
215
+ │ ├── Typography.stories.tsx # Sistema de tipografia
216
+ │ ├── TypographyHierarchy.stories.tsx # Hierarquia tipográfica
217
+ │ ├── Spacing.stories.tsx # Escala de espaçamento
218
+ │ ├── Radius.stories.tsx # Raios de borda
219
+ │ ├── Shadows.stories.tsx # Sombras e efeitos
220
+ │ ├── Animations.stories.tsx # Animações e keyframes
221
+ │ └── *.mdx # Documentação MDX das stories
222
+ │
223
+ ├── ⚙️ .storybook/ # Configuração do Storybook
224
+ │ ├── main.ts # Configuração principal
225
+ │ └── preview.tsx # Preview e temas do Storybook
226
+ │
227
+ ├── 📦 dist/ # Saída compilada (TypeScript)
228
+ │ ├── index.js # CommonJS bundle
229
+ │ ├── index.mjs # ESM bundle
230
+ │ ├── index.d.ts # TypeScript definitions
231
+ │ ├── index.d.mts # ESM TypeScript definitions
232
+ │ └── *.map # Source maps
233
+ │
234
+ └── 📖 docs/ # Documentação completa
235
+ ├── INDICE.md # Índice geral da documentação
236
+ ├── ESTRUTURA.md # Estrutura detalhada da biblioteca
237
+ ├── ESTRUTURA_STORYBOOK.md # Estrutura do Storybook
238
+ ├── SISTEMA_BUILD.md # Sistema de build automatizado
239
+ ├── guidelines.md # Guidelines de uso
240
+ ├── GUIA_TOKENS_EXPANDIDOS.md # Guia dos tokens expandidos
241
+ ├── GUIA_MIGRACAO.md # Guia de migração
242
+ ├── PUBLICACAO.md # Guia de publicação
243
+ ├── CONFIGURACAO_PNPM.md # Configuração pnpm
244
+ ├── CONTRIBUINDO.md # Guia de contribuição
245
+ ├── STORYBOOK.md # Documentação do Storybook
246
+ ├── RESUMO_ESTRUTURA.md # Resumo da estrutura
247
+ ├── HISTORICO_MUDANCAS.md # Histórico de mudanças
248
+ └── roadmap.md # Roadmap do projeto
249
+ ```
250
+
251
+ ### 🎯 Princípio: JSON como Fonte Única de Verdade
252
+
253
+ - ✅ **Edite apenas**: `tokens/*.json` (arquivos JSON na pasta `tokens/`)
254
+ - ✅ **Edite também**: `tokens/*.ts` (utilitários e helpers em TypeScript)
255
+ - ✅ **Formats são gerados**: Execute `pnpm run build:formats`
256
+ - ❌ **NÃO edite manualmente**: `formats/*` (serão sobrescritos pelo build)
257
+ - ⚙️ **Configurações**: Arquivos `.npmrc`, `.eslintrc.json`, `.prettierrc.json`, etc. na raiz
258
+
259
+ ---
260
+
261
+ ## 🎨 Color System
262
+
263
+ ### Light Theme
264
+ ```typescript
265
+ {
266
+ primary: { base: '#0891b2', hover: '#06b6d4', active: '#0891b2' },
267
+ secondary: { base: '#9333ea', hover: '#a855f7', active: '#9333ea' },
268
+ accent: { base: '#db2777', hover: '#e11d48', active: '#db2777' },
269
+ status: { success: '#22c55e', error: '#ef4444', warning: '#f59e0b', info: '#3b82f6' }
270
+ }
271
+ ```
272
+
273
+ ### Dark Theme (Cyberpunk)
274
+ ```typescript
275
+ {
276
+ primary: { base: '#00e6ff', hover: '#33eeff', active: '#00e6ff' },
277
+ secondary: { base: '#7d00ff', hover: '#9333ea', active: '#7d00ff' },
278
+ accent: { base: '#ff006e', hover: '#ff3385', active: '#ff006e' },
279
+ effects: { glowCyan: '0 0 20px rgba(0, 230, 255, 0.5)' }
280
+ }
281
+ ```
282
+
283
+ ---
284
+
285
+ ## 📏 Typography
286
+
287
+ Sistema hierárquico completo com headings, subtítulos, body, captions, buttons e labels:
288
+
289
+ ```typescript
290
+ {
291
+ headings: {
292
+ h1: { fontSize: '2.25rem', fontWeight: '700', lineHeight: '1.2' },
293
+ h2: { fontSize: '1.875rem', fontWeight: '600', lineHeight: '1.3' },
294
+ // ... h3, h4, h5, h6
295
+ },
296
+ body: {
297
+ large: { fontSize: '1.125rem', lineHeight: '1.75' },
298
+ medium: { fontSize: '1rem', lineHeight: '1.5' },
299
+ small: { fontSize: '0.875rem', lineHeight: '1.5' }
300
+ },
301
+ // ... subtitle, caption, button, label, code
302
+ }
303
+ ```
304
+
305
+ ---
306
+
307
+ ## 🌓 Theme Switching
308
+
309
+ ```tsx
310
+ // React example
311
+ function ThemeToggle() {
312
+ const [theme, setTheme] = useState('light');
313
+
314
+ const toggleTheme = () => {
315
+ const newTheme = theme === 'light' ? 'dark' : 'light';
316
+ setTheme(newTheme);
317
+ document.documentElement.classList.toggle('dark');
318
+ };
319
+
320
+ return <button onClick={toggleTheme}>Toggle Theme</button>;
321
+ }
322
+ ```
323
+
324
+ ---
325
+
326
+ ## 📚 Documentation
327
+
328
+ 📖 **[Documentação Completa](./docs/INDICE.md)** - Índice geral de toda a documentação
329
+
330
+ ### Guias Principais
331
+
332
+ - [**Guidelines**](./docs/guidelines.md) - Como usar os tokens
333
+ - [**ESTRUTURA.md**](./docs/ESTRUTURA.md) - Estrutura detalhada da biblioteca
334
+ - [**SISTEMA_BUILD.md**](./docs/SISTEMA_BUILD.md) - Sistema de build automatizado
335
+ - [**Roadmap**](./docs/roadmap.md) - Futuras features e versões
336
+ - [**GUIA_TOKENS_EXPANDIDOS**](./docs/GUIA_TOKENS_EXPANDIDOS.md) - Guia dos tokens expandidos (cores e tipografia)
337
+ - [**GUIA_MIGRACAO**](./docs/GUIA_MIGRACAO.md) - Guia de migração para v3.0.0
338
+ - [**PUBLICACAO**](./docs/PUBLICACAO.md) - Guia de publicação no GitHub/npm
339
+
340
+ ### Storybook
341
+
342
+ - [**STORYBOOK.md**](./docs/STORYBOOK.md) - Documentação visual dos tokens
343
+ - [**ESTRUTURA_STORYBOOK.md**](./docs/ESTRUTURA_STORYBOOK.md) - Separação entre tokens e componentes
344
+
345
+ ### Referência Rápida
346
+
347
+ - [**RESUMO_ESTRUTURA.md**](./docs/RESUMO_ESTRUTURA.md) - Resumo da estrutura
348
+ - [**HISTORICO_MUDANCAS.md**](./docs/HISTORICO_MUDANCAS.md) - Histórico de mudanças
349
+
350
+ ---
351
+
352
+ ## 🎯 Use Cases
353
+
354
+ ### ✅ Perfect For
355
+
356
+ - 🌐 Websites e aplicações web
357
+ - 📱 Aplicativos mobile (React Native, Flutter)
358
+ - 🖥️ Aplicações desktop (Electron, Tauri)
359
+ - 🎮 Interfaces de jogos (Unity, Unreal, Godot)
360
+ - 🎨 Design systems corporativos
361
+ - 🚀 MVPs e protótipos rápidos
362
+
363
+ ### ❌ Not Included
364
+
365
+ Esta biblioteca contém **apenas tokens**, não componentes UI.
366
+
367
+ Para componentes, use:
368
+ - [shadcn/ui](https://ui.shadcn.com/) com estes tokens
369
+ - [Radix UI](https://www.radix-ui.com/) + custom styling
370
+ - Sua própria biblioteca de componentes
371
+
372
+ ---
373
+
374
+ ## 🔧 Integration Examples
375
+
376
+ ### Next.js + Tailwind
377
+
378
+ ```typescript
379
+ // tailwind.config.ts
380
+ import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
381
+
382
+ export default tailwindConfig;
383
+ ```
384
+
385
+ ```tsx
386
+ // app/layout.tsx
387
+ export default function RootLayout({ children }: { children: React.Node }) {
388
+ return (
389
+ <html lang="pt-BR" className="dark">
390
+ <body>{children}</body>
391
+ </html>
392
+ );
393
+ }
394
+ ```
395
+
396
+ ### Vite + CSS
397
+
398
+ ```typescript
399
+ // main.ts
400
+ import '@rainersoft/design-tokens/formats/css-vars.css';
401
+ ```
402
+
403
+ ### shadcn/ui
404
+
405
+ ```typescript
406
+ // Use tokens as base for shadcn/ui theming
407
+ import { tokens } from '@rainer/design-tokens';
408
+
409
+ export const shadcnTheme = {
410
+ primary: tokens.colors.light.primary.base,
411
+ secondary: tokens.colors.light.secondary.base,
412
+ accent: tokens.colors.light.accent.base,
413
+ // ... map other tokens
414
+ };
415
+ ```
416
+
417
+ ---
418
+
419
+ ## 📦 Exports
420
+
421
+ ```typescript
422
+ // Main tokens
423
+ import { tokens } from '@rainer/design-tokens';
424
+
425
+ // Individual token categories
426
+ import {
427
+ lightThemeColors,
428
+ darkThemeColors,
429
+ typographyTokens,
430
+ spacingTokens,
431
+ radiusTokens,
432
+ shadowTokens
433
+ } from '@rainersoft/design-tokens/tokens';
434
+
435
+ // Themes
436
+ import { lightTheme, darkTheme } from '@rainersoft/design-tokens/themes';
437
+
438
+ // Formats
439
+ import { tailwindConfig } from '@rainersoft/design-tokens/formats/tailwind.config';
440
+ ```
441
+
442
+ ---
443
+
444
+ ## 🧪 Development
445
+
446
+ ```bash
447
+ # Install dependencies
448
+ pnpm install
449
+
450
+ # Build tokens (gera formats + compila TypeScript)
451
+ pnpm run build
452
+
453
+ # Gerar apenas formatos (CSS, Tailwind, JSON)
454
+ pnpm run build:formats
455
+
456
+ # Gerar formatos individuais
457
+ pnpm run build:css # Gera formats/css-vars.css
458
+ pnpm run build:tailwind # Gera formats/tailwind.config.ts
459
+ pnpm run build:tokens-json # Gera formats/tokens.json
460
+
461
+ # Storybook (visualização dos tokens)
462
+ pnpm run storybook # Inicia Storybook em http://localhost:6006
463
+ pnpm run build-storybook # Gera build estático do Storybook
464
+
465
+ # Run tests
466
+ pnpm test
467
+
468
+ # Type check
469
+ pnpm run type-check
470
+
471
+ # Lint
472
+ pnpm run lint
473
+
474
+ # Clean
475
+ pnpm run clean # Remove dist/
476
+ pnpm run clean:all # Remove node_modules, lock, dist, etc.
477
+ ```
478
+
479
+ ### 🔄 Workflow de Desenvolvimento
480
+
481
+ 1. **Edite os tokens** em `tokens/*.json` (fonte única de verdade)
482
+ 2. **Edite utilitários** em `tokens/*.ts` se necessário (accessibility, utilities)
483
+ 3. **Execute o build**: `pnpm run build:formats` (gera formatos)
484
+ 4. **Os formatos são gerados automaticamente** em `formats/`
485
+ 5. **Compile o TypeScript**: `pnpm run build` (já inclui build:formats + tsup)
486
+ 6. **Visualize no Storybook**: `pnpm run storybook` para ver todos os tokens de forma interativa
487
+ 7. **Execute testes**: `pnpm test` antes de commitar
488
+ 8. **⚠️ IMPORTANTE**: Sempre commit `dist/` após build (veja [PUBLICACAO.md](./docs/PUBLICACAO.md#-por-que-dist-está-commitado))
489
+
490
+ ### 📚 Storybook - Visualização dos Tokens
491
+
492
+ O Storybook da lib documenta **apenas design tokens**, não componentes UI.
493
+
494
+ **Stories disponíveis:**
495
+ - 🎨 **ColorPalette** - Paletas completas de cores (Light & Dark)
496
+ - 🎭 **ThemePreview** - Preview dos temas mostrando tokens em ação
497
+ - 📝 **Typography** - Sistema completo de tipografia
498
+ - 📏 **Spacing** - Escala de espaçamento (8pt grid)
499
+ - 🔲 **Radius** - Raios de borda
500
+ - 🌑 **Shadows** - Sombras e efeitos glow
501
+ - 🎬 **Animations** - Animações e keyframes (accordion, slide-in, fade-in)
502
+
503
+ **Separação de responsabilidades:**
504
+ - ✅ **Este Storybook**: Apenas tokens (cores, tipografia, espaçamento, etc.)
505
+ - ✅ **Storybook do Frontend**: Componentes UI (Button, Card, Input, etc.)
506
+
507
+ Para mais detalhes sobre a estrutura, consulte [**Estrutura do Storybook**](./docs/ESTRUTURA_STORYBOOK.md).
508
+
509
+ ---
510
+
511
+ ## 🤝 Contributing
512
+
513
+ Contributions are welcome! Please read our [Contributing Guide](./docs/CONTRIBUINDO.md) first.
514
+
515
+ ---
516
+
517
+ ## 📄 License
518
+
519
+ MIT © [Rainer Teixeira](https://github.com/RainerTeixeira)
520
+
521
+ ---
522
+
523
+ ## 🔗 Links
524
+
525
+ - **GitHub**: [RainerTeixeira/rainer-design-tokens](https://github.com/RainerTeixeira/rainer-design-tokens)
526
+ - **NPM**: [@rainersoft/design-tokens](https://www.npmjs.com/package/@rainersoft/design-tokens)
527
+ - **Website**: [rainersoft.com.br](https://rainersoft.com.br)
528
+ - **Email**: suporte@rainersoft.com.br
529
+
530
+ ## 🛠️ Tech Stack
531
+
532
+ - **Language**: TypeScript 5.3+ (strict mode)
533
+ - **Package Manager**: pnpm 9+
534
+ - **Build Tool**: tsup (TypeScript bundler)
535
+ - **Linter**: ESLint + TypeScript ESLint
536
+ - **Formatter**: Prettier
537
+ - **Testing**: Jest
538
+ - **Documentation**: Storybook 10
539
+ - **Publish**: GitHub Actions (GitHub Packages + npm)
540
+
541
+ ---
542
+
543
+ <div align="center">
544
+
545
+ **Made with ❤️ by Rainer Teixeira**
546
+
547
+ ![Built with TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue)
548
+ ![Enterprise Ready](https://img.shields.io/badge/Enterprise-Ready-success)
549
+
550
+ </div>