Tamagui-Designsystem.

Versionskonfiguration und CSS des Tamagui-Designsystems

Das benannte v5-Preset verwenden

Dieses Beispiel legt tamagui und @tamagui/config auf Version 2.7.7 fest und importiert defaultConfig aus @tamagui/config/v5. Der Konfigurationsname lautet v5; er bezeichnet nicht die Hauptversion des npm-Pakets. Werden diese beiden Zahlen vermischt, erhält man einen falschen Installationsbefehl. createTamagui wird einmal außerhalb der Komponente aufgerufen. Das erzeugte CSS wird vor dem Rendern des Boards eingefügt, damit Theme-Variablen und native Stile im Web tatsächlich definiert sind.

Die kleine Konfigurationsüberschreibung explizit angeben

Die bereitgestellte Quelle setzt onlyAllowShorthands auf false, da dieses Lehrbeispiel gut lesbare Langformen wie padding und backgroundColor verwendet. Das ist eine Anwendungsentscheidung zusätzlich zum Preset. Die v5-Basis enthält keinen Animationstreiber, und dieses Beispiel erfindet keinen und behauptet auch keine animierten Übergänge. Das einfache Verhalten von Fortschrittsanzeige und Checkbox funktioniert ohne zusätzliche Animationsabhängigkeit.

Tamagui Designsystem: Größen-, Abstands- und Radius-Tokens

Verwechseln Sie nicht identische Token-Bezeichnungen

In der festgelegten v5-Konfiguration beträgt size $4 44, space $4 18 und radius 4 9. Eine Komponentengröße, ein Layoutabstand und ein Eckenradius lassen sich daher nicht mit einer gemeinsamen Multiplikationsregel umrechnen. Die Referenz führt jede Kategorie separat auf, und das Beispiel verwendet die Werte der jeweiligen Kategorie über tatsächliche Tamagui-Props. Das ist hilfreicher als eine Liste allgemeiner 4px-Schritte, die in der Konfiguration nicht verwendet werden.

• size.$4 = 44
• space.$4 = 18
• radius.4 = 9
• Fließtextschriftgröße $4 = 15px bei einer Zeilenhöhe von 23px

Auch die Schriftgrößenskala separat behandeln

Die Fließtextschriftgröße $4 beträgt 15px bei einer Zeilenhöhe von 23px, während die Komponentengröße $4 weiterhin 44 beträgt. Der Systemschriftstapel wird von v5 bereitgestellt und benötigt keine heruntergeladene Schriftart. H1, H2 und Text erhalten ihren nativen Schriftkontext; die expliziten fontSize- und lineHeight-Werte in der Quelle bestimmen die Hierarchie des ursprünglichen Boards. Die äußere Breite von 880px ist eine lokale Layoutentscheidung und kein globales Tamagui-Token.

Tamagui Designsystem: Semantische Themes und Darstellung

Helles oder dunkles Theme mit einem blauen Unter-Theme kombinieren

TamaguiProvider erhält das ausgewählte defaultTheme, und Theme name="blue" löst ein entsprechendes untergeordnetes Theme auf. Die Quelle verwendet die Rollen background, backgroundHover, color und borderColor, statt im gesamten Komponentenbaum immer wieder hexadezimale Werte einzutragen. Die Tabelle enthält die tatsächlichen Werte von light_blue und dark_blue, damit sich die aufgelöste Konfiguration vergleichen lässt, anstatt von einer festen Markenpalette auszugehen.

Board-Zustand bei Änderungen der Darstellung beibehalten

Das Flag dark ist unabhängig von den Zeilen, dem Eingabeentwurf und dem Filter. Ein Wechsel der Darstellung aktualisiert die nativen Komponenten, ohne das Board zu verändern. Buttons und Checkboxen können eigene Werte für untergeordnete Themes der Komponenten auswählen, sodass ihre berechnete Farbe nicht unbedingt mit dem Hintergrund-Token des übergeordneten Themes übereinstimmt. Prüfen Sie den gerenderten Zustand, bevor Sie die Hierarchie in benutzerdefinierte CSS auflösen.

Tamagui Designsystem: Checkboxen und abgeleiteter Fortschritt

Abschlussstatus in einer einzigen Zeilensammlung halten

Jede Zeile hat eine stabile ID, einen gut lesbaren Text und einen booleschen Wert done. Checkbox erhält checked und onCheckedChange; nur der tatsächliche Wert true markiert die Zeile als erledigt. Checkbox.Indicator zeigt das Häkchen an. Der benachbarte Text und der zugängliche Name beziehen sich auf dieselbe Gewohnheit, während die Durchstreichung den Abschlusszustand visuell wiederholt. Die Quelle erstellt keinen separaten Zähler, der nicht mehr mit den Zeilen übereinstimmen könnte.

Fortschritt anhand des gesamten Boards berechnen

Tamagui Designsystem: Validierung von Entwürfen und Wiederherstellung bei Duplikaten

Ein echtes gesteuertes Eingabefeld hinzufügen

Input speichert den aktuellen Entwurf über value und onChangeText. Die Aktion Add habit entfernt überflüssige Leerzeichen und weist leere Werte mit einer sichtbaren Meldung, aria-invalid und einer Fehlerbeschreibung zurück. Nach dem Absenden eines leeren Werts wird der Fokus wieder auf das Eingabefeld gesetzt. Eine Prüfung auf Duplikate ohne Beachtung der Groß- und Kleinschreibung verhindert eine zweite Zeile mit demselben Text und lässt den Entwurf zur Korrektur stehen. Diese Regeln gehören zum ursprünglichen Board, nicht zur Bibliothek selbst.

Board erst nach einem gültigen Eintrag aktualisieren

Ein gültiger Entwurf fügt eine neue, unerledigte Zeile hinzu, leert das Eingabefeld und entfernt den Fehler. Der Nenner für den Fortschritt ändert sich sofort, da er aus der neuen Sammlung abgeleitet wird. Das Hinzufügen einer Gewohnheit richtet keine Erinnerung ein und erstellt kein Konto. Das Board wird bewusst im lokalen Zustand von React gehalten; nach dem erneuten Laden des Dokuments wird wieder das Beispiel angezeigt.

Tamagui Designsystem: Gefilterte Ansichten und Wiederherstellung bei leeren Ergebnissen

Den Geltungsbereich des Filters verdeutlichen

Show unfinished only blendet erledigte Zeilen aus, lässt sie aber in der Sammlung. Wenn in dieser Ansicht nichts mehr übrig ist, erklärt ein Text für den leeren Zustand, dass die vollständige Liste weiterhin vorhanden ist, und bietet eine direkte Möglichkeit zur Rückkehr. Dieser sinnvolle leere Zustand entsteht durch die Auswahl der Nutzenden – anders als ein dekorativer Schalter, der beliebige Platzhalterkarten austauscht.

Zurücksetzen und Darstellung getrennt halten

Reset sample board stellt die ursprünglichen drei Zeilen wieder her, leert den Entwurf und den Fehler und kehrt zur vollständigen Liste zurück. Die aktuelle Darstellung bleibt unverändert. Da jede Änderung als expliziter Zustand vorliegt, erfordert das Zurücksetzen weder ein erneutes Laden des Dokuments noch das Verwerfen des konfigurierten Providers. Theme- und Inhaltswiederherstellung lassen sich unabhängig voneinander testen.

Tamagui Designsystem: Responsive Stacks und barrierefreies Lesen

Die Höhe durch den Inhalt der Stacks bestimmen lassen

YStack ordnet den Hauptlesefluss an, während XStack die Steuerelemente der Überschrift, Checkbox-Zeilen und Aktionen ausrichtet. Die Steuerelementgruppen umbrechen, statt eine feste Desktopbreite zu erzwingen. Der äußere Container ist höchstens 880px breit und verwendet das tatsächliche Token space $4 für den Innenabstand. Der Text jeder Zeile kann sich verkleinern und umbrechen, während die Steuerelemente sowohl bei 280px als auch bei größeren Testbreiten verfügbar bleiben.

Interaktionen nach dem Umbruch testen

Bei der Browserprüfung wird eine Gewohnheit hinzugefügt, als erledigt markiert, die Liste gefiltert und die Darstellung gewechselt, bevor der Überlauf gemessen wird. Ein Screenshot des anfänglichen Layouts allein würde nicht zeigen, ob ein Fehler, eine lange Bezeichnung oder ein gefilterter Zustand die schmale Darstellung beeinträchtigt. Die native Semantik der Checkboxen und der sichtbare Text wurden zusammen mit dem abgeleiteten Fortschritt geprüft, statt ihr Vorhandensein lediglich festzustellen und ihre Funktionsfähigkeit vorauszusetzen.

Tamagui Designsystem: Vollständiger Browser-Build

Provider, CSS und Build-Definitionen bereitstellen

Die drei bereitgestellten Dateien reichen für die lokale Webstudie aus. Die JSX-Datei enthält den Provider, eine Konfiguration, das generierte Theme CSS und das gesamte Board. build.mjs legt das Webziel und die Produktionsumgebung fest und stellt für andere reine Browser-Umgebungsvariablen einen leeren process.env-Fallback bereit. Ohne diese letzte Definition kann dieses einfache Bundle mit „process is not defined“ fehlschlagen, obwohl es kompiliert.

1. Lege tamagui.jsx, build.mjs und index.html im selben Verzeichnis ab.
2. Installiere die festgelegten Pakete React und Tamagui.
3. Erstelle und stelle das lokale Verzeichnis bereit.
4. Teste leere und doppelte Einträge, den Abschluss, Filter, Theme und Zurücksetzen.

Native und Web getrennt behandeln

Tamagui-Designsystem: Komponentenbeispiele

import React,{useState} from 'react';import{createRoot}from'react-dom/client';
import{createTamagui,TamaguiProvider,Theme,YStack,XStack,Text,H1,H2,Button,Input,Checkbox,Progress,Separator}from'tamagui';import{defaultConfig}from'@tamagui/config/v5';
const config=createTamagui({...defaultConfig,settings:{...defaultConfig.settings,onlyAllowShorthands:false}});const sheet=document.createElement('style');sheet.textContent=config.getCSS();document.head.append(sheet);
const initial=[{id:1,text:'Read ten pages',done:false},{id:2,text:'Step outside for a break',done:true},{id:3,text:'Write one useful note',done:false}];
function App(){const[dark,setDark]=useState(false),[rows,setRows]=useState(initial),[draft,setDraft]=useState(''),[error,setError]=useState(''),[filter,setFilter]=useState(false);const done=rows.filter(x=>x.done).length;let shown=rows.filter(x=>!filter||!x.done);function add(){let text=draft.trim();if(!text){setError('Write a small habit before adding it.');document.querySelector('#habit-input')?.focus();return}if(rows.some(x=>x.text.toLowerCase()===text.toLowerCase())){setError('That habit is already in this list.');return}setRows([...rows,{id:Date.now(),text,done:false}]);setDraft('');setError('')}return <TamaguiProvider config={config} defaultTheme={dark?'dark':'light'}><Theme name="blue"><YStack backgroundColor="$background" color="$color" padding="$4" gap="$4" maxWidth={880} margin="auto" width="100%" minHeight={0}><XStack justifyContent="space-between" alignItems="center" flexWrap="wrap" gap="$3"><Text fontSize="$2" fontWeight="700">TAMAGUI / ORIGINAL HABIT BOARD</Text><Button size="$3" onPress={()=>setDark(!dark)}>{dark?'Light appearance':'Dark appearance'}</Button></XStack><H1 fontSize="$8" lineHeight="$8">A little progress, every day.</H1><Text fontSize="$4" lineHeight="$5">A local board built with Tamagui 2.7.7 and its v5 blue theme. Your changes stay in this page; no account or daily reminder is connected.</Text><YStack backgroundColor="$backgroundHover" borderWidth={1} borderColor="$borderColor" borderRadius="$4" padding="$4" gap="$3"><XStack justifyContent="space-between" gap="$3" flexWrap="wrap"><H2 fontSize="$5">Today’s small steps</H2><Text id="progress-count" aria-live="polite">{done} of {rows.length} complete</Text></XStack><Progress value={rows.length?done/rows.length*100:0} size="$2" aria-label="Completed habits"><Progress.Indicator animation={undefined}/></Progress><Button size="$3" alignSelf="flex-start" onPress={()=>setFilter(!filter)}>{filter?'Show all habits':'Show unfinished only'}</Button><Separator/>{shown.length?shown.map(row=><XStack key={row.id} gap="$3" alignItems="center" paddingVertical="$2"><Checkbox id={'habit-'+row.id} checked={row.done} onCheckedChange={value=>setRows(rows.map(x=>x.id===row.id?{...x,done:value===true}:x))} aria-label={row.text} size="$4"><Checkbox.Indicator><Text fontWeight="700">✓</Text></Checkbox.Indicator></Checkbox><Text flex={1} fontSize="$4" lineHeight="$5" textDecorationLine={row.done?'line-through':'none'} opacity={row.done?.65:1}>{row.text}</Text></XStack>):<YStack gap="$3"><Text fontWeight="700">Nothing unfinished in this view</Text><Text>All your habits remain in the full list. You can revisit any completed item.</Text><Button onPress={()=>setFilter(false)}>Return to all habits</Button></YStack>}</YStack><YStack gap="$3"><Text htmlFor="habit-input" tag="label" fontWeight="700">Add one small habit</Text><Input id="habit-input" value={draft} onChangeText={v=>{setDraft(v);setError('')}} placeholder="For example, stretch for five minutes" aria-describedby={error?'habit-error':undefined} aria-invalid={!!error} onKeyPress={e=>{if(e.nativeEvent.key==='Enter')add()}}/><Text id="habit-error" color="$color" aria-live="polite">{error}</Text><XStack gap="$3" flexWrap="wrap"><Button theme="active" onPress={add}>Add habit</Button><Button onPress={()=>{setRows(initial);setDraft('');setError('');setFilter(false)}}>Reset sample board</Button></XStack></YStack><Text fontSize="$2" lineHeight="$3">Native Checkbox, Input, Button and Progress components; original board content and state. Theme changes preserve the current board.</Text></YStack></Theme></TamaguiProvider>}
createRoot(document.getElementById('root')).render(<App/>);

import {build} from 'esbuild';
await build({entryPoints:['tamagui.jsx'],bundle:true,minify:true,outfile:'tamagui.bundle.js',define:{'process.env.NODE_ENV':'"production"','process.env.TAMAGUI_TARGET':'"web"','process.env':'{}'}});

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Small habits board</title><style>body{margin:0}*{box-sizing:border-box}button,input{max-width:100%}</style></head><body><div id="root"></div><script src="./tamagui.bundle.js"></script></body></html>