@regcheq/ui

Librería interna de componentes UI para aplicaciones Regcheq. Basada en Radix UI + Tailwind CSS v4 + CVA (class-variance-authority), con salida dual CJS + ESM.

Objetivos

• Componentes accesibles y consistentes basados en Radix UI.
• Sistema de tokens semánticos --rq-* para theming centralizado.
• Variantes visuales definidas con CVA — sin clases condicionales ad-hoc.
• Exports con prefijo Rq para evitar colisiones de nombres en los consumidores.
• Build dual (CJS + ESM) para compatibilidad con proyectos Next.js, Vite y CRA.

Instalación

npm i @regcheq/ui

Además, el proyecto usa Tailwind CSS v4. Asegúrate de importar los estilos base en tu app:

import "@regcheq/ui/styles";

Requisitos para desarrollo

El proyecto usa Node 22. Con nvm instalado:

nvm use
npm ci

El archivo .nvmrc fija la versión; nvm use cambia al Node correcto automáticamente.

Husky ejecuta antes de cada commit:

• pre-commit: npm run lint y npm run test (no se permite commit si fallan).
• commit-msg: commitlint para que los mensajes sigan Conventional Commits (ej. feat:, fix:, chore:). Evita commits con mensajes mal formados.

Guía rápida: integrar en tu primera app (React + Vite)

1. Instalar la dependencia

npm i @regcheq/ui

2. Importar estilos base

En el punto de entrada de tu app (ej. src/main.tsx):

import "@regcheq/ui/styles";

3. Envolver la app con RqProvider

RqProvider provee el contexto necesario para componentes como tooltips y popovers de Radix:

// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { RqProvider } from "@regcheq/ui";
import "@regcheq/ui/styles";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <RqProvider>
      <App />
    </RqProvider>
  </React.StrictMode>
);

4. Usar componentes

import { RqButton, RqInput, RqAlert } from "@regcheq/ui";

export function LoginForm() {
  return (
    <form>
      <RqAlert variant="info">Ingresa tus credenciales.</RqAlert>
      <RqInput placeholder="Correo electrónico" type="email" />
      <RqButton variant="primary" type="submit">Ingresar</RqButton>
    </form>
  );
}

5. Resumen de pasos

| Paso | Acción | |------|--------| | 1 | npm i @regcheq/ui | | 2 | Importar "@regcheq/ui/styles" en el entry point. | | 3 | Envolver la app con <RqProvider>. | | 4 | Importar y usar los componentes con prefijo Rq. |

Uso básico

import {
  RqButton,
  RqInput,
  RqPasswordInput,
  RqTextarea,
  RqSelect, RqSelectTrigger, RqSelectContent, RqSelectItem, RqSelectValue,
  RqAlert,
  RqCard,
  RqLabel,
  RqSeparator,
  RqCalendar,
  RqDatePickerInput,
  RqSidebar, RqSidebarContent, RqSidebarItem, RqSidebarFooter, RqSidebarToggle,
  RqDrawer, RqDrawerContent, RqDrawerHeader, RqDrawerTitle,
} from "@regcheq/ui";

Componentes disponibles

| Componente | Descripción | |------------|-------------| | RqButton | Botón con variantes primary, secondary, tertiary, ghost | | RqInput | Input de texto base | | RqPasswordInput | Input de contraseña con toggle de visibilidad | | RqTextarea | Área de texto multilínea | | RqLabel | Etiqueta accesible para campos de formulario | | RqSelect + partes | Select accesible basado en Radix Select | | RqPopover + partes | Popover basado en Radix Popover | | RqCalendar | Calendario de selección de fechas (react-day-picker) | | RqDatePickerInput | Input con picker de fecha integrado | | RqAlert | Alerta con variantes info, success, warning, error | | RqCard | Tarjeta contenedora | | RqSeparator | Divisor horizontal/vertical | | RqField + partes | Sistema de layout para campos de formulario | | RqFormField + partes | Integración con react-hook-form | | RqInputGroup + partes | Input con addons (prefijo / sufijo / botón) | | RqSidebar + partes | Sidebar colapsable con hover-expand | | RqDrawer + partes | Drawer (panel deslizante) con soporte multi-dirección | | RqLogo + variantes | Logos y marcas de Regcheq | | RqProvider | Proveedor de contexto global de la librería |

Design Tokens

Los tokens viven en un solo lugar (src/styles/tokens.css) y todos los proyectos consumidores los obtienen automáticamente al hacer pnpm update @regcheq/ui.

Arquitectura de dos capas

Capa 1 — Primitivos     :root { --rq-navy-950: 240 97% 14%; }
              ↓
Capa 2 — Semánticos     :root { --color-rq-brand: hsl(var(--rq-navy-950)); }
              ↓
Tailwind v4             @theme inline { --color-rq-brand: ... }
Tailwind v3             tailwind-preset.cjs → colors: { "rq-brand": "hsl(var(...) / <alpha-value>)" }

• Capa 1 (primitivos): valores HSL sin semántica. Nunca se usan directamente en componentes.
• Capa 2 (semánticos): asignan significado (brand, surface, text, border, focus, status).

Exports disponibles

| Import | Archivo | Uso | |---|---|---| | @regcheq/ui | dist/index.js | Componentes React | | @regcheq/ui/styles | dist/index.css | CSS compilado (componentes + tokens) | | @regcheq/ui/tokens.css | dist/styles/tokens.css | Solo variables CSS (sin Tailwind) | | @regcheq/ui/tailwind-preset | tailwind-preset.cjs | Preset para Tailwind v3 |

Setup en proyecto nuevo — Tailwind v3

1. Importar el CSS en el layout principal:

// app/layout.tsx
import "@regcheq/ui/styles";  // provee todos los tokens en :root automáticamente
import "@/app/globals.css";

2. Configurar tailwind.config.js:

import { createRequire } from "node:module";
import { realpathSync } from "node:fs";

const require = createRequire(import.meta.url);
const rqPreset = require("@regcheq/ui/tailwind-preset");

let regcheqUiRoot;
try {
  regcheqUiRoot = realpathSync("./node_modules/@regcheq/ui").replaceAll("\\", "/");
} catch {
  regcheqUiRoot = "./node_modules/@regcheq/ui";
}

export default {
  presets: [rqPreset],  // ← tokens rq-* + spacing/zIndex/shadow/radius
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    `${regcheqUiRoot}/dist/**/*.js`,
  ],
  theme: {
    extend: {
      // Solo tokens específicos de este proyecto
    },
  },
};

No copiar ni duplicar las variables --rq-* en el globals.css propio del proyecto.

Setup en proyecto nuevo — Tailwind v4

/* globals.css */
@import "@regcheq/ui/tokens.css";
@import "tailwindcss";

// layout.tsx
import "@regcheq/ui/styles";

Agregar un token nuevo

Sigue estos 4 pasos en orden:

1. Primitivo en src/styles/tokens.css

--rq-purple-600: 270 60% 45%;

2. Semántico en src/styles/tokens.css

--color-rq-status-neutral: hsl(var(--rq-purple-600));

3. Registrar en @theme inline de src/styles/globals.css (para Tailwind v4)

@theme inline {
  --color-rq-status-neutral: hsl(var(--rq-purple-600));
}

4. Registrar en tailwind-preset.cjs (para Tailwind v3)

colors: {
  "rq-status-neutral": "hsl(var(--rq-purple-600) / <alpha-value>)",
}

Luego pnpm build y pnpm publish. Los proyectos consumidores hacen pnpm update @regcheq/ui — sin cambios manuales de su parte.

No es necesario tocar package.json al agregar tokens. Los exports apuntan a archivos fijos; solo cambia su contenido.

Referencia de tokens

| Token Tailwind | Variable CSS | Rol | |---|---|---| | rq-brand | --color-rq-brand | Color principal de marca | | rq-brand-on | --color-rq-brand-on | Texto sobre fondo brand | | rq-brand-hover | --color-rq-brand-hover | Estado hover de brand | | rq-brand-subtle | --color-rq-brand-subtle | Fondo sutil de marca | | rq-surface | --color-rq-surface | Fondo base de superficies | | rq-surface-raised | --color-rq-surface-raised | Fondo elevado / hover | | rq-surface-selected | --color-rq-surface-selected | Fondo seleccionado | | rq-text | --color-rq-text | Texto principal | | rq-text-subtle | --color-rq-text-subtle | Texto secundario / muted | | rq-border | --color-rq-border | Borde estándar | | rq-border-subtle | --color-rq-border-subtle | Borde sutil | | rq-focus | --color-rq-focus | Anillo de foco (inputs) | | rq-focus-brand | --color-rq-focus-brand | Anillo de foco (botones) | | rq-status-success / -subtle | --color-rq-status-success | Estado éxito | | rq-status-error / -subtle | --color-rq-status-error | Estado error | | rq-status-warning / -subtle | --color-rq-status-warning | Estado advertencia | | rq-status-info / -subtle | --color-rq-status-info | Estado información | | rq-status-notification / -subtle | --color-rq-status-notification | Estado notificación | | shadow-rq-surface | --rq-shadow-surface | Sombra estándar de superficies | | z-rq-overlay | --rq-z-overlay | Z-index de overlay (9999) |

Versioning (SemVer)

Este paquete sigue SemVer:

• PATCH: fixes internos sin cambios de API.
• MINOR: nuevos componentes o props compatibles.
• MAJOR: cambios que rompen compatibilidad (props eliminadas, renombradas, comportamientos incompatibles).

Commits (Conventional Commits)

El release automático usa Conventional Commits. Ejemplos:

• feat: agrega componente Badge → MINOR
• fix: corrige clases de focus en Input → PATCH
• feat!: renombra prop variant en Alert → MAJOR

O con breaking change explícito:

feat: agrega componente Badge

BREAKING CHANGE: el export RqBadge reemplaza a RqTag (eliminado)

Tipos comunes: feat, fix, chore, docs, refactor, test.

Scripts útiles

npm test              # Jest — todos los tests
npm run test:watch    # Jest en modo watch
npm run test:coverage # Reporte de cobertura
npm run coverage:ci   # Cobertura en formato lcov (para SonarCloud)
npm run typecheck     # tsc --noEmit
npm run lint          # ESLint
npm run lint:fix      # Auto-fix ESLint
npm run format        # Prettier
npm run storybook     # Storybook en localhost:6006
npm run build         # Build de la librería (dist/)

Storybook

El catálogo de componentes se publica automáticamente en GitLab Pages en cada merge a master. Para verlo en local:

npm run storybook

Accede a http://localhost:6006.

Desarrollo de nuevos componentes

Sigue el patrón de la carpeta src/components/ui/<component-name>/:

badge/
├── badge.tsx          ← componente con forwardRef + CVA
├── badge.test.tsx     ← tests co-localizados
└── index.ts           ← barrel local

Registra el nuevo componente en src/components/ui/index.ts con prefijo Rq y crea su story en stories/<component-name>.stories.tsx.

Consulta el archivo CLAUDE.md en la raíz para la guía completa de convenciones.