Sistema di componenti senza interfaccia · Nuova risorsa
sistema di design Ariakit.
Ariakit fornisce componenti React senza stili, con stato condiviso esplicito e parti accessibili componibili. Il suo combobox distingue il testo digitato dalla selezione confermata, risultando utile per i selettori basati sulla ricerca; il cercatore di riferimenti qui sotto illustra questa distinzione con risultati raggruppati e non disponibili.
@ariakit/react 0.4.40 nativo e React 19. Tutti i token visivi e i contenuti di riferimento dell’esempio sono originali. · Riferimento per l’implementazione
02
Riferimento di progettazione del sistema di design Ariakit
Ariakit React 0.4.40 è un toolkit per l’accessibilità senza stili predefiniti. Non fornisce la palette della pagina, la scala tipografica o le spaziature riportate di seguito come tema di design nativo. Tutti i valori --app-* sono una configurazione originale esplicita usata in questo esempio eseguibile; i nomi dei componenti e gli attributi di stato sono API di Ariakit.
sistema di design Ariakit: inizia dal modello di stato del combobox
Inizia con il modello di stato di Combobox
ComboboxProvider di Ariakit collega l’etichetta, l’input modificabile, il controllo di apertura, il popup e le opzioni. Il provider gestisce lo stato di interazione condiviso, mentre ciascun componente fornisce la propria parte della struttura. In questo modo è possibile disporre in modo indipendente il campo di ricerca e il pannello con i dettagli dell’elemento selezionato, senza considerare ogni pressione di tasto come una nuova selezione.
L’esempio di ricerca dei riferimenti presenta sei record suddivisi in due gruppi con nome. Il filtro si applica alla raccolta dell’applicazione; la navigazione e la selezione delle opzioni sono gestite dal combobox nativo. Rendere esplicita questa distinzione è utile quando si sostituiscono i record statici con un’altra origine dati: l’insieme dei risultati filtrati e l’elemento attualmente confermato non sono necessariamente la stessa cosa.
sistema di design Ariakit: il testo di ricerca e la selezione confermata sono stati distinti
Il testo di ricerca e la selezione confermata sono stati distinti
L’esempio usa inputValue e setInputValue per il testo digitato, e selectedValue e setSelectedValue per il riferimento scelto. In API 0.4.40, la cui versione è stata verificata, inputValue è il nome attuale dello stato dell’input; negli esempi meno recenti possono comparire gli alias deprecati value/setValue. Il codice completo usa i nomi attuali.
Digitare «colore» restringe i suggerimenti, ma non sostituisce immediatamente la scheda dei dettagli visualizzata. La scelta di «Ruoli dei colori» conferma quell’elemento e aggiorna il pannello. Anche cancellando la ricerca, l’ultimo riferimento selezionato rimane invariato. Se ogni query parziale venisse trattata come un valore confermato, la vista dei dettagli passerebbe a record non validi o inesistenti.
sistema di design Ariakit: collega etichetta, input, controllo di apertura e popover
Collega etichetta, input, apertura e popover
ComboboxProvider fornisce uno stato condiviso a ComboboxLabel, Combobox, ComboboxDisclosure e ComboboxPopover. L’etichetta visibile identifica l’input. Il controllo di apertura è un pulsante separato con un nome accessibile esplicito, mentre il popover usa sameWidth e uno spazio di otto pixel per restare allineato all’elemento di ancoraggio.
Ogni risultato è un ComboboxItem con un valore stabile. Foundations e Components sono sezioni ComboboxGroup native con intestazioni ComboboxGroupLabel. Inserire un’intestazione in grassetto in un elenco privo di struttura non esprime la stessa relazione di raggruppamento; l’anatomia nativa mantiene tale relazione e il relativo modello di navigazione da tastiera.
sistema di design Ariakit: filtra i dati prima di visualizzare gli elementi nativi
Filtra i dati prima di visualizzare gli elementi nativi
La raccolta di esempio contiene cinque riferimenti disponibili e una Griglia sperimentale dichiarata intenzionalmente non disponibile. Il filtro dell’applicazione cerca, senza distinguere tra maiuscole e minuscole, le sottostringhe corrispondenti al nome di ciascun riferimento. I due gruppi vengono visualizzati solo se contengono record corrispondenti, evitando intestazioni vuote tra i risultati.
Se la query non produce risultati, viene mostrato un messaggio specifico che suggerisce di cancellare la ricerca o provare «colore». Il messaggio non diventa un’opzione selezionabile. Se pertinente, il record disabilitato rimane visibile con l’etichetta «Non disponibile», mentre la proprietà nativa disabled impedisce di confermarlo come selezione.
sistema di design Ariakit: verifica il percorso effettivo con freccia giù e Invio
Verifica il percorso effettivo Freccia giù e Invio
Nell’esempio autoSelect è disattivato. Dopo aver digitato una query, premendo Freccia giù si entra nell’elenco dei suggerimenti e premendo Invio si seleziona l’elemento attivo. Esc chiude il popover. Il comportamento corrisponde alle istruzioni visibili ed è stato verificato controllando il titolo del dettaglio selezionato, non soltanto la comparsa di un menu a discesa.
In un altro prodotto potrebbe essere opportuno evidenziare automaticamente un’opzione, ma questo cambia il punto di partenza della navigazione con le frecce. Quando c’è un solo risultato già attivo, un’ulteriore pressione di Freccia giù può riportare il focus sull’input. L’esempio evita questa incongruenza e applica lo stile all’elemento attivo tramite data-active-item, mantenendo distinta la posizione della navigazione da tastiera dagli elementi salvati nella lista di lettura.
Digita «colore» e attendi l’opzione corrispondente.
Premi Freccia giù, poi Invio, e controlla il pannello dei dettagli di Ruoli dei colori.
Cerca un riferimento non disponibile o inesistente e verifica che non venga confermata alcuna selezione indesiderata.
sistema di design Ariakit: l’opzione attiva, l’anello di messa a fuoco e lo stato di salvataggio hanno indicatori distinti
L’opzione attiva, l’indicatore di focus e lo stato salvato hanno segnali distinti
L’input e il controllo di apertura mostrano contorni visibili quando ricevono il focus. L’opzione attiva ha uno sfondo verde chiaro e un contorno interno di un pixel, grazie all’attributo nativo data-active-item. Le opzioni disabilitate hanno minore risalto e mantengono la propria etichetta testuale esplicita. Questi stili non si basano soltanto sull’hover.
Quando il riferimento selezionato è già nella lista di lettura, il pulsante Aggiungi viene disabilitato e il testo cambia. Questo stato di salvataggio appartiene all’applicazione ed è distinto dal risultato attualmente attivo nel combobox. Uno sfondo verde chiaro per l’azione salvata evita di rappresentare un’azione disabilitata come un altro pulsante principale attivo.
sistema di design Ariakit: la lista di lettura non sostituisce il riferimento corrente
Un elenco di lettura non sostituisce il riferimento corrente
L’aggiunta di un riferimento inserisce il suo nome in un array locale una sola volta; il riferimento corrente rimane visibile, così l’utente può consultarne le note. Ogni riga della lista di lettura ha un pulsante Rimuovi con un nome specifico. Rimuovendo un elemento, Aggiungi torna disponibile se quel riferimento è ancora selezionato. Il conteggio deriva dalla lunghezza dell’array.
Il contenuto di esempio dei dettagli include indicazioni su tipografia, spaziature e componenti, per rendere interessante esplorare la ricerca. I relativi valori sono chiaramente indicati come contenuti di esempio originali. Il lettore non deve interpretare «Display 36px» nel record Scala tipografica come un token tipografico di Ariakit: Ariakit non fornisce quel linguaggio visivo.
sistema di design Ariakit: il popover ha spazio senza ridimensionare l’intera pagina
Il popover ha spazio senza ridimensionare l’intera pagina
Il popover segue la larghezza dell’input e limita la propria altezza a 340px. Se la raccolta dei risultati è più ampia, il suo contenuto scorre all’interno di questo limite, mentre la scheda dei dettagli selezionati rimane nel normale flusso del documento. Mantieni collegati l’input, il controllo di apertura e il popup delle opzioni anche se la scheda dei dettagli viene spostata in un’altra colonna: la conferma di un elemento deve aggiornare sempre lo stesso record selezionato.
Al breakpoint originale di 700px, l’area di ricerca e la scheda dei dettagli si dispongono una sotto l’altra. I controlli di ricerca, il suggerimento da tastiera e la lista di lettura precedono la scheda selezionata nell’ordine del documento. Le immagini decorative dei riferimenti sono nascoste alle tecnologie assistive, perché il titolo e le note ne comunicano il significato effettivo.
Limita localmente un elenco di opzioni lungo, mantenendo una spaziatura leggibile tra gli elementi.
Mantieni il pannello dei dettagli confermati fuori dal popover temporaneo.
Mantieni visibili le etichette dell’input e i suggerimenti da tastiera sui dispositivi mobili.
sistema di design Ariakit: collega provider, raccolta e foglio di stile
Collega provider, raccolta e foglio di stile
Installa @ariakit/react 0.4.40 nel progetto React e mantieni la composizione completa di provider e componenti presente in App.jsx. L’esempio attuale usa inputValue/setInputValue e selectedValue/setSelectedValue come coppie controllate distinte. Mantieni disponibile il record selezionato anche quando la query corrente dell’input lo esclude dal popup.
Importa il file style.css fornito insieme al componente. La sua regola data-active-item segue la posizione della navigazione da tastiera nel combobox, mentre gli stili della lista salvata seguono lo stato dell’applicazione. Quando sostituisci i risultati caricati in modo asincrono, mantieni distinti questi due canali di stato e le relazioni tra gruppi e opzioni; non sostituire il pannello dei dettagli confermati con una stringa di query intermedia.
Esempi di componenti del sistema di design Ariakit
Ricerca completa dei riferimenti controllata
Provider, etichetta, input, controllo di apertura, elementi raggruppati nel popover e azioni locali per la lista di lettura.
jsx
import React,{useState} from 'react';
import * as Ariakit from '@ariakit/react';
const resources=[{name:'Type scale',group:'Foundations',code:'Aa',description:'A compact editorial hierarchy for headings, supporting text and labels.',notes:['Display · 36px / 1.1','Section · 24px / 1.25','Body · 16px / 1.6'],color:'#f0dbc3'},{name:'Color roles',group:'Foundations',code:'◐',description:'Separate surface, text, boundary and action roles before naming brand colors.',notes:['Canvas and raised surface','Primary and muted text','Action and on-action pair'],color:'#d6e5d8'},{name:'Spacing rhythm',group:'Foundations',code:'▥',description:'Use a small set of intervals to show relationships between content groups.',notes:['8px within a compact group','16px between related controls','32px between sections'],color:'#d6dfee'},{name:'Form field',group:'Components',code:'⌑',description:'Keep the label, hint, input and error message in one understandable group.',notes:['Persistent visible label','Hint before an error exists','Error connected to the input'],color:'#e9d8de'},{name:'Navigation menu',group:'Components',code:'☷',description:'A small set of destinations with a visible current location and keyboard access.',notes:['Destination labels describe content','Current item has a text/state cue','Collapsed layout keeps names'],color:'#e7e0c5'},{name:'Experimental grid',group:'Components',code:'▦',description:'Unavailable in this sample collection.',notes:[],color:'#e3e3e3',disabled:true}];
export default function App(){const[query,setQuery]=useState(''),[chosen,setChosen]=useState('Type scale'),[saved,setSaved]=useState([]);const selected=resources.find(x=>x.name===chosen)||resources[0],matches=resources.filter(x=>x.name.toLowerCase().includes(query.toLowerCase()));return <main className="resource-finder"><header><p className="eyebrow">ARIAKIT · ACCESSIBLE PRIMITIVES</p><h1>A reference, within reach.</h1><p>Search a small collection with the keyboard, inspect the result and keep a local reading list.</p></header><div className="finder-grid"><section className="search-area"><Ariakit.ComboboxProvider inputValue={query} setInputValue={setQuery} selectedValue={chosen} setSelectedValue={setChosen}><Ariakit.ComboboxLabel className="label">Find a reference</Ariakit.ComboboxLabel><div className="input-row"><Ariakit.Combobox className="combobox" placeholder="Try type, color or form" /><Ariakit.ComboboxDisclosure className="disclosure" aria-label="Show reference suggestions">⌄</Ariakit.ComboboxDisclosure></div><Ariakit.ComboboxPopover gutter={8} sameWidth className="popover">{['Foundations','Components'].map(group=>{const items=matches.filter(x=>x.group===group);return items.length?<Ariakit.ComboboxGroup key={group}><Ariakit.ComboboxGroupLabel className="group-label">{group}</Ariakit.ComboboxGroupLabel>{items.map(x=><Ariakit.ComboboxItem key={x.name} value={x.name} disabled={x.disabled} className="combo-item"><span>{x.name}</span><small>{x.disabled?'Unavailable':x.group==='Foundations'?'Guide':'Pattern'}</small></Ariakit.ComboboxItem>)}</Ariakit.ComboboxGroup>:null})}{!matches.length&&<p className="empty" role="status">No matching reference. Try “color” or clear the search.</p>}</Ariakit.ComboboxPopover></Ariakit.ComboboxProvider><p className="hint">Type to filter. Use ↓ and ↑ to browse, Enter to choose, Escape to close.</p><div className="collection-note"><span>06</span><div><strong>Sample references</strong><p>Five available, one deliberately disabled to show an unavailable item.</p></div></div><section className="reading-list"><h2>Your reading list <small>{saved.length}</small></h2>{saved.length?<ul>{saved.map(name=><li key={name}><span>{name}</span><Ariakit.Button className="remove" onClick={()=>setSaved(saved.filter(x=>x!==name))} aria-label={`Remove ${name}`}>Remove</Ariakit.Button></li>)}</ul>:<p className="muted">Choose a reference, then add it here.</p>}<p className="local-note">This list stays in memory and clears on reload.</p></section></section><section className="reference-card" aria-label="Selected reference"><div className="reference-art" style={{background:selected.color}} aria-hidden="true"><span>{selected.code}</span><i></i></div><div className="reference-body"><p className="eyebrow">{selected.group} · SAMPLE CONTENT</p><h2>{selected.name}</h2><p>{selected.description}</p><ul className="note-list">{selected.notes.map(note=><li key={note}>{note}</li>)}</ul><Ariakit.Button className="primary" disabled={saved.includes(selected.name)} onClick={()=>setSaved([...saved,selected.name])}>{saved.includes(selected.name)?'Added to reading list':'Add to reading list'}</Ariakit.Button><p className="scope-note">These sample reference values are original content, not Ariakit design tokens.</p></div></section></div><p className="selection-status" role="status">Selected reference: {selected.name}</p></main>}
Ariakit fornisce comportamento e semantica, non questo sistema di colori o spaziature.
Il risultato attivo è definito tramite data-active-item.
Il popover ha un'altezza massima e un'area di scorrimento proprie.
04
Configurazione dell'agente del sistema di design Ariakit
Punto di partenza per l’implementazione
Verificato con @ariakit/react 0.4.40 e React 19. Usa i nomi correnti inputValue/setInputValue e un selectedValue controllato.
jsx
// Create the project first:
// npm create vite@latest ariakit-specimen -- --template react
// cd ariakit-specimen && npm install
// In a Vite React project:
// npm install @ariakit/[email protected] react@19 react-dom@19
// Save the complete component as App.jsx and the visual configuration as style.css.
import React from 'react';
import {createRoot} from 'react-dom/client';
import App from './App.jsx';
import './style.css';
createRoot(document.getElementById('root')).render(<App />);
// index.html contains <div id="root"></div>.
// No Ariakit theme stylesheet is required; style.css is this example's original theme.
// Keep the template index.html and replace its entry with the code above.
// npm run dev
Un prompt per il tuo progetto
Prompt per l’agente
Usa il componente di ricerca dei riferimenti fornito per Ariakit 0.4.40 in React. Mantieni indipendenti inputValue/setInputValue e selectedValue/setSelectedValue di ComboboxProvider, conserva i gruppi nativi con etichetta e l'opzione a griglia Experimental disabilitata, e filtra i dati prima di visualizzare gli elementi. Mantieni verificato il percorso Freccia giù, poi Invio, con autoSelect disattivato e definisci lo stile di data-active-item separatamente dall'appartenenza all'elenco salvato. Aggiungi il riferimento confermato a un elenco di lettura locale senza duplicati e consenti di rimuoverlo senza perdere il dettaglio corrente. Includi il foglio di stile originale completo.
05
Origini e ambito del sistema di design Ariakit
Ariakit React 0.4.40. Tutti i token visivi, le illustrazioni e i valori di esempio dei riferimenti sono configurazioni originali; non si dichiara l'uso della palette o della scala tipografica ufficiale di Ariakit. Lo stato dell'elenco di lettura è locale.
