@fabio.caffarello/react-design-system 1.7.0 → 1.8.0

package/src/ui/themes/utils.ts

@@ -0,0 +1,70 @@
+/**
+ * Theme Utilities
+ * 
+ * Helper functions for theme operations.
+ */
+
+/**
+ * Deep merge utility
+ */
+export function mergeDeep<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: Partial<T>[]
+): T {
+  if (!sources.length) return target;
+  const source = sources.shift();
+
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, { [key]: {} });
+        mergeDeep(target[key], source[key]);
+      } else {
+        Object.assign(target, { [key]: source[key] });
+      }
+    }
+  }
+
+  return mergeDeep(target, ...sources);
+}
+
+/**
+ * Check if value is an object
+ */
+function isObject(item: unknown): item is Record<string, unknown> {
+  return item && typeof item === 'object' && !Array.isArray(item);
+}
+
+/**
+ * Convert CSS variable name to kebab-case
+ */
+export function toCSSVariableName(name: string): string {
+  return name
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+
+/**
+ * Apply CSS variables to element
+ */
+export function applyCSSVariables(
+  element: HTMLElement,
+  variables: Record<string, string>
+): void {
+  for (const [key, value] of Object.entries(variables)) {
+    element.style.setProperty(key, value);
+  }
+}
+
+/**
+ * Remove CSS variables from element
+ */
+export function removeCSSVariables(
+  element: HTMLElement,
+  variableNames: string[]
+): void {
+  for (const name of variableNames) {
+    element.style.removeProperty(name);
+  }
+}

package/src/ui/tokens/README.md

@@ -0,0 +1,212 @@
+# Design Tokens System
+
+Este documento descreve o sistema de design tokens do `react-design-system`, que fornece valores centralizados e consistentes para cores, espaçamento, tipografia, sombras, bordas, raios e breakpoints.
+
+## Visão Geral
+
+O sistema de tokens utiliza o **Factory Pattern** para criar tokens de forma type-safe e consistente. Todos os tokens seguem uma estrutura padronizada e podem ser acessados através de helper functions.
+
+## Estrutura de Tokens
+
+### 1. Colors (`colors.ts`)
+
+Sistema de cores semânticas com suporte a temas claro e escuro.
+
+**Roles**: `primary`, `secondary`, `success`, `warning`, `error`, `info`, `neutral`
+
+**Shades**: `light`, `DEFAULT`, `dark`, `contrast`
+
+**Uso:**
+```typescript
+import { getColorClass, COLOR_TOKENS } from './tokens/colors';
+
+// Obter classe Tailwind
+const bgClass = getColorClass('primary', 'DEFAULT', 'bg'); // 'bg-indigo-500'
+const textClass = getColorClass('error', 'dark', 'text'); // 'text-red-600'
+
+// Acessar token diretamente
+const primaryColor = COLOR_TOKENS.primary.DEFAULT.hex; // '#6366f1'
+```
+
+### 2. Spacing (`spacing.ts`)
+
+Sistema de espaçamento baseado em unidades de 4px.
+
+**Escala**: `xs` (4px), `sm` (8px), `md` (12px), `base` (16px), `lg` (24px), `xl` (32px), `2xl` (40px), `3xl` (48px), `4xl` (64px), `5xl` (80px), `6xl` (96px)
+
+**Uso:**
+```typescript
+import { getSpacingClass, SPACING_TOKENS } from './tokens/spacing';
+
+// Obter classe Tailwind
+const paddingClass = getSpacingClass('md', 'p'); // 'p-3'
+const marginClass = getSpacingClass('lg', 'mx'); // 'mx-6'
+
+// Acessar token diretamente
+const mdSpacing = SPACING_TOKENS.md.px; // '12px'
+```
+
+### 3. Typography (`typography.ts`)
+
+Sistema de tipografia com tamanhos, pesos e line heights.
+
+**Tamanhos**: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl`
+
+**Pesos**: `light`, `normal`, `medium`, `semibold`, `bold`
+
+**Line Heights**: `none`, `tight`, `snug`, `normal`, `relaxed`, `loose`
+
+**Uso:**
+```typescript
+import { getTypographyClasses, TYPOGRAPHY_TOKENS } from './tokens/typography';
+
+// Obter classes completas
+const headingClasses = getTypographyClasses('h1'); // 'text-4xl leading-tight font-bold'
+
+// Acessar token diretamente
+const h1Size = TYPOGRAPHY_TOKENS.h1.fontSize.px; // '36px'
+```
+
+### 4. Shadows (`shadows.ts`)
+
+Sistema de sombras para elevação e profundidade.
+
+**Tamanhos**: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner`
+
+**Uso:**
+```typescript
+import { getShadowClass, SHADOW_TOKENS } from './tokens/shadows';
+
+// Obter classe Tailwind
+const shadowClass = getShadowClass('lg'); // 'shadow-lg'
+
+// Acessar token diretamente
+const lgShadow = SHADOW_TOKENS.lg.value; // '0 4px 6px -1px rgb(0 0 0 / 0.1)...'
+```
+
+### 5. Radius (`radius.ts`)
+
+Sistema de border radius para cantos arredondados.
+
+**Tamanhos**: `none`, `sm` (2px), `md` (6px), `lg` (8px), `xl` (12px), `2xl` (16px), `3xl` (24px), `full`
+
+**Uso:**
+```typescript
+import { getRadiusClass, RADIUS_TOKENS } from './tokens/radius';
+
+// Obter classe Tailwind
+const radiusClass = getRadiusClass('lg'); // 'rounded-lg'
+
+// Acessar token diretamente
+const lgRadius = RADIUS_TOKENS.lg.px; // '8px'
+```
+
+### 6. Borders (`borders.ts`)
+
+Sistema de bordas para larguras e estilos.
+
+**Larguras**: `none`, `thin` (1px), `base` (1px), `medium` (2px), `thick` (4px)
+
+**Estilos**: `solid`, `dashed`, `dotted`
+
+**Uso:**
+```typescript
+import { getBorderWidthClass, getBorderStyleClass, getBorderClasses, BORDER_TOKENS } from './tokens/borders';
+
+// Obter classes
+const widthClass = getBorderWidthClass('base'); // 'border'
+const styleClass = getBorderStyleClass('solid'); // 'border-solid'
+const fullBorder = getBorderClasses('base', 'solid'); // 'border border-solid'
+
+// Acessar token diretamente
+const baseBorder = BORDER_TOKENS.base.width.px; // '1px'
+```
+
+### 7. Breakpoints (`breakpoints.ts`)
+
+Sistema de breakpoints responsivos.
+
+**Breakpoints**: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px)
+
+**Uso:**
+```typescript
+import { BREAKPOINT_TOKENS } from './tokens/breakpoints';
+
+// Acessar breakpoint
+const mdBreakpoint = BREAKPOINT_TOKENS.md.value; // 768
+```
+
+## Tokens Factory
+
+O `TokensFactory` fornece uma interface unificada para criar todos os tipos de tokens:
+
+```typescript
+import { TokensFactory } from './tokens/tokens.factory';
+
+const factory = new TokensFactory('light');
+const tokenSet = factory.createTokenSet();
+
+// Acessar todos os tokens
+const spacing = tokenSet.spacing;
+const colors = tokenSet.colors;
+const shadows = tokenSet.shadows;
+```
+
+## Padrões de Uso
+
+### ✅ Usar Tokens
+
+```typescript
+import { getColorClass } from './tokens/colors';
+import { getSpacingClass } from './tokens/spacing';
+import { getRadiusClass } from './tokens/radius';
+import { getShadowClass } from './tokens/shadows';
+
+const className = `
+  ${getColorClass('primary', 'DEFAULT', 'bg')}
+  ${getSpacingClass('md', 'p')}
+  ${getRadiusClass('lg')}
+  ${getShadowClass('md')}
+`;
+```
+
+### ❌ Evitar Classes Hardcoded
+
+```typescript
+// ❌ Evitar
+const className = 'bg-indigo-500 p-3 rounded-lg shadow-md';
+
+// ✅ Preferir
+const className = `
+  ${getColorClass('primary', 'DEFAULT', 'bg')}
+  ${getSpacingClass('md', 'p')}
+  ${getRadiusClass('lg')}
+  ${getShadowClass('md')}
+`;
+```
+
+## Migração de Classes Hardcoded
+
+Ao refatorar componentes, substitua classes hardcoded por tokens:
+
+1. **Cores**: `bg-gray-500` → `getColorClass('neutral', 'DEFAULT', 'bg')`
+2. **Espaçamento**: `p-4` → `getSpacingClass('base', 'p')`
+3. **Sombras**: `shadow-lg` → `getShadowClass('lg')`
+4. **Radius**: `rounded-md` → `getRadiusClass('md')`
+5. **Bordas**: `border-2` → `getBorderWidthClass('medium')`
+
+## Benefícios
+
+1. **Consistência**: Valores centralizados garantem consistência visual
+2. **Manutenibilidade**: Mudanças em um lugar refletem em todo o sistema
+3. **Type Safety**: TypeScript garante uso correto dos tokens
+4. **Temas**: Suporte fácil a temas claro/escuro
+5. **Documentação**: Tokens são auto-documentados com descrições
+
+## Próximos Passos
+
+- [ ] Auditar todos os componentes para uso de tokens
+- [ ] Substituir classes hardcoded por tokens
+- [ ] Adicionar tokens para animações e transições
+- [ ] Criar tokens para z-index layers
+- [ ] Documentar tokens no Storybook

package/src/ui/tokens/TokenVisualizations.tsx

@@ -0,0 +1,273 @@
+/**
+ * Token Visualization Components
+ * 
+ * React components for visualizing design tokens in Storybook
+ */
+
+import React from 'react';
+import { 
+  COLOR_TOKENS_LIGHT,
+  SPACING_TOKENS,
+  SHADOW_TOKENS,
+  RADIUS_TOKENS,
+  ANIMATION_TOKENS,
+  Z_INDEX_TOKENS,
+  OPACITY_TOKENS,
+  GRADIENT_TOKENS,
+  type ColorRole,
+} from './index';
+
+/**
+ * Color Palette Visualization
+ */
+export function ColorPalette() {
+  const colorRoles: ColorRole[] = ['primary', 'secondary', 'success', 'warning', 'error', 'info', 'neutral'];
+
+  return (
+    <div className="space-y-6">
+      {colorRoles.map(role => {
+        const color = COLOR_TOKENS_LIGHT[role];
+        return (
+          <div key={role} className="space-y-2">
+            <h3 className="text-sm font-semibold text-gray-700 capitalize">{role}</h3>
+            <div className="flex gap-2">
+              <ColorSwatch
+                label="light"
+                color={color.light.hex}
+                textColor={color.light.contrast || '#000'}
+              />
+              <ColorSwatch
+                label="DEFAULT"
+                color={color.DEFAULT.hex}
+                textColor={color.DEFAULT.contrast || '#fff'}
+              />
+              <ColorSwatch
+                label="dark"
+                color={color.dark.hex}
+                textColor={color.dark.contrast || '#fff'}
+              />
+              <ColorSwatch
+                label="contrast"
+                color={color.contrast.hex}
+                textColor={color.DEFAULT.hex}
+              />
+            </div>
+            <div className="text-xs text-gray-500 space-y-1">
+              <div>Light: {color.light.hex} ({color.light.tailwind})</div>
+              <div>Default: {color.DEFAULT.hex} ({color.DEFAULT.tailwind})</div>
+              <div>Dark: {color.dark.hex} ({color.dark.tailwind})</div>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function ColorSwatch({ label, color, textColor }: { label: string; color: string; textColor: string }) {
+  return (
+    <div className="flex flex-col items-center gap-1">
+      <div
+        className="w-20 h-20 rounded-md border border-gray-200 flex items-center justify-center text-xs font-medium"
+        style={{ backgroundColor: color, color: textColor }}
+      >
+        {label}
+      </div>
+      <span className="text-xs text-gray-600">{label}</span>
+    </div>
+  );
+}
+
+/**
+ * Spacing Reference Visualization
+ */
+export function SpacingReference() {
+  const spacingEntries = Object.entries(SPACING_TOKENS);
+
+  return (
+    <div className="space-y-4">
+      {spacingEntries.map(([key, token]) => (
+        <div key={key} className="flex items-center gap-4">
+          <div className="w-32 text-sm font-medium text-gray-700">{key}</div>
+          <div className="flex-1 flex items-center gap-2">
+            <div
+              className="bg-indigo-500 h-4"
+              style={{ width: token.px }}
+            />
+            <span className="text-xs text-gray-600">{token.px} ({token.rem})</span>
+          </div>
+          <div className="w-24 text-xs text-gray-500 font-mono">{token.tailwind}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Typography Reference Visualization
+ */
+export function TypographyReference() {
+  const typographyEntries = [
+    { name: 'h1', size: '4xl', weight: 'bold', lineHeight: 'tight' },
+    { name: 'h2', size: '3xl', weight: 'bold', lineHeight: 'tight' },
+    { name: 'h3', size: '2xl', weight: 'semibold', lineHeight: 'snug' },
+    { name: 'body', size: 'base', weight: 'normal', lineHeight: 'relaxed' },
+    { name: 'label', size: 'sm', weight: 'medium', lineHeight: 'normal' },
+    { name: 'caption', size: 'xs', weight: 'normal', lineHeight: 'normal' },
+  ];
+
+  return (
+    <div className="space-y-4">
+      {typographyEntries.map(({ name, size, weight, lineHeight }) => (
+        <div key={name} className="border-b border-gray-200 pb-4">
+          <div className="flex items-baseline gap-4">
+            <div className="w-24 text-sm font-medium text-gray-700">{name}</div>
+            <div className={`text-${size} font-${weight} leading-${lineHeight}`}>
+              The quick brown fox jumps over the lazy dog
+            </div>
+          </div>
+          <div className="mt-2 text-xs text-gray-500">
+            Size: {size} | Weight: {weight} | Line Height: {lineHeight}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Shadow Reference Visualization
+ */
+export function ShadowReference() {
+  const shadowEntries = Object.entries(SHADOW_TOKENS);
+
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      {shadowEntries.map(([key, token]) => (
+        <div key={key} className="space-y-2">
+          <div className="text-sm font-medium text-gray-700">{key}</div>
+          <div
+            className="w-full h-20 bg-white rounded-md flex items-center justify-center"
+            style={{ boxShadow: token.value }}
+          >
+            <span className="text-xs text-gray-600">{token.description}</span>
+          </div>
+          <div className="text-xs text-gray-500 font-mono">{token.tailwind}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Radius Reference Visualization
+ */
+export function RadiusReference() {
+  const radiusEntries = Object.entries(RADIUS_TOKENS);
+
+  return (
+    <div className="grid grid-cols-4 gap-4">
+      {radiusEntries.map(([key, token]) => (
+        <div key={key} className="space-y-2">
+          <div className="text-sm font-medium text-gray-700">{key}</div>
+          <div
+            className="w-20 h-20 bg-indigo-500"
+            style={{ borderRadius: token.px }}
+          />
+          <div className="text-xs text-gray-500">{token.px}</div>
+          <div className="text-xs text-gray-500 font-mono">{token.tailwind}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Animation Reference Visualization
+ */
+export function AnimationReference() {
+  const animationEntries = Object.entries(ANIMATION_TOKENS);
+
+  return (
+    <div className="space-y-4">
+      {animationEntries.map(([key, token]) => (
+        <div key={key} className="border-b border-gray-200 pb-4">
+          <div className="text-sm font-medium text-gray-700 mb-2">{key}</div>
+          <div className="space-y-1 text-xs text-gray-600">
+            <div>Duration: {token.duration.value} ({token.duration.ms}ms)</div>
+            <div>Easing: {token.easing.description}</div>
+            <div className="font-mono">{token.duration.tailwind} {token.easing.tailwind}</div>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Z-Index Reference Visualization
+ */
+export function ZIndexReference() {
+  const zIndexEntries = Object.entries(Z_INDEX_TOKENS).sort((a, b) => b[1].value - a[1].value);
+
+  return (
+    <div className="space-y-2">
+      {zIndexEntries.map(([key, token]) => (
+        <div key={key} className="flex items-center gap-4 border-b border-gray-200 pb-2">
+          <div className="w-32 text-sm font-medium text-gray-700">{key}</div>
+          <div className="flex-1">
+            <div className="text-xs text-gray-600">{token.description}</div>
+          </div>
+          <div className="w-24 text-xs text-gray-500 font-mono">{token.tailwind}</div>
+          <div className="w-16 text-xs text-gray-500 text-right">{token.value}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Opacity Reference Visualization
+ */
+export function OpacityReference() {
+  const opacityEntries = Object.entries(OPACITY_TOKENS);
+
+  return (
+    <div className="grid grid-cols-5 gap-4">
+      {opacityEntries.map(([key, token]) => (
+        <div key={key} className="space-y-2">
+          <div className="text-sm font-medium text-gray-700">{key}</div>
+          <div
+            className="w-full h-16 bg-indigo-500 rounded-md"
+            style={{ opacity: token.decimal }}
+          />
+          <div className="text-xs text-gray-500">{token.value}%</div>
+          <div className="text-xs text-gray-500 font-mono">{token.tailwind}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Gradient Reference Visualization
+ */
+export function GradientReference() {
+  const gradientEntries = Object.entries(GRADIENT_TOKENS);
+
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      {gradientEntries.map(([key, token]) => (
+        <div key={key} className="space-y-2">
+          <div className="text-sm font-medium text-gray-700">{key}</div>
+          <div
+            className="w-full h-20 rounded-md"
+            style={{ background: token.value }}
+          />
+          <div className="text-xs text-gray-500">{token.description}</div>
+          <div className="text-xs text-gray-500 font-mono break-all">{token.tailwind}</div>
+        </div>
+      ))}
+    </div>
+  );
+}