@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 |

Idioma de los componentes (i18n)

La librería trae sus propias traducciones de los textos que genera por su cuenta —paginación, aria-labels, estados vacíos, nombres de mes—. La app solo indica el idioma:

import { RqProvider } from "@regcheq/ui";
import { useLocale } from "next-intl";

function Layout({ children }) {
  const locale = useLocale();
  return <RqProvider locale={locale}>{children}</RqProvider>;
}

Idiomas incluidos: es (default), en, br (portugués de Brasil) y zh. Acepta BCP47 (pt-BR, es-MX) o códigos cortos, y cae a español si no reconoce el código.

El mismo locale alimenta el formateo de fechas y porcentajes vía Intl, no solo los textos.

Qué se traduce. Solo el chrome —el texto que el componente genera por su cuenta—. El contenido (placeholder, title, children) sigue pasándose por props normales, porque cambia en cada uso.

Sobreescribir. Solo para terminología propia. Es parcial hasta el nivel de clave, y la precedencia se evalúa clave por clave: prop del componente → prop del RqProvider → diccionario del idioma → español.

// en toda la app
<RqProvider locale={locale} labels={{ dataTable: { filterPlaceholder: "Buscar" } }}>

// solo en esta instancia
<RqDataTable labels={{ filterPlaceholder: "Buscar" }} columns={cols} data={data} />

Sin RqProvider los componentes funcionan igual, cayendo al español.

Guía completa, grupos del catálogo y cómo agregar un idioma → ver docs/i18n.md.

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.