@codenhub/styles 0.6.0 → 0.8.0

package/docs/es/integrating/index.md

@@ -0,0 +1,75 @@
+---
+title: Visión general
+description: Cómo se carga la hoja de estilos en el build de un framework, y qué guía seguir.
+group: Integración
+order: 2
+source: 2028acef66a8ab3659cef35e08ecc0db1de7bdeb
+---
+
+# Integración
+
+Esta sección es un desvío del orden de lectura principal, para proyectos cuyo framework decide dónde puede ir el CSS global. El paquete no tiene JavaScript ni bindings para frameworks (consulta [Introducción](../index.md#lo-que-no-hace)), así que integrarlo se reduce a dos cosas: dónde te deja tu framework cargar una hoja de estilos global, y si el proyecto usa Tailwind CSS v4. Sigue la guía que corresponde a tu stack y después vuelve a [Construir una pantalla](../concepts.md).
+
+## El modelo común
+
+Todos los stacks hacen los mismos dos imports, desde el mismo tipo de lugar: un layout raíz, un archivo de entrada de la aplicación o un archivo CSS global, nunca una página o un componente más abajo en el árbol:
+
+1. Un [punto de entrada](../setup.md#todos-los-puntos-de-entrada): el compilado `@codenhub/styles` para cualquier build, o `@codenhub/styles/tw` cuando el proyecto ya usa Tailwind CSS v4.
+2. `@codenhub/styles/aesthetics` (o `/tw/aesthetics`) después, solo si el proyecto usa una [estética](../usage/aesthetics.md).
+
+Importar desde un solo lugar importa por dos motivos. Algunos frameworks solo _permiten_ CSS global desde un archivo raíz designado y, si no, el build falla; el Pages Router de Next.js es uno de ellos, consulta [Next.js → Solución de problemas](./nextjs.md#solución-de-problemas). Donde un framework lo permite de forma más amplia, como hace el App Router de Next.js, importar desde la raíz sigue siendo la opción recomendada para que el orden del CSS sea predecible; además, importar en cada componente cargaría las mismas reglas de reset y de tokens una vez por componente en lugar de una vez por aplicación.
+
+## Qué guía seguir
+
+| Stack                                                                                           | Guía                                  |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------- |
+| Un proyecto con Tailwind CSS v4 en cualquier bundler                                            | [Tailwind CSS v4](./tailwind.md)      |
+| Next.js / React                                                                                 | [Next.js](./nextjs.md)                |
+| Vue                                                                                             | [Vue](./vue.md)                       |
+| Svelte / SvelteKit                                                                              | [Svelte](./svelte.md)                 |
+| Astro                                                                                           | [Astro](./astro.md)                   |
+| HTML simple, Rails, Laravel, Django o cualquier aplicación sin paso de build de CSS con Node.js | [Sin bundler](./without-a-bundler.md) |
+
+Un proyecto sin framework, un build simple con Vite, webpack o Parcel, importa la hoja de estilos compilada desde la entrada CSS global que el proyecto ya tiene, como muestra [Configuración inicial → Importar la hoja de estilos](../setup.md#importar-la-hoja-de-estilos). Vite y webpack resuelven el nombre del paquete tal cual; Parcel y PostCSS con `postcss-import` necesitan el cambio de abajo. La hoja de estilos compilada contiene todas las clases; para incluir solo las que usan tus páginas sin adoptar Tailwind, escribe una hoja de estilos reducida con el [comando `build`](./without-a-bundler.md#generar-solo-las-clases-que-usas) del paquete e impórtala en su lugar.
+
+### Bundlers que necesitan un empujón
+
+Ambas herramientas encuentran la hoja de estilos en cuanto se les dice cómo; ninguna necesita otro punto de entrada.
+
+**Parcel.** Activa su soporte del mapa `exports` de un paquete en tu `package.json`:
+
+```json
+{
+  "@parcel/resolver-default": {
+    "packageExports": true
+  }
+}
+```
+
+Luego importa el paquete con el prefijo `npm:` de Parcel, que le indica que el nombre es un paquete y no un archivo junto a la hoja de estilos:
+
+```css
+@import "npm:@codenhub/styles";
+```
+
+**PostCSS con `postcss-import`.** El plugin no lee el mapa `exports` de un paquete, así que el nombre del paquete por sí solo no se resuelve. Importa en su lugar el archivo compilado por su ruta en disco, relativa a tu propia hoja de estilos, el mismo archivo que nombraría un `<link>`:
+
+```css
+@import "../node_modules/@codenhub/styles/dist/index.css";
+```
+
+Los demás puntos de entrada compilados funcionan igual, como `@codenhub/styles/dist/aesthetics/neobrutalism.css`.
+
+## Comprobar que funciona
+
+Después del import, renderiza un elemento con estilo y confirma que ha tomado los tokens del paquete y no los valores por defecto del navegador:
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+Un botón redondeado relleno con el color principal (casi negro en una página clara, casi blanco en una oscura) significa que la hoja de estilos se ha cargado. Un texto sin estilo, con los valores por defecto del navegador, casi siempre significa que el especificador del import no se ha resuelto: consulta en la [tabla de puntos de entrada](../setup.md#todos-los-puntos-de-entrada) el especificador exacto que debes importar, y confirma que tus herramientas de build resuelven imports de CSS de paquetes; consulta [Configuración inicial → Requisitos](../setup.md#requisitos). Sin herramienta de build, enlaza el archivo por su ruta; consulta [Sin bundler](./without-a-bundler.md). [Configuración inicial → Cuando nada tiene estilo](../setup.md#cuando-nada-tiene-estilo) enumera las otras causas habituales.
+
+## Siguiente paso
+
+Cuando el botón se renderice, vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes.

package/docs/es/integrating/nextjs.md

@@ -0,0 +1,67 @@
+---
+title: Next.js
+description: Cargar la hoja de estilos en una aplicación Next.js / React.
+order: 2
+source: fd8dc12652c64995638c5b902a1ca35787f9a37c
+---
+
+# Next.js
+
+Next.js tiene dos arquitecturas de router, y tratan el CSS global de forma distinta:
+
+- **App Router** (un directorio `app/`): el CSS global, incluida la hoja de estilos de un paquete externo como este, se puede importar desde cualquier layout, página o componente dentro de `app/`. Importarlo desde el layout raíz es solo una recomendación, para que el orden del CSS sea predecible entre rutas; Next.js no lo impone y no se produce ningún error si lo importas en otro sitio.
+- **Pages Router** (un directorio `pages/`, sin `app/`): el CSS global está restringido a `pages/_app.tsx`. Importarlo desde cualquier otro sitio hace fallar el build; lo impone el propio Next.js, no este paquete; consulta [Solución de problemas](#solución-de-problemas).
+- **Ambos directorios presentes** (a mitad de una migración): importa la hoja de estilos en los dos archivos raíz. Los dos routers sirven sus propias rutas de forma independiente, así que una ruta dentro de `pages/` nunca ve una hoja de estilos importada solo en `app/layout.tsx`, y viceversa.
+
+## Importar la hoja de estilos
+
+Añade el import al archivo raíz de tu router:
+
+**App Router**
+
+```tsx
+// app/layout.tsx
+import "@codenhub/styles";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Pages Router**
+
+```tsx
+// pages/_app.tsx
+import "@codenhub/styles";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+¿Usas Tailwind CSS v4? `@import "@codenhub/styles/tw"` es una directiva de CSS, así que va en un archivo CSS, no como import suelto en `layout.tsx`/`_app.tsx`: añádelo (con `@source` si hace falta; `/tw` ya importa Tailwind, así que no pongas tu propio `@import "tailwindcss"`) a tu archivo CSS global, e importa ese archivo desde el mismo archivo raíz de arriba. Consulta [Tailwind CSS v4](./tailwind.md).
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en `<html>` para forzar un tema en lugar de seguir la preferencia del sistema; consulta [Temas → Claro y oscuro](../usage/theming.md#claro-y-oscuro).
+
+```tsx
+<html lang="en" className="dark">
+```
+
+## Solución de problemas
+
+**El build con Pages Router falla con "Global CSS cannot be imported from files other than your Custom `<App>`"**
+
+- **Qué ha pasado:** Next.js ha rechazado una sentencia `import` de CSS global fuera de `pages/_app.tsx`. Esta restricción es propia del Pages Router: la impone el propio Next.js, no este paquete, y se aplica a cualquier import de CSS global, no solo a `@codenhub/styles`. No se aplica al App Router, donde el mismo import funciona desde cualquier layout, página o componente.
+- **Por qué:** el Pages Router no tiene un límite de CSS por ruta como el App Router, así que Next.js exige un único archivo predecible para las hojas de estilos globales y así evitar conflictos de orden entre páginas.
+- **Solución:** mueve la línea `import "@codenhub/styles"` a `pages/_app.tsx` y quítala de donde esté ahora.
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) enumera todas las demás hojas de estilos que puedes importar.

package/docs/es/integrating/svelte.md

@@ -0,0 +1,45 @@
+---
+title: Svelte
+description: Cargar la hoja de estilos en una aplicación Svelte / SvelteKit.
+order: 4
+source: 9c8bc0fee69e4b2bf1edd85c784b7df8ff1e883d
+---
+
+# Svelte
+
+Svelte y SvelteKit te permiten importar CSS desde cualquier componente, pero el reset y los tokens del paquete deberían cargarse una vez, antes de que se renderice cualquier componente. Esta página muestra dónde va ese único import en SvelteKit y en una aplicación Svelte simple.
+
+## Importar la hoja de estilos
+
+**SvelteKit**: importa desde el layout raíz para que se cargue una vez para todas las rutas:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import "@codenhub/styles";
+  let { children } = $props();
+</script>
+
+{@render children()}
+```
+
+**Svelte simple + Vite**: importa en su lugar desde el archivo de entrada:
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+mount(App, { target: document.getElementById("app")! });
+```
+
+¿Usas Tailwind CSS v4? Importa en su lugar `@codenhub/styles/tw` desde la entrada CSS de la aplicación; consulta [Tailwind CSS v4](./tailwind.md).
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en `<html>` (edita `src/app.html` en SvelteKit) para forzar un tema en lugar de seguir la preferencia del sistema; consulta [Temas → Claro y oscuro](../usage/theming.md#claro-y-oscuro).
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) enumera todas las demás hojas de estilos que puedes importar.

package/docs/es/integrating/tailwind.md

@@ -0,0 +1,148 @@
+---
+title: Tailwind CSS v4
+description: Usar los puntos de entrada de código fuente /tw en un proyecto con Tailwind CSS v4.
+order: 1
+source: a86fe5fa121db14ab917b10fb69e839111ddbc47
+---
+
+# Tailwind CSS v4
+
+Un proyecto que ya usa Tailwind CSS v4 puede compilar el código fuente de este paquete en lugar de cargar su salida compilada. Así, las utilidades de tu aplicación y las clases del paquete salen de un solo build, comparten un tema y usan una sola variante `dark:`. Esta página cubre el import, las estéticas, los puntos de entrada específicos, cómo construir tus propios componentes con `@apply`, cómo prescindir de la paleta de Tailwind y los problemas de build con los que probablemente te encuentres.
+
+## Por qué código fuente en lugar de compilado
+
+Los puntos de entrada `/tw` publican código fuente copiado y sin compilar desde la carpeta `tw/` del paquete; tu propio build de Tailwind lo compila junto con tu aplicación, así que sus directivas `@theme`, `@utility` y `@apply` se resuelven junto con las tuyas. Los puntos de entrada compilados (`@codenhub/styles`) siguen funcionando en un proyecto con Tailwind, pero entonces se ejecutan dos pipelines de CSS separados en paralelo en lugar de uno: usa `/tw` salvo que un motivo concreto lo descarte.
+
+## Importar el punto de entrada de código fuente
+
+```css
+@import "@codenhub/styles/tw";
+
+@source "./src";
+```
+
+`/tw` importa el propio Tailwind, así que sustituye a tu `@import "tailwindcss"` en lugar de sumarse a él: con los dos, el Preflight de Tailwind se emite dos veces. Todos los demás puntos de entrada `/tw/*` esperan que tu import vaya primero; consulta [Usar un punto de entrada específico](#usar-un-punto-de-entrada-específico).
+
+Tailwind CSS v4 escanea tu proyecto automáticamente: la mayoría de los proyectos no necesita nada más que el import anterior. Las rutas de `@source` se resuelven respecto al archivo CSS que las declara, no respecto a la raíz de tu proyecto, así que aquí `./src` significa "el `src/` que está junto a esta hoja de estilos"; ajústalo según dónde esté realmente tu hoja de estilos global. Añade `@source` solo para el markup al que el escaneo automático de Tailwind no llega por sí solo: una ruta excluida por defecto (incluida en `.gitignore`, o dentro de `node_modules`, por ejemplo una librería de componentes externa) o, en un monorepo, una que está fuera del árbol de directorios de este archivo. Apúntalo al markup de tu aplicación, no a este paquete: el código fuente del paquete nombra cada clase que define, así que escanearlo las emite todas, las usen tus páginas o no.
+
+## Añadir estéticas
+
+Añade una estética desde el punto de entrada de código fuente igual que con el compilado, después del import base:
+
+```css
+@import "@codenhub/styles/tw";
+@import "@codenhub/styles/tw/aesthetics";
+
+@source "./src";
+```
+
+## Usar un punto de entrada específico
+
+Importa un punto de entrada `/tw/*` específico en lugar del combinado, como `/tw/button` o `/tw/form`, cuando un build solo necesita una familia de componentes; consulta la [tabla de puntos de entrada](../setup.md#todos-los-puntos-de-entrada) completa para ver qué compone cada uno.
+
+A diferencia de `/tw`, los puntos de entrada específicos y `/tw/native` no importan Tailwind, así que mantén tu propio import primero:
+
+```css
+@import "tailwindcss";
+@import "@codenhub/styles/tw/button";
+```
+
+## Construir tus propios componentes con `@apply`
+
+En `/tw`, cada componente, helper y clase de eje es una utilidad de Tailwind. Eso incluye las intenciones (`neutral`, `primary`, `secondary`, `success`, `warning`, `destructive`, `info`), la presentación (`solid`, `soft`, `ghost`, `edged`, `edgeless`), la elevación (`flat`, `raised`, `floating`), los patrones de esquina (`cut-diagonal`, `cut-diagonal-reverse`) y los tamaños (`sm`, `lg`). Así, una clase tuya puede llevar una receta completa:
+
+```css
+@import "@codenhub/styles/tw";
+
+@utility btn-save {
+  @apply btn primary soft sm;
+}
+
+@utility btn-danger {
+  @apply btn destructive md:lg dark:solid;
+}
+```
+
+```html
+<button class="btn-save" type="submit">Guardar</button>
+```
+
+- **Un componente aplicado se comporta como la clase.** `btn-save` reacciona al hover, se presiona, recibe el foco y sigue a una estética igual que `class="btn primary soft sm"`.
+- **Las variantes funcionan.** `hover:primary`, `md:lg` y `dark:solid` aplican una clase de eje bajo esa condición, en tu marcado o dentro de `@apply`.
+- **Escribe tu clase como `@utility`.** Así se queda en la capa `utilities`, y tus demás utilidades en el mismo elemento le siguen ganando. Una regla simple `.btn-save { @apply … }` también funciona, pero queda sin capa, así que lo que aplica gana a todas las utilidades del elemento; [Personalización → Helpers de composición](../usage/customizing.md#helpers-de-composición) tiene los detalles.
+- **Los modificadores también se aplican.** Los modificadores de un componente, como `.tight` en `.stack`, `.icon` en `.btn` o `.interactive` en `.card`, también son utilidades, así que `@apply stack tight`, `@apply btn icon pill` y `md:tight` funcionan. El estado deshabilitado es la excepción: sigue siendo un atributo o la clase `.disabled` en el marcado.
+- **Tu utilidad gana a los valores internos de un componente.** `p-0 text-center` en una celda de `.data-table`, `text-sm` en un `.label` y `px-8` en un `.btn.sm` se aplican todos.
+
+[Preajustes](../usage/presets.md) compara esto con las demás formas de definir un aspecto una sola vez.
+
+## Prescindir de la paleta de Tailwind
+
+`/tw` se construye sobre el tema por defecto de Tailwind, así que las utilidades de su paleta, como `bg-red-500`, siguen disponibles. Si tu diseño usa solo los tokens del paquete, borra los tonos que no usas:
+
+```css
+@import "@codenhub/styles/tw";
+
+@theme {
+  --color-red-*: initial;
+  --color-orange-*: initial;
+  --color-yellow-*: initial;
+  --color-lime-*: initial;
+  --color-green-*: initial;
+  --color-teal-*: initial;
+  --color-cyan-*: initial;
+  --color-sky-*: initial;
+  --color-blue-*: initial;
+  --color-violet-*: initial;
+  --color-purple-*: initial;
+  --color-fuchsia-*: initial;
+  --color-pink-*: initial;
+  --color-slate-*: initial;
+  --color-gray-*: initial;
+  --color-zinc-*: initial;
+  --color-stone-*: initial;
+  --color-black: initial;
+}
+```
+
+Los colores propios del paquete no cambian, y puedes seguir añadiendo colores tuyos en el mismo bloque.
+
+El bloque deja fuera `neutral`, `emerald`, `amber`, `rose`, `indigo` y `white` a propósito: el tema construye sus colores a partir de ellos.
+
+- **No borres todo el espacio de nombres.** `--color-*: initial` quita también los colores semánticos del paquete, y el build se detiene con un error como `Cannot apply unknown utility class`.
+- **No borres una escala que lee el tema.** Borrar `--color-emerald-*` compila sin error, pero los colores de éxito construidos con ella se pierden.
+
+## Solución de problemas
+
+**Las clases no producen ningún estilo**
+
+- **Qué ha pasado:** los componentes usan clases documentadas como `.btn.primary`, pero no aparece ningún estilo aunque `@import "@codenhub/styles/tw"` está en la hoja de estilos.
+- **Por qué:** rara vez es por el propio `@source`, porque Tailwind ya escanea tu proyecto automáticamente. La causa más habitual es un markup que vive en un lugar que el escaneo automático excluye por defecto: una ruta incluida en `.gitignore`, o un componente que viene de `node_modules`. Puede que Tailwind no vea una clase usada solo ahí y no genere una regla para ella.
+- **Solución:** añade un `@source` explícito que apunte a ese directorio, resuelto respecto a esta hoja de estilos, como en el [ejemplo de arriba](#importar-el-punto-de-entrada-de-código-fuente).
+
+**Reglas de tokens y de reset duplicadas**
+
+- **Qué ha pasado:** la hoja de estilos generada es más grande de lo esperado, y las herramientas de desarrollo del navegador muestran las mismas custom properties o reglas de reset definidas dos veces.
+- **Por qué:** una de dos cosas. Importar en el mismo build un punto de entrada compilado (`@codenhub/styles`) y un punto de entrada `/tw` (`@codenhub/styles/tw`) compila los mismos tokens y el mismo reset desde dos fuentes independientes; el build de Tailwind no tiene forma de saber que describen el mismo paquete. O bien tu hoja de estilos importa `tailwindcss` junto a `/tw`, que ya lo importa, así que el Preflight se emite dos veces.
+- **Solución:** elige un camino por proyecto, los puntos de entrada `/tw` para un proyecto con Tailwind CSS v4 y los compilados en todos los demás casos, y quita tu propio `@import "tailwindcss"` cuando importes `/tw`.
+
+**Una clase construida en tiempo de ejecución no tiene estilo**
+
+- **Qué ha pasado:** `<button class="btn primary">` tiene estilo, pero un botón cuya clase viene de una variable, como `"btn " + variant`, o de contenido de un CMS, no.
+- **Por qué:** Tailwind emite solo las clases que encuentra escritas completas en los archivos que escanea. Eso vale también para las clases de componente del paquete: un build con `/tw` emite `.alert` solo si `alert` aparece en algún lugar que escanea, lo que limita la hoja de estilos a lo que usan tus páginas. Las clases de intención, de presentación, de elevación, de esquina y de tamaño, como `.primary`, `.soft` y `.sm`, también son utilidades, así que les pasa lo mismo. Las clases de estética, como `.glass`, son CSS plano y se emiten siempre. Un nombre armado en tiempo de ejecución nunca aparece completo en un archivo, así que el escaneo no lo ve.
+- **Solución:** escribe cada nombre de clase completo en algún lugar que Tailwind escanee, por ejemplo en un objeto de consulta (`{ save: "btn primary", remove: "btn destructive" }`), o enumera en tu hoja de estilos los nombres que tu código o tu contenido pueden producir:
+
+```css
+@import "@codenhub/styles/tw";
+
+@source inline("btn alert badge primary destructive soft");
+```
+
+Todos los puntos de entrada `/tw` requieren Tailwind CSS 4.3.2 o posterior, por debajo de 5 (`>=4.3.2 <5`).
+
+## La variante `dark:`
+
+Los puntos de entrada `/tw` definen su propia variante `dark:`, así que tus utilidades cambian con los mismos selectores claro y oscuro que usan los tokens del paquete. Tiene una diferencia conocida respecto a los tokens cuando los temas están anidados; consulta [Temas → La variante dark:](../usage/theming.md#la-variante-dark).
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. Todo lo que muestra funciona igual con `/tw`.

package/docs/es/integrating/vue.md

@@ -0,0 +1,31 @@
+---
+title: Vue
+description: Cargar la hoja de estilos en una aplicación Vue / Vite.
+order: 3
+source: 9cc23f66518b0aa3ce886602f39d05820b2b8bcf
+---
+
+# Vue
+
+Vue no pone ninguna restricción sobre desde dónde se importa el CSS, pero importarlo una vez, desde el archivo de entrada de la aplicación, evita que el reset y los tokens se carguen más de una vez y garantiza que estén listos antes de que se renderice cualquier componente.
+
+## Importar la hoja de estilos
+
+```ts
+// main.ts
+import "@codenhub/styles";
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");
+```
+
+¿Usas Tailwind CSS v4? Importa `@codenhub/styles/tw` desde un archivo CSS de entrada en lugar de `main.ts`, con el plugin `@tailwindcss/vite`; consulta [Tailwind CSS v4](./tailwind.md).
+
+## Forzar un tema
+
+Aplica `.dark` o `.light` en el elemento raíz para forzar un tema en lugar de seguir la preferencia del sistema; consulta [Temas → Claro y oscuro](../usage/theming.md#claro-y-oscuro).
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) enumera todas las demás hojas de estilos que puedes importar.

package/docs/es/integrating/without-a-bundler.md

@@ -0,0 +1,238 @@
+---
+title: Sin bundler
+description: Enlazar las hojas de estilos compiladas desde HTML simple, Rails, Laravel, Django o cualquier aplicación renderizada en el servidor, y el build por línea de comandos.
+order: 6
+source: 6289ea781c99dcda5c027a72fede9e2f1cab8414
+---
+
+# Sin bundler
+
+Las hojas de estilos compiladas son CSS terminado: cada una es un único archivo sin `@import` ni referencias a otro archivo, y cada imagen que dibuja va incrustada como URL `data:`: las máscaras del tick y del guion del checkbox, y los filtros de lente SVG que usa `.glass-liquid`. Una página puede cargar una con una simple etiqueta `<link>`, desde cualquier servidor, sin paso de build, y la hoja de estilos no hace más peticiones.
+
+Lo que necesita una herramienta de build es el _nombre_ del import. `@import "@codenhub/styles"` nombra un paquete, y encontrar el archivo que hay detrás de ese nombre, `node_modules/@codenhub/styles/dist/index.css`, lo hacen herramientas que conocen Node, como Vite, webpack o la CLI de Tailwind, que leen el mapa `exports` del paquete. Un navegador no: resuelve la URL de un `@import` respecto a la hoja de estilos que lo contiene y un `<link href>` respecto a la página, así que un nombre de paquete sin más se convierte en una petición a una ruta que no existe. Sin bundler, enlaza el archivo por su ruta.
+
+Los puntos de entrada `/tw` son código fuente de Tailwind y necesitan un build de Tailwind. `/tw/aesthetics` es la excepción, CSS simple sin nada que Tailwind tenga que procesar, pero sin bundler enlaza en su lugar los archivos compilados de `dist/aesthetics/`, como se muestra abajo. Esta página es para una página que no tiene un build de CSS con Node.js: HTML simple, Rails, Laravel, Django o cualquier aplicación renderizada en el servidor. Hay dos caminos:
+
+1. **Enlazar la hoja de estilos compilada.** Funciona hoy, solo con archivos estáticos. Envías todas las clases, las usen tus páginas o no.
+2. **Generar una hoja de estilos con el comando `build` del paquete.** Escanea tus plantillas y escribe una hoja de estilos con solo las clases que usan. Consulta [Generar solo las clases que usas](#generar-solo-las-clases-que-usas).
+
+## Qué archivo enlazar
+
+Cada ruta de import compilada es un archivo en la carpeta `dist/` del paquete:
+
+| Ruta de import                  | Archivo                                                        |
+| ------------------------------- | -------------------------------------------------------------- |
+| `@codenhub/styles`              | `dist/index.css`                                               |
+| `@codenhub/styles/theme`        | `dist/theme.css`                                               |
+| `@codenhub/styles/components`   | `dist/components.css`                                          |
+| `@codenhub/styles/native`       | `dist/native.css`                                              |
+| `@codenhub/styles/palette`      | `dist/palette.css`                                             |
+| `@codenhub/styles/aesthetics`   | `dist/aesthetics/index.css`                                    |
+| `@codenhub/styles/aesthetics/*` | `dist/aesthetics/<name>.css`, como `dist/aesthetics/pixel.css` |
+
+Enlaza un solo archivo base, no varios, porque se solapan, y las estéticas que uses. Su orden no importa, porque cada archivo declara las [capas de cascada](../setup.md#capas-de-cascada) antes de usar alguna. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) explica qué contiene cada uno.
+
+## Desde un CDN
+
+jsDelivr y unpkg sirven todos los archivos de cada versión publicada en npm, así que una página puede enlazar uno sin instalar nada:
+
+```html
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.8.0/dist/index.css" />
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@codenhub/styles@0.8.0/dist/aesthetics/pixel.css" />
+</head>
+```
+
+Pon la versión exacta en la URL. Sin ella, el CDN sirve la última versión, y por debajo de 1.0 una versión menor puede renombrar o eliminar una clase; consulta [Versionado](../index.md#versionado).
+
+## Desde tu propio servidor
+
+Instala el paquete y después sirve su carpeta `dist/` como archivos estáticos:
+
+```sh
+npm install @codenhub/styles
+```
+
+Cada framework sirve de forma distinta una carpeta de `node_modules`, así que abajo está cada uno. Donde el framework lee la carpeta en su sitio, como hacen Rails y Django, actualizar el paquete y volver a desplegar es todo lo que hace falta para una actualización.
+
+### HTML simple
+
+Copia `node_modules/@codenhub/styles/dist` en la carpeta que publica tu servidor y después enlázala:
+
+```html
+<link rel="stylesheet" href="/vendor/codenhub-styles/index.css" />
+```
+
+Repite la copia después de cada actualización, por ejemplo desde un script `postinstall` de npm.
+
+### Ruby on Rails
+
+Una aplicación Rails construida con `cssbundling-rails` ya usa un bundler: importa el paquete desde `app/assets/stylesheets/application.css` como en [Configuración inicial → Importar la hoja de estilos](../setup.md#importar-la-hoja-de-estilos).
+
+Con Propshaft y sin bundler de CSS, añade la carpeta del paquete a las rutas de assets:
+
+```ruby
+# config/initializers/assets.rb
+Rails.application.config.assets.paths << Rails.root.join("node_modules/@codenhub")
+```
+
+Después enlázala desde el layout, por su ruta dentro de esa carpeta:
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<%= stylesheet_link_tag "styles/dist/index" %>
+<%= stylesheet_link_tag "styles/dist/aesthetics/pixel" %>
+```
+
+Apunta la ruta a `node_modules/@codenhub` y no directamente a `dist/`. Propshaft sirve los archivos por su ruta dentro de cada carpeta de assets, así que añadir `dist/` directamente publicaría un `index.css` suelto que choca con cualquier `index.css` tuyo.
+
+Los archivos que enlazas están en `dist/`, que contiene solo CSS terminado, más un `index.d.ts` vacío para TypeScript. El código fuente de Tailwind vive en `tw/`, fuera de `dist/`, así que un pipeline estático que sirve `dist/` o le añade huellas no encuentra ningún `@import` que no pueda resolver.
+
+### Django
+
+Añade la carpeta a `STATICFILES_DIRS` con un prefijo, que mantiene sus nombres de archivo separados de tus propios archivos estáticos:
+
+```python
+# settings.py
+STATICFILES_DIRS = [
+    ("codenhub-styles", BASE_DIR / "node_modules/@codenhub/styles/dist"),
+]
+```
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'codenhub-styles/index.css' %}" />
+```
+
+Apunta el prefijo a `dist`, no a la carpeta del paquete. `dist/` contiene solo CSS terminado, más un `index.d.ts` vacío para TypeScript que el almacenamiento copia tal cual, así que `collectstatic` también funciona con `ManifestStaticFilesStorage`, que añade una huella a cada archivo y reescribe las referencias que contiene. La carpeta del paquete también contiene el código fuente de Tailwind en `tw/`, cuyas líneas `@import "tailwindcss/..."` ese almacenamiento no puede resolver.
+
+### Laravel
+
+Una aplicación Laravel usa Vite por defecto, así que tiene un bundler: importa el paquete desde `resources/css/app.css` como en [Configuración inicial → Importar la hoja de estilos](../setup.md#importar-la-hoja-de-estilos), y carga ese archivo con la directiva `@vite` como de costumbre.
+
+## Generar solo las clases que usas
+
+El paquete trae un comando, `codenhub-styles`, que lo compila por ti. Lee tus plantillas en busca de nombres de clase y escribe una sola hoja de estilos minificada con solo las clases de StyleKit y las utilidades de Tailwind que usan. Una página que usa un botón recibe una pequeña fracción de la hoja de estilos completa; el tamaño exacto depende de las clases que uses, porque cada componente trae las reglas compartidas de las que depende.
+
+El comando también sirve con un bundler. Un proyecto cuyo bundler no ejecuta Tailwind, como un build simple con Vite o webpack, puede escribir la hoja de estilos entre sus fuentes, `--output src/stylekit.css`, e importar ese archivo donde importaría `@codenhub/styles`. Un proyecto que usa Tailwind CSS v4 obtiene la misma reducción con el [punto de entrada de código fuente](./tailwind.md) y no necesita el comando.
+
+Necesita Node.js 24 o posterior en la máquina que genera el CSS, sea tu portátil, un job de CI o un paso del despliegue. Compila con Tailwind CSS, que el paquete no instala por ti, así que un proyecto que solo enlaza la hoja de estilos compilada nunca lo descarga. Instala los tres paquetes como dependencias de desarrollo desde la raíz de tu proyecto; npm crea un `package.json` si no tienes uno, y no necesitas configuración de Tailwind:
+
+```sh
+npm install --save-dev @codenhub/styles @tailwindcss/cli tailwindcss
+```
+
+La hoja de estilos que escribe el comando es CSS simple, así que los servidores que sirven tu sitio no necesitan ni Node.js ni ninguno de estos paquetes. Ejecútalo desde la raíz de tu proyecto:
+
+```sh
+npx codenhub-styles build --content "app/views/**/*.erb" --output public/stylekit.css
+```
+
+Si todo va bien, el comando imprime una línea: la ruta absoluta que escribió y el tamaño del archivo en bytes:
+
+```text
+/home/you/shop/public/stylekit.css 25782 bytes
+```
+
+Enlaza ese archivo desde tu layout como cualquier hoja de estilos estática.
+
+### Vistas de Rails
+
+```sh
+npx codenhub-styles build --content "app/views/**/*.erb" --content "app/helpers/**/*.rb" --output public/stylekit.css
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<link rel="stylesheet" href="/stylekit.css" />
+```
+
+### Vistas Blade de Laravel
+
+```sh
+npx codenhub-styles build --content "resources/views/**/*.blade.php" --output public/css/stylekit.css
+```
+
+```blade
+{{-- resources/views/layouts/app.blade.php --}}
+<link rel="stylesheet" href="{{ asset('css/stylekit.css') }}" />
+```
+
+### Plantillas de Django
+
+Un proyecto Django guarda las plantillas en una carpeta `templates/` del proyecto, en la carpeta `templates/` de cada app, o en ambas. Pasa un `--content` por cada lugar donde estén las tuyas, y deja fuera los que no uses, porque un glob que no coincide con nada hace fallar el build:
+
+```sh
+npx codenhub-styles build --content "templates/**/*.html" --content "shop/templates/**/*.html" --output static/stylekit.css
+```
+
+```django
+{% load static %}
+<link rel="stylesheet" href="{% static 'stylekit.css' %}" />
+```
+
+Escribe la salida en una carpeta incluida en `STATICFILES_DIRS`, aquí `static/`, para que `collectstatic` la recoja. La configuración de arriba solo incluye la carpeta del paquete, así que añade `BASE_DIR / "static"` a esa lista si tu proyecto aún no la tiene.
+
+### Opciones
+
+- `--content <glob>`, o `-c <glob>`, indica los archivos en los que buscar nombres de clase. Es obligatorio y se puede repetir: pásalo una vez por glob, y el build lee todos los archivos que coincidan con alguno. Un glob relativo se resuelve respecto a la carpeta desde la que ejecutas el comando, así que ejecútalo desde la raíz de tu proyecto; un glob absoluto se usa tal cual. `**` coincide con cualquier número de carpetas, y `{rb,erb}` con cualquiera de las dos extensiones. Sirve cualquier archivo de texto, tenga la extensión que tenga. Cada glob tiene que coincidir con al menos un archivo, o el build falla y lo nombra, así que una errata no puede publicar una hoja de estilos vacía. Los archivos que excluye tu `.gitignore` se leen igualmente cuando un glob coincide con ellos, y no se lee nada fuera de tus globs.
+- Pon cada glob entre comillas. Sin comillas, tu shell puede expandir el glob a una lista de archivos antes de que el comando lo vea, y solo el primer archivo cuenta como valor de `--content`. Cuando eso deja nombres de archivo sobrantes, el build los rechaza en lugar de leer en silencio menos de lo que querías; cuando el glob coincidió con un solo archivo, el build lee solo ese archivo y nada de lo que tus plantillas añadan más adelante.
+- `--output <file>`, o `-o <file>`, es la hoja de estilos que se escribe. Es obligatorio. Una ruta relativa se resuelve respecto a la carpeta desde la que ejecutas el comando, las carpetas padre que falten se crean, y un archivo existente se reemplaza.
+- `--aesthetic <name>` añade una de las [estéticas](../usage/aesthetics.md): `neobrutalism`, `glass`, `pixel`, `chunky-tile`, `cyber` o `sketch`. Repítelo para más de una; nombrar una dos veces la incluye una sola vez. Las estéticas se piden explícitamente porque el build no puede saber por tus plantillas cuál quieres, así que cada una se escribe completa cuando la pides, y no se incluye ninguna cuando no lo haces.
+- `--no-minify` escribe en su lugar CSS legible e indentado. Sirve para leer lo que generó el build; en producción sirve el archivo minificado.
+- `--help` imprime el uso, con las estéticas que trae esta versión. `--version` imprime la versión del paquete. Ninguno de los dos genera nada, y ambos terminan con estado 0.
+
+La salida siempre contiene el tema, sus design tokens como propiedades personalizadas de CSS, el reset y las reglas base de las que dependen todos los componentes. Encima van cada clase de StyleKit que usan tus plantillas, con las variantes con las que la combinas, como `primary` o `soft`, y cada utilidad de Tailwind que usan, como `flex` o `mt-4`. La salida se construye a partir de la hoja de estilos completa, no de `/native`, así que no incluye los mapeos sin clases.
+
+### Cómo se encuentran las clases
+
+El build no ejecuta tus plantillas. Lee como texto simple cada archivo que coincide con tus globs de `--content`, recoge cada palabra que podría ser un nombre de clase y escribe las reglas de las palabras que son clases de StyleKit o utilidades de Tailwind. Tailwind CSS también lee el contenido así.
+
+Una clase tiene que aparecer en un archivo como una palabra completa. `class="btn primary"`, `class: "btn primary"` y `classes = ["btn", "primary"]` funcionan. Una palabra que solo parece una clase también cuenta: un comentario que dice "card" añade todas las reglas de la tarjeta a la hoja de estilos, lo que agranda el archivo y no cambia nada en la página.
+
+Un nombre de clase que tu código arma al renderizar nunca aparece completo en ningún archivo, así que el build no puede encontrarlo. En `class="btn <%= @order.priority %>"`, `btn` se encuentra, pero la intención es lo que contenga `priority` al renderizar; si es `destructive`, el botón se renderiza sin su rojo. Hay dos salidas:
+
+- **Escribe los nombres de clase completos.** Asigna cada valor a un nombre de clase completo en un archivo que el build lea, como `{ "urgent" => "destructive", "normal" => "neutral" }.fetch(@order.priority)` en un helper.
+- **Enuméralos en un archivo de safelist.** Un archivo de texto simple con un nombre de clase por línea, añadido con su propio `--content`, como `--content config/stylekit-classes.txt`. Guárdalo junto al código que arma los nombres de clase, para que quien cambie uno vea el otro.
+
+### Lo que no hace
+
+- **No tiene modo watch.** Genera una vez y termina. Vuelve a ejecutarlo después de cambiar una plantilla, desde un script o desde un observador de archivos que ya tengan tu framework o tu editor. Una clase que la hoja de estilos todavía no tiene deja su elemento sin estilo hasta el siguiente build.
+- **No tiene archivo de configuración ni CSS propio.** No puedes añadir tus propios valores de `@theme`, definiciones de `@utility` ni plugins. Para cambiar el aspecto, sobrescribe las propiedades personalizadas en una hoja de estilos tuya cargada después de esta, como describe [Personalización](../usage/customizing.md). Cuando necesites la configuración propia de Tailwind, instala Tailwind CSS e importa el punto de entrada de código fuente desde tu propia entrada de Tailwind, como muestra [Tailwind CSS v4](./tailwind.md).
+- **No tiene otros comandos.** `build` es el único; `--help` y `--version` son los únicos flags que funcionan sin él.
+- **No trae una versión de Tailwind propia.** Cada build usa los `@tailwindcss/cli` y `tailwindcss` instalados en tu proyecto, dentro del rango `>=4.3.2 <5` que StyleKit admite, así que tu lockfile los fija.
+
+### En un despliegue
+
+Genera la hoja de estilos antes del paso que recoge o añade huella a tus assets, como `rails assets:precompile`, `php artisan optimize` o `python manage.py collectstatic`. Puedes hacer commit de la salida, de modo que los servidores no necesitan Node.js en absoluto, a cambio de un archivo generado que alguien tiene que acordarse de regenerar; o generarla en el despliegue, de modo que la máquina de build necesita Node.js 24 o posterior.
+
+Fija la versión. Por debajo de 1.0 una versión menor puede renombrar o eliminar una clase, así que el mismo comando puede escribir otra hoja de estilos con una versión más nueva. Haz commit de `package.json` y del lockfile que escribe npm, e instala con `npm ci` en la máquina de build, para que cada build use las versiones que probaste.
+
+### Cuando el build falla
+
+Cada fallo imprime una línea que empieza por `codenhub-styles:` en la salida de error estándar y termina con estado 1, sin escribir el archivo de salida, así que un script de despliegue se detiene en lugar de publicar una hoja de estilos desactualizada o vacía. La línea dice qué salió mal y qué hacer:
+
+- **`missing --content` o `missing --output`.** Añade la que nombra. Un `--output` vacío o con solo espacios cuenta como ausente.
+- **`--content "<glob>" matches no file in <folder>`.** Suele ser una errata en la ruta, un comando ejecutado desde una carpeta distinta de la raíz de tu proyecto, o un glob de un lugar que tu proyecto no usa. Generar a partir de nada escribiría una hoja de estilos sin clases de componente, y el sitio perdería sus estilos sin avisar.
+- **`unexpected argument "<file>"`.** Casi siempre es un glob de `--content` sin comillas, que tu shell expandió a una lista de archivos. Pon el glob entre comillas.
+- **`unknown option "<flag>"`.** Una errata, o una opción de otra herramienta, como `--watch` o `--config`. `--help` enumera las opciones.
+- **`option "<flag>" is missing its value or does not take one`.** Un flag que lleva valor fue lo último de la línea, o se le dio un valor a `--no-minify`, como en `--no-minify=true`.
+- **`unknown aesthetic "<name>"; choose from ...`.** Elige uno de los nombres de la lista. Van en minúsculas y con guion, como `chunky-tile`.
+- **`missing command` o `unknown command "<name>"`.** La primera palabra después de `codenhub-styles` tiene que ser `build`.
+- **`this command needs @tailwindcss/cli and tailwindcss, which are not installed`.** La línea nombra el que falte de los dos y termina con el comando que lo instala. Ejecútalo desde la raíz de tu proyecto.
+- **`this command needs Node.js 24 or newer`.** Actualiza Node.js en la máquina que genera el CSS.
+- **`Tailwind failed to build the stylesheet: <reason>`.** `<reason>` es el propio mensaje de Tailwind. `EISDIR` significa que `--output` nombra una carpeta existente, así que nombra un archivo dentro de ella; `EACCES` o `EPERM` significa que no puedes escribir ahí. Ante cualquier otro motivo, ejecuta el mismo comando con `--no-minify` para descartar el minificador, e informa del mensaje junto con la versión que imprime `--version`.
+
+## Comprobar que funciona
+
+Renderiza un elemento con estilo, como en [Integración → Comprobar que funciona](./index.md#comprobar-que-funciona):
+
+```html
+<button class="btn primary">Save changes</button>
+```
+
+Un botón redondeado relleno con el color principal significa que la hoja de estilos se ha cargado. Si el botón se ve como el predeterminado del navegador, abre el panel de red del navegador: un `404` en la hoja de estilos significa que la ruta o la configuración de archivos estáticos es incorrecta.
+
+## Siguiente paso
+
+Vuelve al camino principal: [Construir una pantalla](../concepts.md) añade la primera tarjeta y el primer formulario a la página de ajustes. [Configuración inicial → Todos los puntos de entrada](../setup.md#todos-los-puntos-de-entrada) enumera todas las demás hojas de estilos que puedes importar.