Guía

CSS-Zero te permite escribir estilos CSS en archivos de contrato (.css.ts/.css.js). En tiempo de compilación, el compilador ejecuta esos archivos, reemplaza cada llamada de utilidad con un token de cadena determinista y emite el CSS correspondiente como un único bloque. Nada se ejecuta en el navegador.

CSS-Zero está inspirado en vanilla-extract (escritura de .css.ts con seguridad de tipos y cero runtime) y Tailwind CSS (clases de utilidad/variantes componibles), unificados en torno a una sola idea: todo es un token reutilizable.

¿Por qué se llama reutilizable CSS-in-TS?

En mi opinión, el valor del código a menudo puede medirse por su reutilización. CSS-Zero está construido para hacer que los estilos sean reutilizables sin complejidad ni limitaciones estrictas.

El único requisito es escribir estilos en archivos con la extensión .css.ts/.css.js. A partir de ahí, la reutilización es un concepto de primera clase en todos los niveles:

• Reglas reutilizables — className, classSelector, id, idSelector, variable, animation, font, layer, container producen tokens pequeños y autocontenidos que puedes componer libremente.
• Variantes reutilizables — variants y theme convierten un único estilo base en una familia de modificadores, de modo que un componente puede cubrir muchos estados visuales sin duplicar CSS.
• Condicionales reutilizables — style(config, deps) te permite adjuntar estilos que se emiten solo cuando los tokens referenciados se usan realmente en el bundle.
• Librerías reutilizables — un módulo .css.ts es simplemente un módulo. Puedes publicar una librería de estilos en NPM y consumirla como una dependencia normal en cualquier proyecto, importando tokens como cualquier otro export. La librería incluso puede estar precompilada a .css.js — CSS-Zero entiende ambos formatos, por lo que los consumidores nunca se preocupan de cómo se distribuyó.

Cada utilidad devuelve una cadena simple o cadenas dentro de arrays / objetos planos — nada más. En tiempo de compilación, el compilador sustituye cada resultado único con una cadena especial llamada token (p. ej. o-s_1, --o-v_1) y emite el CSS correspondiente. Como los tokens son únicos, los estilos no utilizados se eliminan con tree-shaking — solo se envía el CSS que realmente usas, y nada de esta reutilización cuesta nada en runtime.

Como resultado, defines el estilo una vez, reutilizas en todas partes y envías solo lo que usas.

Instalación

npm i @css-zero/core @css-zero/vite-plugin

Configuración (Vite)

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { cssZero } from '@css-zero/vite-plugin';

export default defineConfig({
    plugins: [react(), cssZero()],
});

Escribe estilos en un archivo .css.ts e importa los tokens en tus componentes.

// Button.tsx
import { btn } from './styles.css.ts';

export function Button() {
    return <button className={btn}>Click</button>;
}

Utilidades

Reglas individuales

Utilidad	Firma	Devuelve
className	(rule?) => string	Token de clase único (p. ej. o-s_1)
classSelector	(rule?) => [string, string]	[token, '.token']
id	(rule?) => string	Token de id único
idSelector	(rule?) => [string, string]	[token, '#token']
variable	(config?) => [string, string]	[--token, 'var(--token)']
animation	(config?) => string	Token de nombre @keyframes único
font	(config?) => string	Token de familia @font-face único
layer	() => string	Cadena @layer token única
container	(type?) => [string, string]	[container, '@container name']

Reglas compuestas

Utilidad	Firma	Devuelve
variants	(config, base?) => Record<string, string>	Mapa de tokens de modificadores, selector .base.mod
theme	(vars, options) => [Record, Record]	[varRefs, optionClasses]
style	(config, deps?) => string	Estilos globales (sin deps) o bloque AND condicional

Ejemplos

className

import { className } from '@css-zero/core';

export const btn = className({
    color: 'white',
    '&:hover': { color: 'gray' },
});
// → 'o-s_1'

classSelector

import { classSelector } from '@css-zero/core';

export const [card, cardSelector] = classSelector({
    display: 'block',
    padding: '16px',
    borderRadius: '8px',
});
// card → 'o-s_1', cardSelector → '.o-s_1'

id

import { id } from '@css-zero/core';

export const badge = id({ backgroundColor: 'red' });
// → 'o-i_1'

idSelector

import { idSelector } from '@css-zero/core';

export const [modal, modalSelector] = idSelector({
    position: 'fixed',
    inset: 0,
});
// modal → 'o-i_1', modalSelector → '#o-i_1'

variable

import { variable } from '@css-zero/core';

// [name, var(name)]
export const [accentKey, accent] = variable('#2b6cb0');
// → ['--o-v_1', 'var(--o-v_1)']

animation

import { animation } from '@css-zero/core';

export const spin = animation({
    from: { transform: 'rotate(0)' },
    to: { transform: 'rotate(360deg)' },
});

font

import { font } from '@css-zero/core';

export const inter = font({
    src: "url('/fonts/inter.woff2') format('woff2')",
    weight: '400 700',
    display: 'swap',
});
// → 'o-f_1' — use it as `fontFamily: Inter`

layer

import { layer } from '@css-zero/core';

export const base = layer();
// → '@layer o-l_1'

container

import { container } from '@css-zero/core';

export const [card, cardQuery] = container('inline-size');
// card → 'o-c_1 / inline-size', cardQuery → '@container o-c_1'

variants

import { variants } from '@css-zero/core';

export const tone = variants(
    { primary: { color: '#fff' }, ghost: { color: 'gray' } },
    btn // optional base token → selector becomes `.btn.primary`
);
// → { primary: 'o-s_2', ghost: 'o-s_3' }

theme

import { theme } from '@css-zero/core';

// [varRefs, optionClasses]
export const [tokens, options] = theme(
    { accent: '#2b6cb0', spacing: '8px' },
    { dark: { accent: '#0f0' }, compact: { spacing: '4px' } }
);
// tokens.accent → 'var(--o-v_1)'
// options.dark  → 'o-s_1' (overrides accent when applied)

style

import { style } from '@css-zero/core';

// no deps - always emitted
style({ body: { margin: 0 } });

// emitted only if all deps are used in the bundle
style({ [`${btnSelector} > span`]: { display: 'block' } }, [btnSelector]);

Extender tipos

Combina tus propias propiedades CSS personalizadas mediante la fusión de declaraciones de interfaces:

declare global {
    namespace CSSZero {
        interface ExtraProperties {
            '--brand': string;
        }
    }
}

Publicar una librería de estilos

Los módulos de contrato son módulos ordinarios, por lo que puedes publicar estilos como un paquete NPM y consumirlos:

// your-lib/src/buttons.css.ts
export const [btn, btnSelector] = classSelector({ /* ... */ });
export const btnBg = variants({ primary: { /* ... */ }, ghost: { /* ... */ } }, btn);

import { btn, btnBg } from 'your-lib/src/buttons.css';

<button className={`${btn} ${btnBg.primary}`}>Button</button>

Opciones del plugin

Opción	Tipo	Predeterminado	Descripción
prefix	string	'o'	Prefijo de nombre para cada token (o-s_1, --o-v_1).
build.inline	boolean	false	Inline el CSS en una etiqueta <style> en <head> en lugar de un <link>

Importante

Fuera de un bundler (SSR, Jest, tsc/IDE), @css-zero/core devuelve cadenas vacías — las firmas son correctas, los valores son marcadores de posición. La ruta de trabajo pasa por @css-zero/compiler y @css-zero/vite-plugin.

Paquetes

Paquete	Rol
@css-zero/core	Tipos reales de utilidades + stubs de cadena para tsc/IDE
@css-zero/compiler	Motor de compilación independiente de la herramienta de build
@css-zero/vite-plugin	Fachada de Vite: compila, agrega, inline/emite CSS, elimina imports