7ee621ec41
* feat(core): read and write W3C design tokens Variables export as DTCG 2025.10 token files, one per collection mode in the shape Figma imports, with text and effect styles as typography and shadow tokens and a resolver document that combines them. OpenPencil's own token fields ride in a dev.openpencil extension, so an export reads back as it was. Import reads plain mode files, resolver documents, and Tokens Studio themes, plans what it would add, update, or skip against the document without changing it, and applies the plan as one undo step: values merge into variables by name, nothing is deleted, and an updated style updates the layers that use it. * feat: import and export design tokens from the variables dialog The stylesheet menu exports the document's variables and styles as a zip of W3C design tokens, and Import design tokens reads token files, folders, or a zip into a dialog that shows where each collection and mode goes, what would be added, updated, or skipped and why, before applying it as one undo step. * feat: import and export design tokens from tools and the CLI openpencil tokens --format dtcg --out <folder> writes the token files, design_to_tokens takes the same format, and import_design_tokens imports token files into a document for AI, MCP, and openpencil tool call. The editor and these paths share one apply step behind a target interface: the editor makes each change undoable, a headless document takes them directly. Re-importing an export changes nothing it does not need to: values that match are left alone, layers that use an updated style are changed only outside instances, where they follow their component, and collections that share a name keep their own files apart. * perf(core): index token lookups when planning an import Resolving each reference scanned every token and variable, which made importing a large design system quadratic. A resolver now also finds files picked without their folders by name. * docs: document design token import and export * test: type the design token result in the tokens command test * fix: lay out the design token import dialog as a mapping list Each collection and mode sits beside the picker for where it goes, in one bordered list, so the pickers no longer read as headings. Skipped tokens use AppCollapsible, file problems AppAlert, and the counts move to the footer. * fix: keep durations, variable metadata, and style edits through design token import A duration Figma's format writes in seconds goes back into a variable that holds milliseconds. Tokens without OpenPencil's extension leave an updated variable's unit, scopes, and code syntax as they are. A style token whose value was edited in another tool takes that edit instead of the stale exact fields its extension still carries. Aliases to a repeated collection name resolve within one collection, a collection named Styles no longer collides with the resolver's styles set, and the dialog plans again when the document changes and right before applying. The editor imports the apply step directly rather than the whole format barrel. * fix: keep effect order and explicit alias targets in design token import Edited shadows take the places of the shadows they replace, so blurs keep their positions. An alias whose Figma data names a collection that is left out or absent is missing rather than bound to the same path in another collection. The resolver reserves the Styles set name only when there is a styles file. * perf(cli): print token stylesheets without loading every page A CSS or Tailwind stylesheet reads only variables, which load with the document, so tokens skips populating and laying out every page as variables already does. On an 85 MB design kit this takes the command from about seven minutes to seconds.
9.1 KiB
| title | description |
|---|---|
| Variables | Crear variables, colecciones y modos, y vincularlas a propiedades de diseño. |
Variables
Las variables almacenan tokens de diseño reutilizables, como colores, espaciados y otras propiedades, que se pueden vincular a objetos. Si cambias el valor de una variable, se actualizan todos los objetos que la usan.
Abrir el diálogo de variables
Ábrelo desde Ver → Variables…, buscando «Variables» en la paleta de comandos o, sin objetos seleccionados, desde la sección Variables de la pestaña Diseño. Expandir en la esquina del diálogo le da la mayor parte de la ventana.
El diálogo muestra a la izquierda las variables de la colección activa, edita a la derecha la variable seleccionada o la colección, y muestra debajo la hoja de estilos que producen. En una ventana estrecha o en un teléfono muestra un modo a la vez, y una variable, los ajustes de la colección o la hoja de estilos se abren sobre la lista con un botón para volver.
Colecciones
Las variables se organizan en colecciones. En un diálogo ancho aparecen en una barra lateral con el número de variables de cada una; si es más estrecho, como pestañas, o como menú en el móvil.
- Cambiar de colección: haz clic en ella en la barra lateral o en su pestaña
- Crear una colección: haz clic en + junto a Colecciones o en el botón de carpeta de la barra de herramientas (Crear colección)
- Renombrar o eliminar: sin ninguna variable seleccionada, la parte derecha edita la colección: cambia su nombre o elimínala desde el menú ⋯ junto al nombre (Eliminar colección)
- Atributo de cambio: el atributo que activa los modos que se cambian manualmente,
data-themepor defecto para una colección llamada Theme; escribe otro nombre, comodata-color-scheme, para adaptarlo a un código existente
Modos
Cada colección puede tener varios modos (por ejemplo, Claro y Oscuro). Los modos aparecen como columnas de valores en la lista, y una variable tiene un valor para cada modo. Se gestionan en los Ajustes de la colección:
- Añadir un modo: haz clic en + junto a Modos
- Renombrar: edita el nombre del modo
- Duplicar, establecer como predeterminado, eliminar: usa el menú ⋯ junto al modo (Duplicar modo, Establecer como predeterminado, Eliminar modo)
El modo predeterminado es Siempre activo y va en :root. Todos los demás modos tienen Se aplica cuando, que indica cuándo el modo toma el control en la hoja de estilos exportada; el CSS que escribe se muestra debajo:
| Se aplica cuando | CSS |
|---|---|
| se cambia manualmente | el atributo de cambio de la colección con el modo como valor, como [data-theme="dark"] para el modo Oscuro de una colección Theme |
| el sistema está en modo oscuro / el sistema está en modo claro | @media (prefers-color-scheme: dark) / light |
| el contraste alto está activado | @media (prefers-contrast: more) |
| la reducción de movimiento está activada | @media (prefers-reduced-motion: reduce) |
| la pantalla es más estrecha que / la pantalla es más ancha que un ancho | @media (max-width: 640px) / min-width |
| el contenedor es más estrecho que / el contenedor es más ancho que un ancho | @container (max-width: 640px) / min-width |
| CSS personalizado | cualquier selector, o una consulta @media, @supports o @container |
En el lienzo, una capa muestra un modo cuando la estableces en él, sea cual sea la condición. En el código exportado, un modo que se cambia manualmente se activa añadiendo su atributo a un elemento, así que las capas establecidas en él se exportan con ese atributo. Las capas establecidas en un modo con cualquier otra condición, incluidos los selectores personalizados, se exportan con valores literales en lugar de tokens, porque la hoja de estilos, y no la capa, decide cuándo se aplica ese modo.
Gestionar variables
Las variables se agrupan según las carpetas de sus nombres (Brand/Primary aparece como Primary dentro de Brand), con su nombre CSS y un valor por modo.
- Crear una variable: haz clic en Crear variable (o en +) y elige un tipo; la nueva variable se abre para editarla
- Seleccionar: haz clic en una fila, o muévete con las flechas y pulsa Intro. Con Shift y clic seleccionas un rango, y con Cmd y clic (Ctrl y clic en Windows y Linux) añades o quitas una fila
- Filtrar: escribe en la barra de búsqueda para filtrar por nombre, nombre CSS, descripción o valor, como
--color-brand, un color hexadecimal o la variable a la que apunta un alias, tolerando erratas como la paleta de comandos; haz clic en un grupo de la barra lateral para ver solo ese grupo y los grupos que contiene, o usa el botón de filtro (Filtrar por tipo) para ver solo algunos tipos - Renombrar o editar en el lugar: haz doble clic en un nombre, o en un valor numérico o de texto, de la lista
- Clic derecho: renombra, duplica (Duplicar), mueve a un grupo o a uno nuevo (Mover al grupo, Nuevo grupo…) o elimina (Eliminar variables) las variables seleccionadas; Delete o Backspace también las elimina
- Reordenar: arrastra una fila; el orden se conserva en el archivo
- Varias seleccionadas: la parte derecha las mueve a un grupo, las duplica o las elimina
- Deshacer y rehacer: Cmd+Z y Cmd+Mayús+Z o Cmd+Y (Ctrl en Windows y Linux) funcionan en el diálogo igual que en el lienzo, un paso por cambio. Intro confirma un campo y vuelve a la lista; mientras un campo tiene texto sin confirmar, Cmd+Z deshace lo escrito
Al seleccionar una variable se editan:
- Nombre y Nombre CSS: deja el nombre CSS vacío para derivarlo del nombre y los ámbitos, por ejemplo
--color-brand-primary. Escribe el nombre sin--; un nombre que CSS no puede usar se marca y no se guarda - Unidad: para números,
px,rem,%,ms,s,dego ninguna; los valores se introducen en esa unidad - Valor o Valores: uno por modo; un color abre el selector de color. El botón de variable (Usar una variable) junto a un valor lo hace apuntar a otra variable del mismo tipo, un alias que sigue a esa variable; Desvincular variable lo devuelve al valor que mostraba
- Expresión CSS: para números, un valor como
clamp(1rem, 4vw, 1.5rem)que se escribe en CSS en lugar del número, mientras el lienzo sigue dibujando el número - Ámbitos: para qué propiedades se ofrece la variable
- Descripción
- Ocultar al publicar: los archivos que usan este como biblioteca no ven la variable
Hoja de estilos
La parte inferior del diálogo muestra la colección activa como propiedades personalizadas de CSS. El botón de copiar (Copiar todas las variables como CSS) copia las variables de todo el documento como CSS o como un tema de Tailwind v4 (Copiar todas las variables como tema de Tailwind), de modo que los alias a otras colecciones se resuelven.
Importar y exportar design tokens
Las variables y los estilos pasan entre OpenPencil, Figma y el código como design tokens del W3C:
- Exportar: en el menú de copia de la hoja de estilos, elige Exportar como design tokens. El zip contiene un archivo por cada modo de colección, que Figma importa como modo; los estilos de texto y de efecto como tokens de tipografía y de sombra; y un resolver que lo combina todo para herramientas como Style Dictionary
- Importar: haz clic en Importar design tokens en la barra de herramientas y elige archivos de tokens o un zip. Funcionan los archivos de Figma, un resolver con los archivos que nombra y los temas de Tokens Studio
- Elegir el destino: antes de cambiar nada, el diálogo muestra cada colección y modo que encontró y adónde va: a una colección o un modo nuevos, a uno existente o a ninguna parte. Las variables y los estilos con el mismo nombre se actualizan y el resto se añade; no se elimina nada. Cuenta lo que se añadirá, actualizará y omitirá, y explica por qué se omitió cada token
- La importación es un solo paso: Deshacer la revierte entera
Vincular variables a rellenos
En la sección Relleno del panel de propiedades, usa el selector de variables para vincular una variable de color al relleno de un objeto.
- Vincular: elige una variable de color en el selector. El relleno muestra una etiqueta morada con el nombre de la variable.
- Desvincular: haz clic en el botón de desvincular de la etiqueta para quitar el vínculo. El relleno vuelve al valor de color resuelto.
Cuando cambia el valor de la variable (o al cambiar de modo), todos los rellenos vinculados se actualizan automáticamente.
Consejos
- Usa colecciones para agrupar tokens relacionados (por ejemplo,
Primitivespara colores base,Semanticpara alias por función ySpacingpara valores de maquetación). - Los modos son útiles para cambiar de tema: define valores Claro y Oscuro en la misma colección.
- Las variables admiten alias: una colección
Semanticpuede hacer referencia a valores de una colecciónPrimitives. - Consulta Dibujar formas para ver cómo funcionan los rellenos y el selector de color.