Sistema di componenti senza interfaccia · Nuova risorsa
Sistema di progettazione Kobalte.
Kobalte offre componenti headless per Solid, inclusi campi numerici con valori grezzi e formattati separati, l’anatomia composta delle checkbox e pulsanti con stato premuto. Questa guida collega le primitive ai segnali Solid attraverso uno scaler di ricette con quantità derivate e caselle degli ingredienti ripristinabili.
Riferimento di progettazione del sistema di progettazione sistema di design Kobalte
Kobalte 0.13.14 fornisce primitive headless per Solid, non una scala visiva canonica. Ogni colore e dimensione recipe-* riportati di seguito costituisce la configurazione originale completa dell’applicazione. I nomi API e gli attributi di stato sono stati verificati nel pacchetto installato e nella documentazione ufficiale dei componenti.
Sistema di progettazione sistema di design Kobalte: collega i componenti Kobalte ai segnali Solid
Collega i componenti Kobalte ai segnali Solid
Il componente usa i segnali Solid per le porzioni, gli ingredienti raccolti e l’elemento fissato. createMemo ricava la validità dal segnale numerico e For visualizza una raccolta stabile di ingredienti. Le proprietà controllate di Kobalte leggono direttamente questi segnali; gli aggiornamenti non richiedono un provider di moduli separato né un adattatore di stato in stile React.
NumberField, Checkbox e ToggleButton vengono importati dai rispettivi entry point dei componenti. Hanno funzioni diverse: il campo numerico gestisce l’input numerico modificabile, ogni casella di controllo rappresenta un ingrediente raccolto e il pulsante a commutazione mantiene lo stato dell’elemento fissato della ricetta. Le regole aritmetiche e di invalidazione restano nelle funzioni dell’applicazione, anziché essere incorporate nei selettori visivi.
Sistema di progettazione sistema di design Kobalte: mantieni separati lo stato numerico e il testo formattato
Mantieni separati lo stato numerico e il testo formattato
NumberField riceve rawValue={portions()} e onRawValueChange={update}. Il segnale numerico alimenta direttamente la moltiplicazione, mentre il campo gestisce la formattazione e la modifica da parte dell’utente. Riutilizzare il testo formattato visualizzato nei calcoli introdurrebbe ipotesi di parsing relative ai separatori o alle impostazioni locali, già gestite dalla primitiva nativa.
L’esempio consente da una a otto porzioni intere, con un incremento di uno e maximumFractionDigits impostato a zero. Un predicato calcolato separato verifica comunque che il valore sia finito, intero e compreso nei limiti, perché un campo modificabile può contenere temporaneamente un valore incompleto o non valido. Se il valore non è valido, i totali mostrano un trattino lungo e le caselle degli ingredienti sono disabilitate. L’interfaccia non presenta una quantità plausibile ma errata come se fosse un input valido dell’utente.
Sistema di progettazione sistema di design Kobalte: componi il campo con la relativa etichetta e i messaggi nativi
Componi il campo con la relativa etichetta e i messaggi nativi
Il campo numerico contiene Label, DecrementTrigger, Input, IncrementTrigger, Description ed ErrorMessage. La descrizione visibile spiega sia l’intervallo sia le conseguenze della modifica delle porzioni. I trigger hanno etichette significative, Meno porzioni e Più porzioni, così i simboli meno e più non devono costituire da soli l’intero nome accessibile.
validationState passa da valido a non valido in base al predicato dell’applicazione. ErrorMessage appartiene al campo nativo, non è un paragrafo separato collocato altrove nella pagina. Per un modulo inviato, Kobalte fornisce anche HiddenInput per la serializzazione del valore grezzo; questo esempio locale non lo include perché non dispone di un endpoint di invio né di un payload del modulo.
Sistema di progettazione sistema di design Kobalte: gestisci la selezione degli ingredienti con un Set immutabile
Gestisci la selezione degli ingredienti con un Set immutabile
Ogni ingrediente usa l’anatomia completa di Checkbox: Input, Control, Indicator e Label. L’input effettivo mantiene la semantica e l’interazione da tastiera, mentre il controllo visibile mostra il segno di spunta e gli stili di stato originali. L’etichetta include sia il nome dell’ingrediente sia la quantità, così la quantità fa parte dell’elemento che l’utente sta raccogliendo.
mark crea un nuovo Set a partire dalla selezione precedente, prima di aggiungere o rimuovere un ID. Modificare soltanto il Set esistente non garantirebbe lo stesso aggiornamento affidabile del segnale. Il conteggio visualizzato legge la dimensione del Set e ogni Checkbox controlla l’appartenenza tramite l’ID stabile dell’ingrediente. Una variazione delle porzioni azzera l’intera selezione, perché aver raccolto 320 grammi non dimostra di aver soddisfatto il nuovo fabbisogno di 400 grammi.
Associa ogni nome di ingrediente visibile a Checkbox.Label.
Mantieni Checkbox.Input anche quando il quadrato visibile ha uno stile personalizzato.
Usa ID stabili per la selezione e crea un nuovo Set per ogni aggiornamento.
Sistema di progettazione sistema di design Kobalte: usa un Toggle per una scelta locale persistente
Usa un Toggle per una scelta locale persistente
L’elemento da fissare è un ToggleButton con pressed e onChange, non un normale pulsante che cambia soltanto la didascalia. Il suo stato premuto si riflette nella semantica nativa e nel selettore data-pressed. L’etichetta diventa Fissata con un segno di spunta e lo stato vicino chiarisce che la modifica riguarda solo l’anteprima locale.
Fissare la ricetta non modifica le quantità degli ingredienti né la selezione. Cambiare le porzioni azzera le caselle degli ingredienti, ma mantiene l’elemento fissato perché la ricetta è la stessa. Ripristina la ricetta predefinita reimposta insieme tutti e tre gli aspetti del modello: quattro porzioni, un Set di ingredienti vuoto e un elemento non fissato. Questi diversi ambiti di ripristino seguono il significato dello stato, invece di azzerare tutto a ogni interazione.
Sistema di progettazione sistema di design Kobalte: fornisci ai controlli headless una configurazione visiva riproducibile
Fornisci ai controlli headless una configurazione visiva riproducibile
Il foglio di stile della ricetta distingue la superficie di modifica dell’input numerico, i relativi trigger di incremento e decremento e il ruolo di selezione della casella di controllo. Il testo attenuato degli ingredienti viene applicato solo dopo la selezione; le quantità restano leggibili, così l’utente può confrontare gli importi raccolti con il numero attuale di porzioni.
La spaziatura usa quattro, otto, dodici, sedici, ventiquattro e trentadue pixel. La gerarchia tipografica originale abbina un sans serif di sistema per i controlli a Georgia per il titolo della ricetta. Una casella di controllo visiva di ventuno pixel è accanto a un’etichetta associata completa, che resta l’area di attivazione utile. Tutti questi valori esatti sono inclusi nel CSS completo, così chi legge può riprodurre l’esempio senza dover stimare le misure da uno screenshot.
Sistema di progettazione sistema di design Kobalte: adatta la composizione senza nascondere informazioni
Adatta la composizione senza nascondere informazioni
Il layout ampio affianca una scheda della ricetta flessibile a un pannello delle porzioni di 280 pixel. A 760 pixel si dispone su un’unica colonna. L’intestazione della scheda può andare a capo, le etichette degli ingredienti possono continuare su un’altra riga e la quantità resta compatta e su una sola riga. Al punto di interruzione più stretto, la spaziatura interna dei pannelli e il carattere delle etichette si riducono leggermente, invece di nascondere le quantità.
L’illustrazione dell’insalata è originale CSS ed è contrassegnata come decorativa. Il nome della ricetta, il numero di porzioni e le quantità degli ingredienti comunicano le informazioni indipendentemente dall’immagine. Quando cambi l’illustrazione o riduci la larghezza della scheda, mantieni tutte le etichette complete degli ingredienti e le rispettive quantità: sono gli input effettivi dell’attività di raccolta.
Sistema di progettazione sistema di design Kobalte: gestisci le variazioni di quantità come aggiornamenti di stati dipendenti
Gestisci le variazioni di quantità come aggiornamenti di stati dipendenti
Ogni porzione richiede 250 grammi complessivi dei cinque ingredienti. Passando da quattro a cinque porzioni, il totale visualizzato passa da 1.000 a 1.250 grammi e la quantità richiesta di arance da 320 a 400 grammi. Le caselle già selezionate vengono azzerate perché si riferivano alle quantità precedenti; l’elemento fissato resta invariato perché la ricetta è la stessa.
La funzione di aggiornamento confronta innanzitutto il valore in ingresso con il segnale corrente usando Object.is. Un callback che non comporta modifiche non deve azzerare la checklist né annunciare un cambio di quantità. I valori non validi escludono le quantità e disabilitano la raccolta; il messaggio di errore spiega quindi l’intervallo accettato. Queste regole rendono osservabili le modifiche intermedie senza consentire a un numero non valido di generare un totale fuorviante.
Seleziona i segmenti di arancia per quattro porzioni.
Aumenta a cinque e verifica che ci siano 400 g di arancia, 1.250 g in totale e zero elementi raccolti.
Fissa la ricetta, quindi ripristina i valori predefiniti e verifica che tutto lo stato locale venga azzerato.
Sistema di design Kobalte: usa una build Solid e includi l’intero foglio di stile
Usa una build Solid e includi l’intero foglio di stile
La configurazione usa il template Solid di Vite, blocca le versioni verificate di Solid e Kobalte e monta l’applicazione in un elemento radice esplicito. Il componente e il foglio di stile mostrati sopra sono file completi. Per questo esempio non servono un provider di temi, un pacchetto di icone, un font esterno o un backend.
Quando integri l’esempio in un’altra applicazione, mantieni allineati il compilatore del framework e la generazione dei componenti. Una trasformazione di React non convertirà JSX di Solid in un’applicazione Kobalte corretta. Analogamente, prima di sostituire la dipendenza bloccata, verifica un’eventuale versione principale futura di Kobalte API consultando la relativa documentazione. Le quantità della ricetta e la palette sono dati di esempio dell’applicazione: modificarli non richiede di cambiare il contratto delle primitive native.
Kobalte Esempi di componenti del sistema di design
Componente reattivo completo per la ricetta
Campo numerico nativo, struttura della checkbox e pulsante di attivazione con gestione esplicita degli errori e del ripristino.
jsx
import {createSignal,createMemo,For} from 'solid-js';
import {NumberField} from '@kobalte/core/number-field';
import {Checkbox} from '@kobalte/core/checkbox';
import {ToggleButton} from '@kobalte/core/toggle-button';
export default function App(){
const[portions,setPortions]=createSignal(4),[checked,setChecked]=createSignal(new Set()),[pinned,setPinned]=createSignal(false),[notice,setNotice]=createSignal('');
const ingredients=[{id:'orange',name:'Orange segments',grams:80},{id:'beans',name:'Cooked white beans',grams:90},{id:'leaves',name:'Salad leaves',grams:25},{id:'fennel',name:'Thinly sliced fennel',grams:40},{id:'dressing',name:'Citrus dressing',grams:15}];
const valid=createMemo(()=>Number.isFinite(portions())&&Number.isInteger(portions())&&portions()>=1&&portions()<=8);
function update(value){if(Object.is(value,portions()))return;setPortions(value);setChecked(new Set());setNotice('Portions changed. Ingredient checks were cleared for the new quantities.')}
function mark(id,value){setChecked(previous=>{const next=new Set(previous);value?next.add(id):next.delete(id);return next})}
function reset(){setPortions(4);setChecked(new Set());setPinned(false);setNotice('Restored four portions and an unchecked ingredient list.')}
return <main class="recipe-shell"><header><p class="eyebrow">KITCHEN NOTEBOOK · REACTIVE RECIPE CARD</p><h1>A brighter bowl, sized for your table.</h1><p>Change the portions, check the scaled ingredients and pin the recipe locally. The quantities are original sample data for this interface.</p></header><div class="recipe-layout"><section class="recipe-card"><div class="salad-art" aria-hidden="true"><div class="plate"><i/><b/><em/><span/><strong/></div></div><div class="recipe-heading"><div><p class="eyebrow">CITRUS & WHITE BEAN SALAD</p><h2>Fresh, crisp, generous.</h2></div><ToggleButton class="pin" pressed={pinned()} onChange={value=>{setPinned(value);setNotice(value?'Recipe pinned in this local preview.':'Recipe unpinned in this local preview.')}} aria-label="Pin recipe">{pinned()?'Pinned ✓':'Pin recipe'}</ToggleButton></div><p class="recipe-description">Sweet citrus, tender beans and crisp fennel. Use the checklist to gather the amounts for your chosen portion count.</p><div class="ingredient-title"><h3>Ingredients</h3><span>{checked().size} / 5 gathered</span></div><div class="ingredients"><For each={ingredients}>{ingredient=><Checkbox class="ingredient" checked={checked().has(ingredient.id)} onChange={value=>mark(ingredient.id,value)} disabled={!valid()}><Checkbox.Input/><Checkbox.Control class="check-control"><Checkbox.Indicator>✓</Checkbox.Indicator></Checkbox.Control><Checkbox.Label class="ingredient-label"><span>{ingredient.name}</span><strong>{valid()?ingredient.grams*portions()+' g':'—'}</strong></Checkbox.Label></Checkbox>}</For></div></section><aside class="portion-panel"><h2>Make it yours</h2><NumberField rawValue={portions()} onRawValueChange={update} minValue={1} maxValue={8} step={1} formatOptions={{maximumFractionDigits:0}} validationState={valid()?'valid':'invalid'} class="portion-field"><NumberField.Label class="field-label">Portions</NumberField.Label><div class="stepper"><NumberField.DecrementTrigger aria-label="Fewer portions">−</NumberField.DecrementTrigger><NumberField.Input/><NumberField.IncrementTrigger aria-label="More portions">+</NumberField.IncrementTrigger></div><NumberField.Description class="field-description">Choose 1–8 whole portions. Changing the quantity clears ingredient checks.</NumberField.Description><NumberField.ErrorMessage class="field-error">Enter a whole number from 1 to 8.</NumberField.ErrorMessage></NumberField><div class="portion-total"><span>Total ingredients</span><strong>{valid()?ingredients.reduce((s,x)=>s+x.grams,0)*portions()+' g':'—'}</strong></div><h3>A simple preparation order</h3><ol><li>Gather the scaled amounts and drain the cooked beans.</li><li>Combine the orange, fennel and leaves in a bowl.</li><li>Add the beans and dressing, then toss gently.</li></ol><button class="reset" onClick={reset}>Restore default recipe</button><p role="status" class="notice">{notice()||(pinned()?'Recipe pinned in this local preview.':'No shopping order or account update is created.')}</p></aside></div></main>
}
Questi valori recipe-* sono scelte originali dell’applicazione, non token ufficiali di Kobalte.
Il foglio di stile completo include una composizione adattabile e indicatori di focus visibili.
04
Kobalte Configurazione dell’agente per il sistema di design
Punto di partenza per l’implementazione
Il template Solid di Vite fornisce il compilatore JSX richiesto da Solid. Gli esempi completi di App.jsx e style.css riportati sopra contengono tutto il codice e gli stili dell’applicazione; non servono provider o servizi esterni.
javascript
// npm create vite@latest kobalte-recipe -- --template solid
// cd kobalte-recipe && npm install
// npm install [email protected] @kobalte/[email protected]
// Save the complete examples as src/App.jsx and src/style.css.
// src/index.jsx:
import {render} from 'solid-js/web';
import App from './App.jsx';
import './style.css';
render(() => <App />, document.getElementById('app'));
// index.html: <div id="app"></div><script type="module" src="/src/index.jsx"></script>
// npm run dev
Un prompt per il tuo progetto
Prompt per l’agente
Usa Kobalte 0.13.14 con Solid 1.9.15 per riprodurre la scheda della ricetta reattiva. Mantieni NumberField rawValue/onRawValueChange, i limiti da uno a otto, la convalida delle porzioni intere e la struttura completa Label/Description/ErrorMessage. Ricava i grammi degli ingredienti e i totali dal segnale delle porzioni; un effettivo cambio di quantità svuota l’insieme immutabile degli ID selezionati, ma mantiene la ricetta fissata. Mantieni le parti Checkbox native e ToggleButton pressed/onChange, disabilita la raccolta quando le quantità non sono valide e, al ripristino, imposta quattro porzioni, nessuna selezione e nessuna ricetta fissata. Includi la ricetta originale CSS completa; tutto lo stato rimane locale.
05
Kobalte Fonti e ambito del sistema di design
Verificato con Kobalte 0.13.14 e Solid 1.9.15. Tutti i token recipe-*, l’illustrazione CSS e le quantità degli ingredienti sono dati originali dell’esempio. Fissare la ricetta e raccogliere gli ingredienti modificano solo lo stato locale; non sono collegati account, servizi di acquisto o archivi persistenti di ricette.
