@tokens_variables_credix/tokenized-styles

Design tokens en CSS y SCSS para usar en Angular y otros proyectos.

Estructura del paquete (después de npm run build)

dist/
├── css/
│   ├── tokens.css              # Todas las variables (monolito)
│   └── components/             # Por componente, sin prefijos, scope para overrides
│       ├── avatars.css
│       ├── app-bars.css
│       ├── buttons-wip.css
│       └── ...
└── scss/
│   ├── variables.scss          # Punto de entrada SCSS (primitives + semantic + component)
│   ├── 1-primitives.scss
│   ├── 2-semantic.scss
│   ├── 3-component.scss
│   └── components/             # Por componente, variables sin prefijos
│       ├── _index.scss         # @use de todos los componentes
│       ├── _avatars.scss
│       └── ...

Uso local

npm run build

Actualizar desde Figma y regenerar todo

Cuando actualices los tokens desde Figma (reemplazando tokens.css, 1-primitives.*, 2-semantic.*, 3-component.* en la raíz del repo), regenera los archivos de dist/ con uno de estos métodos.

Opción 1: Comando manual (recomendado)

Después de pegar o exportar los archivos actualizados desde Figma:

npm run build

o, explícitamente:

npm run build:figma

Eso vuelve a generar:

• dist/css/tokens.css
• dist/css/components/*.css (valores resueltos, sin prefijos)
• dist/scss/variables.scss y dist/scss/components/_*.scss

Opción 2: Modo watch (regenerar al guardar)

Si sueles pegar los archivos en la carpeta del repo y quieres que se regenere solo al guardar:

npm run watch

El script observa tokens.css, 1-primitives.css, 1-primitives.scss, 2-semantic.css, 2-semantic.scss, 3-component.css, 3-component.scss y tokens.json. Al detectar cambios, ejecuta el build y actualiza todo dist/. Deja la terminal abierta mientras trabajas.

Resumen del flujo Figma → dist

1. Exportar/actualizar desde Figma los archivos de tokens en la raíz del repo.
2. Ejecutar npm run build (o tener npm run watch corriendo).
3. Publicar si aplica: npm publish.

Ejecutar el build automáticamente

Puedes hacer que el build se ejecute solo en estos casos:

A) Después de cada git pull o git merge

Instala el hook una vez:

npm run install-git-hooks

A partir de ahí, cada vez que alguien haga git pull (o se haga un merge), se ejecutará node build.js y se actualizará dist/ sin tener que acordarse de correr el build a mano.

B) Watch en segundo plano (al guardar archivos)

Si quieres que, al pegar o guardar los archivos desde Figma, se regenere todo sin tener la terminal abierta:

npm run watch:background

Se inicia el mismo watch que npm run watch pero en segundo plano. Así cualquier cambio en los archivos de tokens dispara el build automáticamente. Para dejarlo siempre activo, puedes ejecutar watch:background al abrir el proyecto o usar un gestor de procesos (por ejemplo PM2: pm2 start watch-figma.js --name tokens-watch).

Publicar el paquete y actualizarlo en npm

Publicar tras cambios (manual)

Cuando hayas actualizado los tokens (desde Figma o a mano) y quieras subir una nueva versión a npm:

npm run build
npm run release

release hace: build → sube la versión patch (ej. 1.0.0 → 1.0.1) → npm publish.

Para subir minor o major:

npm run release:minor   # 1.0.0 → 1.1.0
npm run release:major  # 1.0.0 → 2.0.0

Necesitas estar logueado en npm (npm login) o tener configurado el token.

Publicar automáticamente con GitHub Actions

Si el repo está en GitHub, puedes publicar en npm en cada push a main:

1. Crea un token de npm (Automation): npm → Access Tokens → Generate New Token → Automation.
2. En el repo de GitHub: Settings → Secrets and variables → Actions → New repository secret → nombre NPM_TOKEN, valor = el token.
3. Al hacer push a main (o al ejecutar manualmente el workflow "Publish to npm"), se ejecutará build, se subirá la versión patch y se publicará en npm. Opcionalmente se hace commit del nuevo package.json en el repo.

El workflow está en .github/workflows/publish-npm.yml. También puedes lanzarlo a mano desde la pestaña Actions → Publish to npm → Run workflow.

1. Ajustar nombre y registro

• Cambia @tokens_variables_credix en package.json por el scope de tu organización (ej: @mi-empresa).

• Si usas npm público: npm publish --access public (paquetes con scope son privados por defecto).

• Si usas GitHub Packages: crea .npmrc en el repo con:

  @tokens_variables_credix:registry=https://npm.pkg.github.com

  y en package.json añade:

  "repository": {
    "type": "git",
    "url": "https://github.com/tu-org/tu-repo.git"
  },
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }

2. Publicar

npm run build
npm publish

Consumir en un proyecto Angular

Instalación

npm install @tokens_variables_credix/tokenized-styles@latest --save

CSS global (angular.json)

En angular.json, en projects > tu-proyecto > architect > build > options > styles:

"styles": [
  "node_modules/@tokens_variables_credix/tokenized-styles/dist/css/tokens.css",
  "src/styles.css"
]

SCSS en componentes

En cualquier .scss:

@use '@tokens_variables_credix/tokenized-styles/dist/scss/variables' as *;

.mi-clase {
  color: $colors-rojo-primary-rojo-50;
}

O con namespace:

@use '@tokens_variables_credix/tokenized-styles/dist/scss/variables' as tokens;

.mi-clase {
  color: tokens.$colors-rojo-primary-rojo-50;
}

Versionado

Usa Semantic Versioning. En el proyecto que consume:

• ^1.0.0 → acepta 1.x.x
• ~1.0.0 → acepta 1.0.x

Actualizar tokens en el proyecto:

npm update @tokens_variables_credix/tokenized-styles

Uso por componente (lib-ui, global-theme, overrides)

Para componentes reutilizables y overrides limpios, usa los archivos por componente: sin prefijos y con scope .tokens-<nombre>.

Importar solo lo que necesitas

En angular.json (o en un SCSS global), en lugar del monolito puedes cargar solo los componentes que uses:

"styles": [
  "node_modules/@tokens_variables_credix/tokenized-styles/dist/css/tokens.css",
  "node_modules/@tokens_variables_credix/tokenized-styles/dist/css/components/avatars.css",
  "node_modules/@tokens_variables_credix/tokenized-styles/dist/css/components/buttons-wip.css",
  "src/styles.css"
]

O cargar todos los componentes (si usas el índice, créalo como CSS que importe cada uno, o lista los archivos).

Overrides con .global-theme

Cada componente expone variables sin prefijo dentro de .tokens-<componente>. Para sobreescribir desde tu tema global:

1. Asegura que tokens.css o los components/*.css estén cargados (para que existan las variables).
2. En tu contenedor de tema (ej. lib-ui o global-theme), aplica la clase que envuelve la app (ej. .global-theme).
3. Sobreescribe por componente:

/* En tu global-theme.scss o styles del shell */
.global-theme .tokens-avatars {
  --avatar-background: #e42313;
  --avatar-element: #fff;
}

.global-theme .tokens-buttons-wip {
  --button-enabled-button-container-color: #tu-color;
}

Así solo importas los CSS de componentes que usas y haces overrides por scope, sin tocar prefijos largos.

SCSS por componente (variables sin prefijo)

En un componente Angular o en lib-ui:

@use '@tokens_variables_credix/tokenized-styles/dist/scss/components/avatars' as *;

.avatar {
  background: $avatar-background;
  color: $avatar-element;
}

O el índice de todos los componentes:

@use '@tokens_variables_credix/tokenized-styles/dist/scss/components' as tokens;

.avatar {
  background: tokens.$avatar-background;
}