Système de composants sans interface · Nouvelle ressource
Système de design Ariakit.
Ariakit fournit des composants React sans style, avec un état partagé explicite et des éléments accessibles combinables. Son combobox distingue la saisie de texte de la sélection validée, ce qui le rend utile pour les sélecteurs pilotés par la recherche ; le chercheur de références ci-dessous illustre cette distinction à l’aide de résultats regroupés et indisponibles.
@ariakit/react natif 0.4.40 et React 19. Tous les jetons visuels et le contenu des références d’exemple sont originaux. · Référence de mise en œuvre
02
Ariakit Référence de conception du système de design
Ariakit React 0.4.40 est une boîte à outils d’accessibilité sans style prédéfini. Elle ne définit pas la palette de la page, l’échelle typographique ni les espacements ci-dessous comme thème natif du système de design. Toutes les valeurs --app-* constituent une configuration originale explicite utilisée dans cet exemple exécutable ; les noms des composants et les attributs d’état sont des API Ariakit.
Système de design Ariakit : commencez par le modèle d’état de Combobox
Commencez par le modèle d’état de Combobox
ComboboxProvider de Ariakit relie le libellé, le champ de saisie modifiable, le contrôle d’ouverture, le popup et les options. Le fournisseur gère leur état d’interaction partagé, tandis que chaque composant apporte sa propre partie de la structure. Le champ de recherche et le panneau des détails de la sélection peuvent ainsi être disposés indépendamment, sans traiter chaque frappe comme une nouvelle sélection.
Le chercheur de référence présente six entrées réparties en deux groupes nommés. Le filtrage relève de la collection de l’application ; la navigation et le choix des options relèvent de la combobox native. Cette séparation est utile lorsqu’on remplace les entrées statiques par une autre source de données : les résultats filtrés et l’élément actuellement sélectionné ne sont pas nécessairement les mêmes.
Ariakit : le texte de recherche et la sélection validée sont deux états distincts dans le système de design
Le texte de recherche et la sélection validée sont deux états distincts
L’exemple utilise inputValue et setInputValue pour le texte saisi, et selectedValue et setSelectedValue pour la référence choisie. Dans la version 0.4.40 API, vérifiée ici, inputValue est le nom actuel de l’état de saisie ; les anciens exemples peuvent utiliser les alias obsolètes value/setValue. Le code complet emploie les noms actuels.
La saisie de « color » réduit le nombre de suggestions, sans remplacer immédiatement la fiche détaillée affichée. Choisir Color roles valide cette référence et met à jour le panneau. Effacer la recherche conserve également la dernière référence sélectionnée. Si chaque requête partielle était considérée comme une valeur validée, la vue détaillée passerait à des entrées invalides ou inexistantes.
Ariakit : relier le libellé, le champ de saisie, le bouton d’ouverture et le popover dans le système de design
Associez le libellé, le champ de saisie, le contrôle d’ouverture et le popover
ComboboxProvider fournit un état partagé à ComboboxLabel, Combobox, ComboboxDisclosure et ComboboxPopover. Le libellé visible identifie le champ de saisie. Le bouton d’ouverture est un bouton distinct doté d’un nom accessible explicite, tandis que le popover utilise sameWidth et une marge de huit pixels pour rester aligné sur son élément d’ancrage.
Chaque résultat est un ComboboxItem doté d’une valeur stable. Foundations et Components sont des sections ComboboxGroup natives, avec des titres ComboboxGroupLabel. Un titre en gras ajouté à une liste non structurée n’exprimerait pas la même relation de groupement ; l’anatomie native porte cette relation et intègre le modèle de navigation au clavier.
Ariakit : filtrer les données avant d’afficher les éléments natifs dans le système de design
Filtrez les données avant d’afficher les éléments natifs
La collection d’exemple contient cinq références disponibles et une grille Experimental volontairement indisponible. Le filtrage s’effectue au niveau de l’application, à l’aide d’une recherche de sous-chaîne insensible à la casse dans le nom de chaque référence. Les deux groupes ne s’affichent que s’ils contiennent des entrées correspondantes, ce qui évite les titres sans contenu parmi les résultats.
Lorsqu’aucun résultat ne correspond, un message dédié suggère d’effacer la recherche ou d’essayer « color ». Ce message ne devient pas une option sélectionnable. L’entrée désactivée reste visible lorsqu’elle est pertinente et porte le libellé Unavailable ; la propriété native disabled l’empêche d’être validée comme sélection.
Ariakit : vérifier le parcours réel avec les touches Bas et Entrée dans le système de design
Vérifiez le parcours réel avec les touches Bas et Entrée
Dans cet exemple, autoSelect reste désactivé. Après avoir saisi une requête, la touche Bas déplace le focus vers la liste de suggestions et la touche Entrée sélectionne l’élément actif. La touche Échap ferme le popover. Ce comportement correspond aux instructions visibles et a été vérifié à partir du titre du détail sélectionné, et pas seulement de l’apparition d’une liste déroulante.
La mise en surbrillance automatique peut convenir à un autre produit, mais elle modifie le point de départ de la navigation avec les flèches. Lorsqu’un seul résultat est déjà actif, une nouvelle pression sur Bas peut ramener le focus au champ de saisie. L’exemple évite ce décalage et applique le style de l’élément actif à l’aide de data-active-item, afin de distinguer sa position au clavier de son éventuelle présence dans la liste de lecture enregistrée.
Saisissez « color » et attendez l’option correspondante.
Appuyez sur Bas, puis sur Entrée, et examinez le panneau détaillé de Color roles.
Recherchez une référence indisponible ou inexistante et vérifiez qu’aucune sélection non souhaitée n’est validée.
Ariakit : distinguer les indices visuels de l’option active, de l’anneau de focus et de l’état enregistré dans le système de design
L’option active, l’anneau de focus et l’état enregistré ont des indicateurs distincts
Le champ de saisie et le bouton d’ouverture affichent un contour de focus visible. L’option active se distingue par un fond vert pâle et un contour interne d’un pixel, appliqués au moyen de l’attribut natif data-active-item. Les options désactivées sont moins mises en avant et conservent leur libellé explicite. Ces styles ne reposent pas uniquement sur le survol.
Le bouton Add se désactive et change de libellé lorsque la référence sélectionnée figure déjà dans la liste de lecture. Cet état enregistré relève de l’application et est distinct du résultat actuellement actif dans la combobox. Un fond vert pâle pour l’action déjà effectuée évite de présenter une action désactivée comme un autre bouton principal actif.
Ariakit : la liste de lecture ne remplace pas la référence actuelle dans le système de design
Une liste de lecture ne remplace pas la référence actuelle
L’ajout d’une référence ajoute son nom à un tableau local, une seule fois ; la référence actuelle reste affichée pour permettre de consulter ses notes. Chaque ligne de la liste de lecture comprend un bouton Remove doté d’un nom explicite. La suppression d’une entrée réactive le bouton Add si cette référence est toujours sélectionnée. Le nombre d’éléments est calculé à partir de la longueur du tableau.
Le contenu détaillé de l’exemple comprend des conseils sur la typographie, l’espacement et les composants, afin de permettre d’explorer le chercheur. Ses valeurs sont clairement identifiées comme du contenu d’exemple original. Il ne faut pas prendre « Display 36px », dans l’entrée Type scale, pour un jeton de typographie de Ariakit : Ariakit ne fournit pas ce langage de design.
Ariakit : prévoir l’espace nécessaire au popover sans redimensionner toute la page dans le système de design
Prévoir l’espace nécessaire au popover sans redimensionner toute la page
Le popover suit la largeur du champ de saisie et sa hauteur est limitée à 340px. Si la liste de résultats est plus longue, elle défile dans cet espace, tandis que la fiche détaillée de l’élément sélectionné reste dans le flux normal du document. Gardez le champ de saisie, le bouton d’ouverture et le menu d’options liés, même si la fiche détaillée passe dans une autre colonne : la validation d’un élément doit toujours mettre à jour la même référence sélectionnée.
Au point de rupture initial de 700px, le chercheur et la fiche détaillée s’empilent. Dans l’ordre du document, les commandes de recherche, l’indication des raccourcis clavier et la liste de lecture précèdent la fiche sélectionnée. L’illustration décorative de référence est masquée aux technologies d’assistance, car le titre et les notes portent le sens utile.
Limiter localement la hauteur d’une longue liste d’options tout en conservant un espacement lisible entre les éléments.
Garder le panneau détaillé correspondant à l’élément validé en dehors du popover temporaire.
Conserver des libellés de champ visibles et des indications sur les raccourcis clavier sur mobile.
Ariakit : relier le Provider, la collection et la feuille de style dans le système de design
Relier le Provider, la collection et la feuille de style
Installez @ariakit/react 0.4.40 dans le projet React et conservez l’ensemble de la composition des fournisseurs et composants de App.jsx. L’exemple actuel utilise inputValue/setInputValue et selectedValue/setSelectedValue comme deux paires contrôlées distinctes. Conservez la référence sélectionnée disponible même si la requête saisie ne la fait plus apparaître dans la fenêtre contextuelle.
Importez le fichier style.css fourni avec le composant. Sa règle data-active-item suit la position clavier dans la combobox, tandis que les styles de la liste de lecture suivent l’état de l’application. Lorsque vous remplacez les résultats par des résultats chargés de façon asynchrone, préservez ces deux canaux d’état ainsi que les relations entre groupes et options ; ne remplacez pas le panneau de détail validé par une chaîne de requête intermédiaire.
Exemples de composants du système de design Ariakit
Outil de recherche de références entièrement contrôlé
Fournisseur, libellé, champ de saisie, divulgation, éléments groupés dans une fenêtre contextuelle et actions locales de liste de lecture.
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 fournit le comportement et la sémantique, pas ce système de couleurs ou d’espacement.
Le résultat actif est stylé à l’aide de data-active-item.
La fenêtre contextuelle possède sa propre hauteur maximale et sa propre zone de défilement.
04
Configuration de l’agent du système de design Ariakit
Point de départ de l’implémentation
Vérifié avec @ariakit/react 0.4.40 et React 19. Utilise les noms actuels inputValue/setInputValue et un selectedValue contrôlé.
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 pour votre projet
Prompt pour l’agent IA
Utilisez l’outil de recherche de références Ariakit 0.4.40 fourni dans React. Gardez inputValue/setInputValue de ComboboxProvider indépendants de selectedValue/setSelectedValue, conservez les groupes natifs avec libellés et l’option de grille Experimental désactivée, et filtrez les données avant d’afficher les éléments. Préservez le parcours vérifié consistant à appuyer sur Bas puis sur Entrée, avec autoSelect désactivé, et distinguez le style de data-active-item de l’appartenance à la liste enregistrée. Ajoutez la référence validée à une liste de lecture locale sans doublons et permettez sa suppression sans effacer le détail affiché. Incluez la feuille de style d’origine complète.
05
Sources et périmètre du système de design Ariakit
Ariakit React 0.4.40. Tous les jetons visuels, les illustrations et les exemples de références relèvent de la configuration d’origine ; aucune palette ni échelle typographique officielle de Ariakit n’est revendiquée. L’état de la liste de lecture est local.
