regcheq-ui-vue-2

Librería de componentes UI de RegCheq para proyectos Vue 2. Documenta y distribuye los componentes del design system oficial, sincronizados directamente desde Figma.

Tabla de contenidos

• Descripción
• Requisitos
• Instalación
• Levantar Storybook
• Estructura del proyecto
• Design Tokens
  • Colores
  • Tipografía
  • Elevaciones
• Crear un componente
  • Patrón CVA
  • Estructura de archivos
• Storybook: convenciones de stories
• Fuente de verdad: Figma

Descripción

Este repositorio es la fuente de componentes UI reutilizables para los frontends de RegCheq (web-client, web-client-mx, web-client-proveedores). Los tokens de diseño (colores, tipografía, sombras) están sincronizados con el design system oficial en Figma y compilados en SCSS/CSS custom properties para que sean consumibles sin dependencias adicionales en los proyectos destino.

Stack:

| Herramienta | Versión | Rol | |---|---|---| | Vue | 2.6 | Framework de componentes | | Storybook | 7.6 | Documentación y sandbox | | Bootstrap Vue | 2.22 | Base de componentes estructurales | | SCSS | — | Estilos y design tokens | | CVA | latest | Gestión de variantes de componentes | | Inter | — | Fuente tipográfica del sistema |

Requisitos

• Node.js 18 (ver .nvmrc)
• npm o yarn

nvm use   # activa Node 18 según .nvmrc

Instalación

npm install
# o
yarn

Levantar Storybook

npm run storybook
# o
yarn storybook

Abre en http://localhost:6006

Para generar el build estático:

npm run build-storybook

Estructura del proyecto

regcheq-ui-vue-2/
├── .storybook/
│   ├── main.js          # Configuración de Storybook (webpack, addons, SCSS global)
│   ├── preview.js       # Setup global: Bootstrap Vue, tokens, fuente Inter
│   └── manager.js       # (opcional) Personalización UI de Storybook
│
└── src/
    ├── assets/
    │   └── scss/
    │       ├── _tokens.scss      # CSS custom properties (:root) — carga global
    │       └── _variables.scss   # Variables SCSS ($) — inyectadas en cada componente
    │
    ├── components/
    │   ├── atoms/                # Componentes base: Button, Input, Badge, Tag...
    │   │   └── [NombreComponente]/
    │   │       ├── NombreComponente.vue
    │   │       ├── NombreComponente.variants.js
    │   │       ├── NombreComponente.scss
    │   │       └── NombreComponente.stories.js
    │   │
    │   ├── molecules/            # Combinaciones de atoms: Card, FormField, Alert...
    │   │   └── [NombreComponente]/
    │   │       └── ...
    │   │
    │   └── organisms/            # Secciones completas: Navbar, Sidebar, DataTable...
    │       └── [NombreComponente]/
    │           └── ...
    │
    └── index.js                  # Entry point — exporta todos los componentes

Jerarquía Atomic Design

| Nivel | Carpeta | Ejemplos | Title en Storybook | |---|---|---|---| | Atoms | components/atoms/ | Button, Input, Badge, Icon | Atoms/RcqButton | | Molecules | components/molecules/ | Card, FormField, Alert, Tooltip | Molecules/RcqCard | | Organisms | components/organisms/ | Navbar, Sidebar, DataTable, Modal | Organisms/RcqNavbar |

Design Tokens

Todos los tokens están definidos en src/assets/scss/_tokens.scss. Se inyectan automáticamente en todos los archivos .scss de los componentes, por lo que no es necesario importarlos manualmente.

Están disponibles como CSS custom properties (para uso inline o en cualquier contexto CSS) y como variables SCSS (para uso dentro de <style lang="scss">).

Colores

El sistema de colores sigue la escala 50–900 de Material Design, nombrada con el prefijo rq-.

| Paleta | Variable base | Uso | |---|---|---| | Primary | $rq-primary / --rq-primary | Color de marca principal #040045 | | Secondary | $rq-secondary / --rq-secondary | Color de marca secundario #0064e0 | | Info | $rq-info-{n} | Estados informativos | | Success | $rq-success-{n} | Estados de éxito | | Warning | $rq-warning-{n} | Estados de advertencia | | Red | $rq-red-{n} | Estados de error / alerta | | Tag | $rq-tag-{n} | Etiquetas, badges (fucsia) | | Gray | $rq-gray-{n} | Neutros, textos, bordes | | White | $rq-white-{n} | Fondos y superficies |

Uso:

// SCSS variable
background: $rq-primary;
color: $rq-gray-700;
border-color: $rq-secondary-300;

// CSS custom property
background: var(--rq-primary);
color: var(--rq-gray-700);

Tipografía

La fuente del sistema es Inter, cargada desde Google Fonts y aplicada globalmente a todos los componentes.

// SCSS
font-family: $rq-font-family;

// CSS custom property
font-family: var(--rq-font-family);

No es necesario declarar la fuente en los componentes — se hereda por defecto.

Elevaciones

5 niveles de sombra (L0–L4) para representar profundidad en el eje Z.

| Variable | Valor | Uso recomendado | |---|---|---| | $rq-elevation-0 | none | Flat. Cards y contenedores base | | $rq-elevation-1 | 0px 1px 1px | Widgets, Top Nav en hover | | $rq-elevation-2 | 0px 2px 2px | Cards en hover | | $rq-elevation-3 | 0px 4px 12px | Dropdowns, tooltips, menús | | $rq-elevation-4 | 0px 8px 24px | Modales, diálogos, notificaciones flotantes |

// SCSS
box-shadow: $rq-elevation-3;

// CSS custom property
box-shadow: var(--rq-elevation-3);

Crear un componente

Patrón CVA

Este proyecto usa CVA (Class Variance Authority) para gestionar variantes de componentes. CVA genera el string de clases CSS según las props recibidas, eliminando lógica condicional sucia dentro del template.

prop variant="primary"  →  CVA  →  "rcq-btn rcq-btn--primary rcq-btn--md"
                                          ↓
                                   SCSS define qué hace cada clase usando tokens

Estructura de archivos

Cada componente vive en su propio directorio con 4 archivos:

NombreComponente.variants.js

Define el mapeo entre props y clases CSS. Es la única fuente de verdad de las variantes.

import { cva } from 'class-variance-authority'

export const componenteVariants = cva('rcq-componente', {
  variants: {
    variant: {
      primary:   'rcq-componente--primary',
      secondary: 'rcq-componente--secondary',
    },
    size: {
      sm: 'rcq-componente--sm',
      md: 'rcq-componente--md',
      lg: 'rcq-componente--lg',
    },
  },
  defaultVariants: {
    variant: 'primary',
    size: 'md',
  },
})

NombreComponente.scss

Define los estilos de cada clase usando los tokens del sistema. Nunca usar valores hardcodeados.

.rcq-componente {
  font-family: $rq-font-family;

  &--primary {
    background: $rq-primary;
    color: #ffffff;
    &:hover:not(:disabled) { background: $rq-primary-400; }
  }

  &--sm { height: 32px; font-size: 12px; }
  &--md { height: 40px; font-size: 14px; }
  &--lg { height: 48px; font-size: 16px; }
}

NombreComponente.vue

El componente llama a CVA en un computed y aplica el resultado con :class. Sin lógica de clases en el template.

<template>
  <div :class="classes">
    <slot />
  </div>
</template>

<script>
import { componenteVariants } from './NombreComponente.variants'
import './NombreComponente.scss'

export default {
  name: 'NombreComponente',
  props: {
    variant: { type: String, default: 'primary' },
    size:    { type: String, default: 'md' },
  },
  computed: {
    classes() {
      return componenteVariants({ variant: this.variant, size: this.size })
    },
  },
}
</script>

NombreComponente.stories.js

Documenta el componente en Storybook con controles interactivos y todas las variantes.

import NombreComponente from './NombreComponente.vue'

export default {
  title: 'Atoms/NombreComponente',  // o Molecules/ u Organisms/ según corresponda
  component: NombreComponente,
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary'] },
    size:    { control: 'select', options: ['sm', 'md', 'lg'] },
  },
}

const Template = (args, { argTypes }) => ({
  components: { NombreComponente },
  props: Object.keys(argTypes),
  template: '<NombreComponente v-bind="$props"><slot>Contenido</slot></NombreComponente>',
})

export const Default = Template.bind({})
Default.args = { variant: 'primary', size: 'md' }

export const AllVariants = () => ({
  components: { NombreComponente },
  template: `
    <div style="display:flex; gap:12px;">
      <NombreComponente variant="primary">Primary</NombreComponente>
      <NombreComponente variant="secondary">Secondary</NombreComponente>
    </div>
  `,
})

Storybook: convenciones de stories

• Cada componente expone al menos 3 stories: Default, AllVariants y AllSizes
• Agregar story Disabled cuando el componente tenga estado deshabilitado
• Usar title: 'Atoms/NombreComponente', 'Molecules/...' u 'Organisms/...' según el nivel
• Los controles (argTypes) deben cubrir todas las props públicas

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