CBC UI

Biblioteca de estilos de CBC basada en Design Tokens, tokens semánticos, utilidades CSS y componentes reutilizables. Su objetivo es proporcionar una base visual consistente para el desarrollo de aplicaciones y sitios web de la organización.

Se distribuye como una única hoja de estilos compilada (dist/index.css). No incluye JavaScript, ni bindings de framework, ni lógica de componentes: es CSS puro.

Paquete: @corporacion-de-bienes-de-capital/cbc-ui · publicado públicamente en npm (uso restringido — ver Licencia y uso restringido).

Características

• Sistema de Design Tokens.
• Tokens semánticos para colores, superficies, acciones y capas.
• Utilidades CSS para layout y espaciado.
• Componentes reutilizables.
• Arquitectura modular basada en CSS.
• Playground para pruebas y desarrollo.

Instalación

El paquete se publica públicamente en npm, por lo que no requiere autenticación ni configuración de .npmrc para instalarlo:

npm install @corporacion-de-bienes-de-capital/cbc-ui

Aunque la instalación es abierta, el uso del paquete está sujeto a la licencia del proyecto — ver Licencia y uso restringido.

Licencia y uso restringido

Este paquete se distribuye bajo licencia UNLICENSED (todos los derechos reservados). Se publica en el registro público de npm únicamente por conveniencia técnica de distribución: cualquiera puede descargarlo, pero su uso, modificación o integración está reservado a proyectos de Corporación de Bienes de Capital y sus afiliados autorizados. Cualquier otro uso requiere autorización previa y expresa. Ver el archivo LICENSE para el texto completo.

Uso en proyectos

La librería expone una única hoja de estilos. Basta con importarla una vez en el punto de entrada de tu aplicación; a partir de ahí, todas las clases (cbc-*) y variables (--cbc-*) quedan disponibles globalmente.

Con un bundler (Vite, webpack, Next.js, etc.)

Desde un archivo CSS:

@import "@corporacion-de-bienes-de-capital/cbc-ui";

O desde el entry point JS/TS:

import "@corporacion-de-bienes-de-capital/cbc-ui";

Sin bundler (HTML plano)

Enlaza directamente el CSS compilado desde node_modules:

<link rel="stylesheet" href="node_modules/@corporacion-de-bienes-de-capital/cbc-ui/dist/index.css" />

Ejemplo de uso

Una vez importada la hoja de estilos, se combinan componentes y utilidades:

<button class="cbc-button cbc-button--primary">Guardar</button>

<div class="cbc-card cbc-p-4 cbc-mt-4">
  <p class="cbc-text-brand">Contenido de la tarjeta</p>
</div>

Los componentes disponibles son button, card, input, drawer y modal, además de las utilidades atómicas de layout, espaciado, colores, tipografía, bordes y sombras.

Estructura del proyecto

cbc-ui/
├── playground/
│   ├── buttons.html
│   ├── cards.html
│   ├── drawer.html
│   ├── inputs.html
│   ├── modal.html
│   └── playground.html
│
├── scripts/
│   └── generate-spacing.cjs
│
├── src/
│   ├── components/
│   ├── semantic/
│   ├── tokens/
│   ├── utilities/
│   └── index.css
│
├── dist/
│   └── index.css
│
├── package.json
├── postcss.config.js
└── README.md

Arquitectura

Tokens

Contienen los valores base del sistema de diseño.

Ejemplos:

• Colores
• Espaciados
• Tipografía
• Sombras
• Blur

Los componentes y la semántica utilizan estos valores como fuente de verdad.

Tokens semánticos

Representan la intención de uso de un token, desacoplando los componentes de valores específicos.

Ejemplos:

• Surface
• Text
• Border
• Action
• Z-index

Utilidades

Conjunto de clases reutilizables para acelerar la construcción de interfaces.

Incluyen utilidades para:

• Layout
• Display
• Flexbox
• Grid
• Posicionamiento
• Espaciados
• Tamaños
• Bordes
• Tipografía

Componentes

Los componentes encapsulan patrones visuales reutilizables construidos sobre los tokens y utilidades del sistema.

Actualmente la biblioteca incluye:

• Button
• Card
• Drawer
• Input
• Modal

Desarrollo local

Requiere Node.js. Instala las dependencias y usa los scripts disponibles:

npm install              # instalar dependencias de desarrollo
npm run build            # genera utilidades de espaciado y compila src/index.css -> dist/index.css
npm run generate:spacing # regenera src/utilities/spacing.css desde scripts/generate-spacing.cjs

La carpeta playground contiene ejemplos de uso de los componentes y sirve como entorno de pruebas. Los HTML enlazan ../src/index.css directamente, por lo que puedes iterar sobre el código fuente sin ejecutar el build.

src/utilities/spacing.css se genera automáticamente: no lo edites a mano; modifica scripts/generate-spacing.cjs y ejecuta npm run generate:spacing.

Publicación (mantenedores)

El paquete se publica en el registro público de npm. publishConfig.access: "public" en package.json ya indica que el paquete (con scope) debe publicarse como público, sin flags adicionales.

Prerequisito (una sola vez): el scope @corporacion-de-bienes-de-capital debe existir en npmjs.com. Crea una organización npm gratuita con ese nombre (permite paquetes públicos sin costo) o confirma que ya existe y que tu cuenta tiene permiso de publicación.

1. Autenticarse con tu cuenta personal de npm:

   npm login

2. Versionar siguiendo SemVer:

   npm version patch   # o minor / major

3. Publicar:

   npm publish

   El script prepublishOnly compila automáticamente dist/index.css antes de cada publicación, evitando subir un artefacto desactualizado.

El campo repository de package.json vincula el paquete publicado con este repositorio en GitHub. Mantenlo actualizado si el repositorio cambia de nombre u organización.

Principios del proyecto

• Utilizar Design Tokens como única fuente de valores.
• Preferir tokens semánticos dentro de los componentes.
• Mantener una arquitectura modular y escalable.
• Incorporar nuevos componentes únicamente cuando exista evidencia de reutilización dentro del producto.
• Evitar duplicación de estilos.

Estado

Versión 1.0.0

Esta versión establece la base del sistema de diseño e incluye los componentes y utilidades fundamentales para el desarrollo de interfaces dentro de CBC.