Kalka
Documentación

Componentes y variables

Componentes reutilizables con variantes y propiedades, la página Variables con colecciones y modos, y cómo las variables se convierten en propiedades personalizadas de CSS y design tokens.

docs / components-variables

Componentes

Un componente es un diseño que reutilizas: un botón, una tarjeta, una barra de navegación. Sus copias, llamadas instancias, lo siguen. Cambia el componente y cambian todas las instancias, salvo lo que una instancia sobrescribe.

  • Crear componente: selecciona capas y pulsa Cmd Alt K (Ctrl Alt K).
  • Crear una instancia: arrastra el componente desde el panel Recursos al lienzo, o usa ahí Insertar instancia.
  • Ir al componente principal salta de una instancia a su componente.
  • Separar instancia (Cmd Alt B, Ctrl Alt B) convierte una instancia de nuevo en capas normales.

El panel Recursos lista los componentes del documento, en cuadrícula o en lista, con un buscador.

Variantes

Las variantes son versiones de un mismo componente, como un botón que es primario o secundario, pequeño o grande. Selecciona varios componentes y usa Crear conjunto de componentes (Shift Cmd K, Ctrl Shift K), y luego añade propiedades de variante y sus valores. Cada variante necesita su propia combinación de valores. En una instancia, cambias de variante desde el panel Diseño.

Propiedades de componente

Además de las variantes, un componente puede ofrecer:

  • propiedades de Texto, para cambiar una etiqueta en cada instancia;
  • propiedades Booleano, para mostrar u ocultar una parte;
  • propiedades de Intercambio de instancia, para sustituir un componente anidado, como un icono;
  • slots, zonas donde cada instancia recibe sus propias capas, con límites de cuántas.

Crea una con Crear propiedad… en el panel Diseño, o desde un campo con Aplicar propiedad de componente. Las instancias muestran estas propiedades en la parte superior del panel Diseño.

Comportamientos

Un componente puede actuar como un control real: un interruptor, una casilla, un deslizador, pestañas, un campo de texto, un acordeón, un botón con estados de hover, pulsado, foco y desactivado, y más. Elígelo en la sección Comportamiento del componente. Ver › Vista previa (Cmd Alt Enter) hace funcionar los controles de verdad: puedes escribir en un campo de texto, arrastrar un deslizador, abrir un acordeón, también con el teclado. Nada cambia en el documento mientras los pruebas; Esc vuelve a la edición.

Bibliotecas

Para compartir componentes entre documentos, publica un documento como biblioteca con Publicar biblioteca y actívala en otro documento con Gestionar bibliotecas. Cuando la biblioteca cambia, Revisar las actualizaciones de la biblioteca muestra qué ha cambiado, lado a lado o superpuesto, antes de que actualices.

Variables

Las variables son valores con nombre que reutilizas: un color de marca, un espaciado, un tamaño de fuente, una etiqueta. Cambia la variable y todas las capas que la usan la siguen.

Abrir la página Variables

Haz clic en Variables en la barra izquierda. En el editor de escritorio, la página Variables se abre sobre los paneles y el lienzo. Pulsa Variables otra vez, elige otro panel o pulsa Esc para recuperar el lienzo tal como estaba. También puedes abrirla con Ver › Variables…, o con Abrir variables en el panel Diseño cuando no hay nada seleccionado. En la pantalla de un móvil se abre como un diálogo.

La página Variables con una colección Tokens: variables de colores, espaciado y redondeado con valores Light y Dark, sus nombres CSS y, debajo, la hoja de estilos generada
La página Variables: cada variable con su nombre CSS y un valor por modo, y la hoja de estilos que escribe Kalka.

Tipos

Tipo Para
Color rellenos, trazos, colores de sombra
Número tamaños, espaciados, redondeados, opacidad, tamaños de fuente
Texto etiquetas, textos, familias tipográficas
Booleano verdadero o falso, como mostrar una capa

Con sus ámbitos, una variable se puede limitar a ciertos campos, para que un espaciado nunca aparezca en una lista de colores. Su expresión CSS le permite contener algo como clamp(1rem, 4vw, 1.5rem) en el código.

Colecciones y modos

Las variables viven en colecciones, como Colores o Espaciado, y se pueden ordenar en grupos. Una colección puede tener modos: claro y oscuro, compacto y holgado, uno por marca. Cada variable tiene un valor por modo.

Cada modo indica cuándo se aplica en el CSS exportado:

  • a mano, con un atributo como data-theme;
  • cuando el sistema está en modo oscuro o claro;
  • con contraste alto o movimiento reducido;
  • por debajo o por encima de un ancho de pantalla, o de un ancho de contenedor;
  • o bajo cualquier selector CSS o consulta @media, @supports o @container que escribas.

Usar una variable

Junto a un campo, haz clic en Usar una variable y elige una de la pequeña lista; al pasar el puntero por una variable de color o de número la ves en el lienzo. Desvincular variable vuelve a poner un valor fijo. A partir de un valor que ya has definido, Crear variable de color desde… o Crear variable numérica desde… lo convierten en variable en un solo paso.

Variables en el código

Las variables son propiedades personalizadas de CSS. El modo por defecto de cada colección se escribe en :root, y los demás modos solo sobrescriben los valores que cambian, bajo su condición. Una variable llamada Gray/50 se convierte en --color-gray-50, y Space/small en --spacing-small; puedes poner tu propio nombre CSS.

Desde la página Variables puedes:

  • Copiar todas las variables como CSS, o Copiar todas las variables como tema de Tailwind (@theme);
  • Exportar como design tokens: un .zip de design tokens W3C, un archivo por modo de cada colección;
  • Importar design tokens desde archivos .json, .tokens o .zip. Las variables con el mismo nombre se actualizan; no se borra nada.

En una carpeta de Kalka, las variables se guardan como design tokens W3C en design-system/tokens.json, y como CSS en design-system/tokens.css. Consulta Archivos y versiones.