@react-xp/design-system 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Fábio Maia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# Component Specs (P0) — Buttons, Inputs, Modal, Card, Skeleton
+
+> Objetivo: especificações **copy-paste** e **token-first** para futura implementação React (Web + Native).  
+> Regra: **todas as properties de estilo referenciam tokens** (ou tokens P0 adicionais explicitamente listados).
+
+---
+
+## 0) Convenções (aplicável a todos)
+
+### 0.1 Estados (nomenclatura)
+
+- `default`
+- `hover` (web) / `pressed` (native)
+- `focus` (web) / `focus-visible` (web) / `focused` (native)
+- `disabled`
+- `loading` (quando aplicável)
+- `error` (inputs)
+
+### 0.2 Motion (quando houver animação)
+
+- Entrar (ex: Modal): `emphasis-enter` → `duration-regular` + `ease-emphasized`
+- Sair (ex: Modal): `emphasis-exit` → `duration-fast` + `ease-accelerated`
+- Micro feedback (hover/pressed): `micro-interaction` → `duration-fast` + `ease-standard`
+
+### 0.3 Acessibilidade (mínimos P0)
+
+- Focus sempre visível: usar `color-focus-ring`.
+- Conteúdo desativado: usar `color-state-disabled-bg` + `color-state-disabled-fg`.
+- Texto: `font-family-base`, tamanhos `font-size-*`, pesos `font-weight-*`, line-height `line-height-*`.
+
+---
+
+## 1) Tokens P0 adicionais (para evitar “magic numbers”)
+
+> Estes tokens **não estão no style guide base**, mas são recomendados para o pacote de tokens do DS,
+> porque são muito usados em componentes e garantem consistência entre Web/RN.
+
+| Token P0 sugerido            | Papel                               | Valor sugerido (P0) |
+|-----------------------------|--------------------------------------|---------------------|
+| `border-width-default`      | Borda padrão                         | `1px`               |
+| `border-width-focus`        | Borda/outline em foco                | `2px`               |
+| `opacity-pressed`           | Feedback pressed (fallback)          | `0.92`              |
+| `opacity-disabled`          | Feedback disabled (fallback)         | `1` *(preferir cores disabled)* |
+| `tap-target-min`            | Área mínima (touch)                  | `44px`              |
+| `focus-ring-gap`            | Distância do ring ao componente      | `2px`               |
+
+> Nota: sempre que possível, o “disabled” deve ser **por cor** (tokens) e não por opacity.
+
+---
+
+## 2) BUTTON (P0)
+
+### 2.1 Anatomia
+
+- Container (pressable)
+- Label (texto)
+- (Opcional) Left icon / Right icon
+- (Opcional) Spinner (loading)
+
+### 2.2 Variantes (cores por tema)
+
+| Variant      | Background token              | Foreground token               | Border token            |
+|-------------|-------------------------------|--------------------------------|-------------------------|
+| `primary`   | `color-action-primary`         | `color-action-primary-fg`      | `color-action-primary`  |
+| `secondary` | `color-action-secondary`       | `color-action-secondary-fg`    | `color-action-secondary`|
+| `ghost`     | `color-surface` *(ou transparente)* | `color-fg-default`        | `color-border-subtle`   |
+| `danger`    | `color-status-error`           | `color-status-error-fg`        | `color-status-error`    |
+
+> `ghost` usa fundo “neutro” para manter legibilidade cross-theme.
+
+### 2.3 Tamanhos (P0)
+
+| Size  | Font token     | Padding Y token | Padding X token | Radius token | Min height |
+|-------|----------------|-----------------|-----------------|-------------|-----------|
+| `sm`  | `font-size-2`  | `space-2`       | `space-3`       | `radius-3`  | `tap-target-min` |
+| `md`  | `font-size-3`  | `space-2`       | `space-4`       | `radius-3`  | `tap-target-min` |
+| `lg`  | `font-size-3`  | `space-3`       | `space-5`       | `radius-3`  | `tap-target-min` |
+
+### 2.4 Estilo (tokens por property)
+
+**Container**
+
+- `backgroundColor`: conforme variante (ex: `color-action-primary`)
+- `borderColor`: conforme variante (ex: `color-action-primary`), ou `color-border-subtle` (ghost)
+- `borderWidth`: `border-width-default`
+- `borderRadius`: `radius-3`
+- `paddingVertical`: `space-2` (md) / ver tabela
+- `paddingHorizontal`: `space-4` (md) / ver tabela
+- `shadow`:
+  - `default`: nenhum (ou `shadow-level-1` se quiseres botões “raised”)
+  - `hover` (web): `shadow-level-2`
+  - `pressed` (web+native): `shadow-level-1`
+
+**Label**
+
+- `color`: conforme variante (ex: `color-action-primary-fg`)
+- `fontFamily`: `font-family-base`
+- `fontSize`: conforme size (ex: `font-size-3`)
+- `fontWeight`: `font-weight-medium`
+- `lineHeight`: `line-height-default`
+
+**Icon**
+
+- `color`: igual ao label
+- `size`: alinhado ao `font-size-*` do botão
+
+### 2.5 Estados
+
+| State        | O que muda (token-first) |
+|--------------|---------------------------|
+| `hover`      | `shadow-level-2` + motion `micro-interaction` |
+| `pressed`    | `shadow-level-1` + (fallback) `opacity-pressed` |
+| `focus`      | `outlineColor`: `color-focus-ring` + `borderWidth`: `border-width-focus` |
+| `disabled`   | `backgroundColor`: `color-state-disabled-bg`, `labelColor`: `color-state-disabled-fg`, remover shadow |
+| `loading`    | manter cores da variante + mostrar spinner (spinner usa cor do label) |
+
+---
+
+## 3) INPUT (TextField) (P0)
+
+### 3.1 Anatomia
+
+- Label (opcional)
+- Field container (borda + fundo)
+- Text input
+- Helper text (opcional)
+- Error text (opcional)
+- (Opcional) Leading / trailing icon
+
+### 3.2 Estilo base (tokens por property)
+
+**Label**
+
+- `color`: `color-fg-muted`
+- `fontFamily`: `font-family-base`
+- `fontSize`: `font-size-2`
+- `fontWeight`: `font-weight-medium`
+- `lineHeight`: `line-height-default`
+- `marginBottom`: `space-1`
+
+**Field container**
+
+- `backgroundColor`: `color-input-bg`
+- `borderColor`: `color-input-border`
+- `borderWidth`: `border-width-default`
+- `borderRadius`: `radius-2`
+- `paddingVertical`: `space-2`
+- `paddingHorizontal`: `space-3`
+- `shadow`: nenhum
+
+**Text**
+
+- `color`: `color-fg-default`
+- `fontFamily`: `font-family-base`
+- `fontSize`: `font-size-3`
+- `lineHeight`: `line-height-default`
+
+**Placeholder**
+
+- `color`: `color-input-placeholder`
+
+**Helper**
+
+- `color`: `color-fg-subtle`
+- `fontSize`: `font-size-1`
+- `marginTop`: `space-1`
+
+### 3.3 Estados
+
+| State        | Border / Ring | Texto |
+|--------------|---------------|-------|
+| `default`    | `borderColor: color-input-border` | `color-fg-default` |
+| `focused`    | `borderColor: color-input-border-focus` + ring `color-focus-ring` | idem |
+| `disabled`   | `backgroundColor: color-state-disabled-bg` | `color: color-state-disabled-fg` |
+| `error`      | `borderColor: color-status-error` + ring `color-status-error` | helper/error usa `color-status-error` |
+
+> `error text` (linha abaixo):  
+>
+> - `color`: `color-status-error`  
+> - `fontSize`: `font-size-1`  
+> - `marginTop`: `space-1`
+
+---
+
+## 4) MODAL / DIALOG (P0)
+
+### 4.1 Anatomia
+
+- Backdrop (scrim)
+- Surface (content)
+- Header (título + optional close)
+- Body
+- Footer (ações)
+
+### 4.2 Camadas (z-layer)
+
+- Backdrop: `z-layer-overlay`
+- Modal surface: `z-layer-modal`
+
+### 4.3 Estilo (tokens por property)
+
+**Backdrop**
+
+- `backgroundColor`: `color-overlay-backdrop`
+- `zIndex`: `z-layer-overlay`
+
+**Surface**
+
+- `backgroundColor`: `color-surface`
+- `borderRadius`: `radius-4`
+- `shadow`: `shadow-level-4`
+- `padding`: `space-4` (mobile) / `space-5` (tablet/desktop)
+- `zIndex`: `z-layer-modal`
+
+**Header**
+
+- `marginBottom`: `space-3`
+- Title:
+  - `color`: `color-fg-default`
+  - `fontFamily`: `font-family-heading`
+  - `fontSize`: `font-size-5`
+  - `fontWeight`: `font-weight-strong`
+  - `lineHeight`: `line-height-tight`
+
+**Body**
+
+- `color`: `color-fg-default`
+- `fontSize`: `font-size-3`
+- `lineHeight`: `line-height-default`
+
+**Footer**
+
+- `marginTop`: `space-4`
+- `gap` entre botões: `space-2`
+
+### 4.4 Motion
+
+- Open: `emphasis-enter` (duration/easing tokens)
+- Close: `emphasis-exit` (duration/easing tokens)
+
+---
+
+## 5) CARD (P0)
+
+### 5.1 Variantes
+
+| Variant         | Background token  | Border token         | Shadow token        |
+|----------------|-------------------|----------------------|---------------------|
+| `default`      | `color-surface`   | `color-border-subtle`| `shadow-level-1`    |
+| `elevated`     | `color-surface`   | `color-border-subtle`| `shadow-level-2`    |
+| `highlight`    | `color-surface-alt` | `color-border-strong` | `shadow-level-2` |
+
+### 5.2 Estilo base
+
+- `backgroundColor`: conforme variante
+- `borderColor`: conforme variante
+- `borderWidth`: `border-width-default`
+- `borderRadius`: `radius-3`
+- `padding`: `space-4`
+- `shadow`: conforme variante
+
+**Título (opcional)**
+
+- `color`: `color-fg-default`
+- `fontFamily`: `font-family-heading`
+- `fontSize`: `font-size-4`
+- `fontWeight`: `font-weight-strong`
+- `marginBottom`: `space-2`
+
+**Texto**
+
+- `color`: `color-fg-muted`
+- `fontSize`: `font-size-3`
+- `lineHeight`: `line-height-default`
+
+### 5.3 Interação (opcional)
+
+- Hover (web): elevar `shadow-level-2` → `shadow-level-3` + motion `micro-interaction`
+
+---
+
+## 6) SKELETON (P0)
+
+### 6.1 Tipos
+
+- `text-line` (linha)
+- `avatar` (círculo)
+- `block` (retângulo para cards/imagens)
+
+### 6.2 Estilo base (token-first)
+
+- `backgroundColor`: `color-surface-alt`
+- `borderRadius`:
+  - `text-line`: `radius-2`
+  - `block`: `radius-3`
+  - `avatar`: `radius-full`
+
+### 6.3 Spacing recomendada
+
+- Entre linhas: `space-2`
+- Dentro de cards: respeitar `padding` do card (`space-4`)
+
+### 6.4 Animação (opcional)
+
+- `pulse` usando `duration-slower` + `ease-standard`
+
+> Se quiseres shimmer “clássico”, recomenda-se criar tokens próprios (ex: `duration-skeleton`).
+
+---
+
+## 7) Checklist de implementação (para React Web + RN)
+
+- Todos os componentes:
+  - Lêem tokens por tema (multi-tenant) e por modo (light/dark).
+  - Não têm cores hardcoded.
+  - Focus ring sempre: `color-focus-ring`.
+- Botão:
+  - `disabled` via `color-state-disabled-*`
+  - `loading` sem mudar layout (substitui label por spinner com a mesma largura, quando possível).
+- Input:
+  - `focused` usa `color-input-border-focus` + `color-focus-ring`
+  - `error` usa `color-status-error`
+- Modal:
+  - Backdrop `color-overlay-backdrop` + layers `z-layer-*`
+  - Motion `emphasis-enter/exit`

package/dist/cjs/helpers/a11y.js

@@ -0,0 +1,176 @@
+"use strict";
+// styles/a11y.checks.ts
+// Checker WCAG AA para pares de tokens (bg/fg)
+// - Útil para CI: garante contraste mínimo no tema (multi-tenant).
+// - Sem deps externas.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertThemeContrast = exports.getContrastFailures = exports.validateThemeContrast = exports.defaultContrastRules = void 0;
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+const parseHex = (hex) => {
+    // #RGB, #RRGGBB
+    const h = hex.trim();
+    if (!h.startsWith('#'))
+        return null;
+    const raw = h.slice(1);
+    if (raw.length === 3 && raw[0] && raw[1] && raw[2]) {
+        const r = Number.parseInt(raw[0] + raw[0], 16);
+        const g = Number.parseInt(raw[1] + raw[1], 16);
+        const b = Number.parseInt(raw[2] + raw[2], 16);
+        return { r, g, b, a: 1 };
+    }
+    if (raw.length === 6) {
+        const r = Number.parseInt(raw.slice(0, 2), 16);
+        const g = Number.parseInt(raw.slice(2, 4), 16);
+        const b = Number.parseInt(raw.slice(4, 6), 16);
+        return { r, g, b, a: 1 };
+    }
+    return null;
+};
+const parseRgbLike = (input) => {
+    // rgb(0,0,0) / rgba(0,0,0,0.5)
+    const m = input.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([0-9.]+))?\s*\)/i);
+    if (!m)
+        return null;
+    const r = Number(m[1]);
+    const g = Number(m[2]);
+    const b = Number(m[3]);
+    const a = m[4] ? Number(m[4]) : 1;
+    return { r, g, b, a: clamp01(a) };
+};
+const parseColor = (input) => {
+    if (typeof input !== 'string')
+        return null;
+    // Nota: se usares tokens tipo "var(--x)" isto não consegue resolver.
+    // Ideal: no tema final, tokens sejam cores concretas (#hex / rgb(a)).
+    return parseHex(input) ?? parseRgbLike(input);
+};
+const srgbToLinear = (c) => {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+const relativeLuminance = (rgb) => {
+    const r = srgbToLinear(rgb.r);
+    const g = srgbToLinear(rgb.g);
+    const b = srgbToLinear(rgb.b);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+const contrastRatio = (a, b) => {
+    // WCAG formula (ignora alpha — assume cores finais já resolvidas)
+    const L1 = relativeLuminance(a);
+    const L2 = relativeLuminance(b);
+    const light = Math.max(L1, L2);
+    const dark = Math.min(L1, L2);
+    return (light + 0.05) / (dark + 0.05);
+};
+const threshold = (level, size) => {
+    if (level === 'AAA')
+        return size === 'large' ? 4.5 : 7;
+    return size === 'large' ? 3 : 4.5;
+};
+const defaultContrastRules = () => [
+    // Base surfaces
+    {
+        name: 'Default BG / Default FG',
+        bg: 'color-bg-default',
+        fg: 'color-fg-default',
+    },
+    { name: 'Surface / Default FG', bg: 'color-surface', fg: 'color-fg-default' },
+    {
+        name: 'Surface-alt / Default FG',
+        bg: 'color-surface-alt',
+        fg: 'color-fg-default',
+    },
+    {
+        name: 'Default BG / Muted FG',
+        bg: 'color-bg-default',
+        fg: 'color-fg-muted',
+    },
+    // Actions
+    {
+        name: 'Primary Action',
+        bg: 'color-action-primary',
+        fg: 'color-action-primary-fg',
+    },
+    {
+        name: 'Secondary Action',
+        bg: 'color-action-secondary',
+        fg: 'color-action-secondary-fg',
+    },
+    { name: 'Accent', bg: 'color-accent', fg: 'color-accent-fg' },
+    // Status
+    {
+        name: 'Success',
+        bg: 'color-status-success',
+        fg: 'color-status-success-fg',
+    },
+    {
+        name: 'Warning',
+        bg: 'color-status-warning',
+        fg: 'color-status-warning-fg',
+    },
+    { name: 'Error', bg: 'color-status-error', fg: 'color-status-error-fg' },
+    { name: 'Info', bg: 'color-status-info', fg: 'color-status-info-fg' },
+    // Inputs (texto/placeholder em fundo input)
+    {
+        name: 'Input BG / Default FG',
+        bg: 'color-input-bg',
+        fg: 'color-fg-default',
+    },
+    {
+        name: 'Input BG / Placeholder',
+        bg: 'color-input-bg',
+        fg: 'color-input-placeholder',
+        textSize: 'large',
+    }, // placeholder pode ser menos exigente; ajusta se quiseres
+    // Inverted (tooltip/overlays)
+    {
+        name: 'Inverted FG on Default FG',
+        bg: 'color-fg-default',
+        fg: 'color-fg-on-inverted',
+    },
+    // Disabled
+    {
+        name: 'Disabled BG / Disabled FG',
+        bg: 'color-state-disabled-bg',
+        fg: 'color-state-disabled-fg',
+        textSize: 'large',
+    },
+];
+exports.defaultContrastRules = defaultContrastRules;
+const validateThemeContrast = (tokens, rules = (0, exports.defaultContrastRules)()) => {
+    return rules.map((r) => {
+        const bgRaw = tokens[r.bg];
+        const fgRaw = tokens[r.fg];
+        const bg = parseColor(bgRaw);
+        const fg = parseColor(fgRaw);
+        // Se não conseguimos parse, falha (porque não dá para validar)
+        if (!bg || !fg) {
+            return {
+                rule: r,
+                contrastRatio: 0,
+                pass: false,
+            };
+        }
+        const ratio = contrastRatio(bg, fg);
+        const lvl = r.level ?? 'AA';
+        const size = r.textSize ?? 'normal';
+        const pass = ratio >= threshold(lvl, size);
+        return { rule: r, contrastRatio: ratio, pass };
+    });
+};
+exports.validateThemeContrast = validateThemeContrast;
+const getContrastFailures = (results) => results.filter((r) => !r.pass);
+exports.getContrastFailures = getContrastFailures;
+const assertThemeContrast = (tokens, rules) => {
+    const results = (0, exports.validateThemeContrast)(tokens, rules);
+    const fails = (0, exports.getContrastFailures)(results);
+    if (fails.length === 0)
+        return;
+    const lines = fails.map((f) => {
+        const lvl = f.rule.level ?? 'AA';
+        const size = f.rule.textSize ?? 'normal';
+        return `- ${f.rule.name}: ${String(f.rule.bg)} / ${String(f.rule.fg)} => ${f.contrastRatio.toFixed(2)} (min ${threshold(lvl, size)})`;
+    });
+    throw new Error(`Theme contrast validation failed:\n${lines.join('\n')}`);
+};
+exports.assertThemeContrast = assertThemeContrast;

package/dist/cjs/helpers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./a11y"), exports);
+__exportStar(require("./styles"), exports);