Kalka
Dokumentation

Komponenten und Variablen

Wiederverwendbare Komponenten mit Varianten und Eigenschaften, die Variablen-Seite mit Sammlungen und Modi, und wie Variablen zu CSS Custom Properties und Design-Tokens werden.

docs / components-variables

Komponenten

Eine Komponente ist ein Design, das du wiederverwendest: ein Button, eine Karte, eine Navigationsleiste. Ihre Kopien, Instanzen genannt, folgen ihr. Änderst du die Komponente, ändern sich alle Instanzen, außer dem, was eine Instanz überschreibt.

  • Komponente erstellen: Wähle Ebenen aus und drücke Cmd Alt K (Ctrl Alt K).
  • Eine Instanz anlegen: Ziehe die Komponente aus dem Panel Elemente auf den Canvas, oder nutze dort Instanz einfügen.
  • Zur Hauptkomponente springt von einer Instanz zu ihrer Komponente.
  • Instanz lösen (Cmd Alt B, Ctrl Alt B) macht aus einer Instanz wieder normale Ebenen.

Das Panel Elemente listet die Komponenten des Dokuments, als Raster oder Liste, mit einer Suche.

Varianten

Varianten sind Versionen einer Komponente, etwa ein Button, der primär oder sekundär, klein oder groß ist. Wähle mehrere Komponenten aus und nutze Komponentensatz erstellen (Shift Cmd K, Ctrl Shift K), dann füge Varianteneigenschaften und ihre Werte hinzu. Jede Variante braucht ihre eigene Kombination von Werten. Auf einer Instanz wechselst du die Variante im Design-Panel.

Komponenteneigenschaften

Neben Varianten kann eine Komponente Folgendes anbieten:

  • Text-Eigenschaften, um auf jeder Instanz eine Beschriftung zu ändern;
  • Boolean-Eigenschaften, um einen Teil ein- oder auszublenden;
  • Eigenschaften zum Instanz austauschen, um eine verschachtelte Komponente zu ersetzen, etwa ein Icon;
  • Slots, Bereiche, in die jede Instanz ihre eigenen Ebenen aufnimmt, mit Grenzen für deren Anzahl.

Lege eine mit Eigenschaft erstellen… im Design-Panel an, oder aus einem Feld heraus mit Komponenteneigenschaft anwenden. Instanzen zeigen diese Eigenschaften oben im Design-Panel.

Verhalten

Eine Komponente kann sich wie ein echtes Bedienelement verhalten: ein Schalter, eine Checkbox, ein Schieberegler, Tabs, ein Textfeld, ein Akkordeon, ein Button mit den Zuständen Hover, gedrückt, Fokus und deaktiviert, und mehr. Wähle es im Bereich Verhalten der Komponente. Ansicht › Vorschau (Cmd Alt Enter) lässt die Bedienelemente dann wirklich laufen: Du kannst in ein Textfeld tippen, einen Schieberegler ziehen, ein Akkordeon öffnen, auch per Tastatur. Am Dokument ändert sich beim Ausprobieren nichts; Esc bringt dich zurück zum Bearbeiten.

Bibliotheken

Um Komponenten zwischen Dokumenten zu teilen, veröffentliche ein Dokument mit Bibliothek veröffentlichen als Bibliothek und aktiviere sie in einem anderen Dokument mit Bibliotheken verwalten. Ändert sich die Bibliothek, zeigt Bibliotheksaktualisierungen prüfen, was sich geändert hat, nebeneinander oder überlagert, bevor du aktualisierst.

Variablen

Variablen sind benannte Werte, die du wiederverwendest: eine Markenfarbe, ein Abstand, eine Schriftgröße, eine Beschriftung. Änderst du die Variable, folgt jede Ebene, die sie verwendet.

Die Variablen-Seite öffnen

Klicke in der linken Leiste auf Variablen. Im Desktop-Editor öffnet sich die Variablen-Seite über den Panels und dem Canvas. Drücke erneut auf Variablen, wähle ein anderes Panel oder drücke Esc, um den Canvas so zurückzubekommen, wie er war. Du kannst sie auch über Ansicht › Variablen… öffnen, oder mit Variablen öffnen im Design-Panel, wenn nichts ausgewählt ist. Auf einem Smartphone-Bildschirm öffnet sie sich als Dialog.

Die Variablen-Seite mit einer Sammlung Tokens: Variablen für Farben, Abstände und Radien mit Werten für Light und Dark, ihre CSS-Namen und darunter das erzeugte Stylesheet
Die Variablen-Seite: jede Variable mit ihrem CSS-Namen und einem Wert pro Modus, dazu das Stylesheet, das Kalka schreibt.

Typen

Typ Für
Farbe Füllungen, Konturen, Schattenfarben
Zahl Größen, Abstände, Radien, Deckkraft, Schriftgrößen
Text Beschriftungen, Texte, Schriftfamilien
Boolean wahr oder falsch, etwa ob eine Ebene sichtbar ist

Mit ihren Geltungsbereichen lässt sich eine Variable auf bestimmte Felder beschränken, damit ein Abstand nie in einer Farbliste auftaucht. Ihr CSS-Ausdruck erlaubt ihr, im Code etwas wie clamp(1rem, 4vw, 1.5rem) zu enthalten.

Sammlungen und Modi

Variablen liegen in Sammlungen, etwa Farben oder Abstände, und lassen sich in Gruppen sortieren. Eine Sammlung kann Modi haben: hell und dunkel, kompakt und großzügig, einen pro Marke. Jede Variable hat einen Wert pro Modus.

Jeder Modus legt fest, wann er im exportierten CSS gilt:

  • von Hand umgeschaltet, über ein Attribut wie data-theme;
  • wenn das System im dunklen oder hellen Modus ist;
  • bei hohem Kontrast oder reduzierter Bewegung;
  • unter oder über einer Bildschirmbreite oder einer Container-Breite;
  • oder unter einem beliebigen CSS-Selektor oder einer @media-, @supports- oder @container-Abfrage, die du schreibst.

Eine Variable verwenden

Klicke neben einem Feld auf Variable verwenden und wähle eine aus der kleinen Liste; beim Überfahren einer Farb- oder Zahlenvariable siehst du sie als Vorschau auf dem Canvas. Variable lösen setzt wieder einen festen Wert. Aus einem Wert, den du schon gesetzt hast, machen Farbvariable aus … erstellen oder Zahlenvariable aus … erstellen in einem Schritt eine Variable.

Variablen im Code

Variablen sind CSS Custom Properties. Der Standardmodus jeder Sammlung steht in :root, und andere Modi überschreiben unter ihrer Bedingung nur die abweichenden Werte. Eine Variable namens Gray/50 wird zu --color-gray-50, und Space/small wird zu --spacing-small; du kannst auch einen eigenen CSS-Namen festlegen.

Auf der Variablen-Seite kannst du:

  • Alle Variablen als CSS kopieren oder Alle Variablen als Tailwind-Theme kopieren (@theme);
  • Als Design-Tokens exportieren: eine .zip mit W3C-Design-Tokens, eine Datei pro Modus einer Sammlung;
  • Design-Tokens importieren aus .json-, .tokens- oder .zip-Dateien. Variablen mit gleichem Namen werden aktualisiert; gelöscht wird nichts.

In einem Kalka-Ordner werden Variablen als W3C-Design-Tokens in design-system/tokens.json gespeichert und als CSS in design-system/tokens.css. Siehe Dateien und Versionen.