Tokens en Tailwind, variables CSS y CSS-in-JS

La salida de la plataforma CSS de Style Dictionary genera un archivo de propiedades personalizadas de CSS: --color-primary-500: #3b82f6; --spacing-4: 16px;, entre otras. Estas variables se definen en :root, por lo que están disponibles globalmente. Esta es la base para utilizar todos los tokens en la aplicación.

Importe el archivo de tokens CSS generado en la hoja de estilos global o en el componente de diseño raíz: @import './tokens/tokens.css'. En Next.js, impórtelo en app/layout.tsx o styles/globals.css. Una vez importado, todas las reglas CSS y los componentes de la aplicación pueden hacer referencia a las propiedades personalizadas.

Haga referencia a las variables CSS en las hojas de estilos de los componentes o en los módulos CSS: background-color: var(--color-primary-500); y padding: var(--spacing-4);. Si el valor del token cambia en el origen JSON, volver a compilar Style Dictionary actualiza el archivo CSS y todos los componentes que utilizan esa variable reflejan automáticamente el nuevo valor.

Las propiedades personalizadas de CSS permiten cambiar de tema en tiempo de ejecución. Para el modo oscuro, sobrescriba los valores de los tokens bajo un selector de tema: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Establecer document.documentElement.setAttribute('data-theme', 'dark') cambia instantáneamente todos los valores de los tokens sin recargar ni volver a compilar.

Amplíe el tema de Tailwind en tailwind.config.js para utilizar los valores de los tokens: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Importe la salida de JavaScript de Style Dictionary en la configuración de Tailwind para garantizar que las clases de Tailwind (bg-primary-500) utilicen siempre los valores de tokens autorizados.

Para utilizar temas que se puedan cambiar en tiempo de ejecución con Tailwind, configure el color para que haga referencia a una variable CSS: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. Esto requiere que la variable CSS almacene los componentes RGB sin el contenedor rgb() (--color-primary-rgb: 59 130 246). De este modo, Tailwind gestiona automáticamente las utilidades de opacidad.

Las bibliotecas CSS-in-JS utilizan un objeto de tema de JavaScript. Pase la salida de Style Dictionary como valor del proveedor de temas: <ThemeProvider theme={tokens}>. Los componentes acceden a los tokens mediante const theme = useTheme() y theme.color.primary[500]. Style Dictionary genera el objeto de tokens tipado y el proveedor de temas lo distribuye.

El complemento stylelint-no-hardcoded-colors y las reglas personalizadas de ESLint pueden imponer que no aparezcan valores hexadecimales codificados directamente en las hojas de estilos ni en los archivos de componentes. Si un desarrollador escribe color: #3b82f6 en lugar de color: var(--color-primary-500), el linter lo señala. Esto mantiene el sistema de tokens como única fuente de colores.

Cuando los nombres de las clases de Tailwind se construyen dinámicamente a partir de nombres de tokens en tiempo de ejecución, el proceso de purga de Tailwind puede eliminar esas clases porque no aparecen como cadenas estáticas en el código fuente. Añada los patrones de clases dinámicas a safelist en tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

El complemento Figma Tokens exporta directamente los valores de tokens de Figma al formato JSON de Style Dictionary. El flujo de trabajo es el siguiente: los diseñadores actualizan los colores en Figma Variables, los exportan mediante el complemento, se confirma el JSON actualizado, el script de precompilación ejecuta Style Dictionary y las salidas CSS y JS actualizadas se utilizan en la aplicación de React. El diseño y el código permanecen sincronizados.

Las propiedades personalizadas de CSS tienen como ámbito el elemento en el que se definen y sus descendientes. Esto permite realizar sobrescrituras del tema a nivel de componente: un componente de tarjeta puede establecer --color-background: var(--color-surface-elevated) en su elemento raíz, y todos los descendientes utilizan el color de superficie elevada sin necesidad de pasar propiedades por toda la cadena de componentes.

¿Cuál es la principal ventaja de utilizar propiedades personalizadas de CSS (variables) para los tokens de diseño frente a los valores estáticos de Tailwind?

Style Dictionary genera propiedades personalizadas de CSS para importarlas globalmente y objetos JS para integrarlos con Tailwind y CSS-in-JS. Las variables CSS permiten cambiar de tema en tiempo de ejecución mediante sobrescrituras de [data-theme]. Tailwind amplía su configuración con valores de tokens de la salida JS; para crear temas compatibles con la opacidad, configure Tailwind para que haga referencia a variables CSS RGB. Las reglas de lint imponen el uso exclusivo de tokens para los colores y evitan los valores codificados directamente en el código base.