Sistema di progettazione Tamagui.

Configurazione versionata e CSS del sistema di progettazione sistema di design Tamagui

Usa il preset v5 specificato

Questo esempio fissa tamagui e @tamagui/config alla versione 2.7.7 e importa defaultConfig da @tamagui/config/v5. Il nome della configurazione è v5: non è la versione principale del pacchetto npm. Confondere questi due numeri porterebbe chi legge a usare il comando di installazione sbagliato. createTamagui viene eseguito una sola volta, fuori dal componente, e il relativo CSS generato viene inserito prima del rendering della bacheca, così le variabili del tema e gli stili nativi hanno una definizione web effettiva.

Rendi esplicita la piccola personalizzazione della configurazione

La sorgente fornita imposta onlyAllowShorthands su false perché questo esempio didattico usa proprietà estese leggibili, come padding e backgroundColor. È una scelta applicativa aggiuntiva rispetto al preset. La base v5 non include un motore di animazione e questo esempio non ne inventa uno né dichiara di avere transizioni animate. Il semplice comportamento di avanzamento e della casella di controllo funziona senza aggiungere una dipendenza separata per le animazioni.

Token di dimensione, spaziatura e raggio del sistema di progettazione sistema di design Tamagui

Non confondere token con etichette identiche

Nella configurazione v5 fissata, la dimensione $4 vale 44, la spaziatura $4 vale 18 e il raggio 4 vale 9. Una dimensione del componente, uno spazio nel layout e un raggio degli angoli non possono quindi essere convertiti usando un’unica regola di moltiplicazione. Il riferimento elenca separatamente ogni categoria e l’esempio usa valori specifici per ciascuna categoria tramite le effettive proprietà Tamagui. È più utile di un elenco di incrementi generici da 4px, che la configurazione non usa.

• size.$4 = 44
• space.$4 = 18
• radius.4 = 9
• font body $4 = 15px con altezza della riga di 23px

Mantieni separata anche la scala tipografica

Il font body $4 è 15px con un’altezza della riga di 23px, mentre la dimensione del componente $4 resta 44. Lo stack di font di sistema è fornito da v5 e non richiede il download di alcun font. H1, H2 e Text ricevono i rispettivi contesti tipografici nativi; i valori espliciti di fontSize e lineHeight nel codice sorgente definiscono la gerarchia della bacheca originale. La larghezza esterna di 880px è una scelta locale di layout, non un token globale Tamagui.

Temi semantici e aspetto del sistema di progettazione sistema di design Tamagui

Combina la modalità chiara o scura con un tema figlio blu

TamaguiProvider riceve defaultTheme selezionato e Theme name="blue" risolve il tema figlio corrispondente. Il codice sorgente usa i ruoli background, backgroundHover, color e borderColor anziché ripetere valori esadecimali letterali in tutto l’albero dei componenti. La tabella riporta i valori effettivi di light_blue e dark_blue, così chi legge può confrontare la configurazione risolta invece di dare per scontata una palette di brand fissa.

Mantieni lo stato della bacheca quando cambia l’aspetto

Il flag dark è indipendente dalle righe, dalla bozza di testo e dal filtro. Cambiare aspetto aggiorna i componenti nativi senza modificare la bacheca. Pulsanti e checkbox possono selezionare valori del tema figlio specifici per il componente, quindi il colore calcolato potrebbe non coincidere con quello del token di sfondo principale. Esamina lo stato renderizzato prima di appiattire la gerarchia in token CSS personalizzati.

Checkbox e progresso derivato del sistema di progettazione sistema di design Tamagui

Mantieni il completamento in un’unica raccolta di righe

Ogni riga ha un ID stabile, un testo leggibile e un valore booleano done. Checkbox riceve checked e onCheckedChange; solo il valore letterale true indica il completamento. Checkbox.Indicator mostra il segno di spunta. Il testo adiacente e il nome accessibile identificano la stessa abitudine, mentre la barratura ripropone visivamente lo stato di completamento. Il codice sorgente non crea un conteggio separato che potrebbe non essere più sincronizzato con le righe.

Calcola il progresso sull’intera bacheca

Validazione delle bozze e gestione dei duplicati del sistema di progettazione sistema di design Tamagui

Aggiungi un vero input controllato

Input mantiene la bozza corrente tramite value e onChangeText. L’azione Add habit rimuove gli spazi superflui e rifiuta i valori vuoti mostrando un messaggio, aria-invalid e una descrizione dell’errore. Dopo l’invio di un valore vuoto, il focus torna sull’input. Un controllo dei duplicati senza distinzione tra maiuscole e minuscole impedisce di aggiungere una seconda riga con lo stesso testo e conserva la bozza per consentirne la correzione. Queste regole appartengono alla bacheca originale, non alla libreria.

Aggiorna la bacheca solo dopo un’aggiunta valida

Una bozza valida aggiunge una nuova riga incompleta, svuota l’input e rimuove l’errore. Il denominatore del progresso si aggiorna subito perché deriva dalla nuova raccolta. Aggiungere un’abitudine non registra promemoria né crea un account. La bacheca usa deliberatamente lo stato locale React; ricaricando il documento si torna all’esempio.

Viste filtrate e recupero dagli stati vuoti del sistema di progettazione sistema di design Tamagui

Specifica l’ambito del filtro

Show unfinished only nasconde le righe completate senza rimuoverle dalla raccolta. Quando nella vista non resta nulla, uno stato vuoto testuale spiega che l’elenco completo esiste ancora e offre un’azione diretta per tornarvi. È uno stato vuoto significativo, prodotto dalle scelte dell’utente, non un interruttore decorativo che sostituisce schede arbitrarie con segnaposto.

Tieni separati il ripristino e l’aspetto

Reset sample board ripristina le tre righe iniziali, cancella la bozza e l’errore e torna all’elenco completo. Non modifica l’aspetto corrente. Poiché ogni modifica è uno stato esplicito, il ripristino non richiede di ricaricare il documento né di eliminare il provider configurato. Il tema e il ripristino dei contenuti restano verificabili in modo indipendente.

Stack responsivi e lettura accessibile del sistema di progettazione sistema di design Tamagui

Lascia che il contenuto dello stack determini l’altezza

YStack organizza il flusso di lettura principale e XStack allinea i controlli dell’intestazione, le righe delle checkbox e le azioni. I gruppi di controlli vanno a capo, senza imporre una larghezza fissa da desktop. Il contenitore esterno è largo al massimo 880px e usa il token effettivo di spaziatura $4 per il padding. Il testo di ogni riga può restringersi e andare a capo, mentre i controlli restano disponibili sia a 280px sia a larghezze di prova maggiori.

Verifica le interazioni dopo il riadattamento del layout

La verifica nel browser aggiunge un’abitudine, la segna come completata, filtra l’elenco e cambia l’aspetto prima di misurare l’overflow. Uno screenshot del solo layout iniziale non rivelerebbe se un errore, un’etichetta lunga o uno stato filtrato compromettono la composizione a larghezza ridotta. Sono stati verificati anche la semantica nativa delle checkbox e il testo visibile, insieme al progresso derivato, anziché limitarsi a constatarne la presenza e presumere che funzionino.

Build completa per browser del sistema di progettazione sistema di design Tamagui

Fornisci il provider, CSS e le definizioni di build

I tre file forniti sono sufficienti per lo studio web locale. Il JSX include il provider, una configurazione, il tema generato CSS e l’intera bacheca. build.mjs imposta la destinazione web e l’ambiente di produzione e fornisce un fallback vuoto per process.env, necessario per altre letture delle variabili d’ambiente riservate al browser. Senza quest’ultima definizione, il bundle semplice può generare l’errore process is not defined anche se la compilazione riesce.

1. Salva tamagui.jsx, build.mjs e index.html nella stessa cartella.
2. Installa i pacchetti React e Tamagui nelle versioni fissate.
3. Compila e servi la directory locale.
4. Verifica gli inserimenti vuoti e duplicati, il completamento, i filtri, il tema e il ripristino.

Tieni separati l’adozione nativa e quella web

Esempi di componenti del sistema di design Tamagui

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>