Ariakit stellt ungestaltete React-Komponenten mit gemeinsamem, explizitem Zustand und kombinierbaren, barrierefreien Bausteinen bereit. Bei der Combobox sind die eingegebene Suchanfrage und die bestätigte Auswahl voneinander getrennt. Dadurch eignet sie sich für suchbasierte Auswahlelemente. Die Referenzsuche unten veranschaulicht diese Unterscheidung mit gruppierten und nicht verfügbaren Ergebnissen.
Natives @ariakit/react 0.4.40 und React 19. Alle visuellen Designwerte und Beispielreferenzen sind eigens erstellt. · Implementierungsreferenz
02
Designsystem-Designreferenz für Ariakit
Ariakit React 0.4.40 ist ein ungestaltetes Barrierefreiheits-Toolkit. Es stellt weder die unten gezeigte Farbpalette noch Schriftgrößen oder Abstände als natives Designthema bereit. Alle --app-* Werte sind eine explizit festgelegte, eigens erstellte Konfiguration für dieses ausführbare Beispiel. Komponentennamen und Zustandsattribute sind Ariakit-APIs.
Designsystem von Ariakit: Beginnen Sie mit dem Zustandsmodell der Combobox
Beginnen Sie mit dem Zustandsmodell der Combobox
ComboboxProvider von Ariakit verbindet Label, bearbeitbares Eingabefeld, Steuerelement zum Öffnen, Pop-up und Optionen. Der Provider verwaltet den gemeinsamen Interaktionszustand, während jede Komponente ihren Teil der Struktur bereitstellt. So lassen sich Suchfeld und Detailbereich für die Auswahl unabhängig voneinander anordnen, ohne jeden Tastendruck als neue Auswahl zu behandeln.
Die Referenzsuche zeigt sechs Einträge in zwei benannten Gruppen. Die Filterung gehört zur Anwendungssammlung; Navigation und Optionsauswahl gehören zur nativen Combobox. Diese klare Abgrenzung ist hilfreich, wenn statische Einträge durch eine andere Datenquelle ersetzt werden: Die gefilterte Ergebnismenge und das aktuell bestätigte Element sind nicht zwangsläufig identisch.
Designsystem von Ariakit: Suchtext und bestätigte Auswahl sind unterschiedliche Zustände
Suchtext und bestätigte Auswahl sind unterschiedliche Zustände
Das Beispiel verwaltet mit inputValue und setInputValue den eingegebenen Text sowie mit selectedValue und setSelectedValue die ausgewählte Referenz. In der überprüften Version 0.4.40 von API ist inputValue die aktuelle Bezeichnung für den Eingabestatus; ältere Beispiele verwenden möglicherweise die veralteten Aliase value/setValue. Der vollständige Code verwendet die aktuellen Bezeichnungen.
Die Eingabe von „color“ schränkt die Vorschläge ein, ersetzt aber nicht sofort die angezeigte Detailkarte. Mit der Auswahl von „Color roles“ wird dieser Eintrag bestätigt und das Panel aktualisiert. Auch beim Leeren der Suche bleibt die zuletzt ausgewählte Referenz erhalten. Würde jede unvollständige Suchanfrage als bestätigter Wert behandelt, würde die Detailansicht zu ungültigen oder nicht vorhandenen Einträgen springen.
Designsystem von Ariakit: Label, Eingabe, Offenlegung und Popover verbinden
Label, Eingabe, Offenlegung und Popover miteinander verbinden
ComboboxProvider stellt ComboboxLabel, Combobox, ComboboxDisclosure und ComboboxPopover einen gemeinsamen Zustand bereit. Das sichtbare Label kennzeichnet das Eingabefeld. Das Steuerelement zum Öffnen ist eine separate Schaltfläche mit einem expliziten barrierefreien Namen. Das Popover bleibt mithilfe von sameWidth und einem Abstand von acht Pixeln am Anker ausgerichtet.
Jedes Ergebnis ist ein ComboboxItem mit einem stabilen Wert. Foundations und Components sind native ComboboxGroup-Abschnitte mit ComboboxGroupLabel-Überschriften. Eine visuell hervorgehobene Überschrift in einer unstrukturierten Liste würde nicht dieselbe Gruppierungsbeziehung ausdrücken; die native Struktur vermittelt diese Beziehung zusammen mit ihrem Tastaturverhalten.
Ariakit-Designsystem: Filterdaten vor dem Rendern nativer Elemente
Daten vor dem Rendern nativer Elemente filtern
Die Beispiel-Sammlung enthält fünf verfügbare Referenzen und ein absichtlich nicht verfügbares Experimental-Raster. Gefiltert wird auf Anwendungsebene mit einer Groß-/Kleinschreibung ignorierenden Teilzeichenfolgensuche im Namen jeder Referenz. Die beiden Gruppen werden nur gerendert, wenn sie passende Einträge enthalten. So werden leere Überschriften zwischen den Ergebnissen vermieden.
Bei einer Suche ohne Treffer erscheint eine eigene Meldung, die dazu auffordert, die Suche zu löschen oder „color“ auszuprobieren. Die Meldung wird nicht zu einer auswählbaren Option. Der deaktivierte Eintrag bleibt sichtbar, wenn er relevant ist, und trägt die Kennzeichnung „Nicht verfügbar“. Die native disabled-Prop verhindert, dass er als Auswahl übernommen wird.
Ariakit-Designsystem: Den tatsächlichen Ablauf mit Pfeil nach unten und Enter überprüfen
Den tatsächlichen Ablauf mit Pfeil nach unten und Eingabetaste überprüfen
Im Beispiel bleibt autoSelect deaktiviert. Nach Eingabe einer Suchanfrage wechselt die Taste „Pfeil nach unten“ zur Vorschlagsliste, und Enter wählt das aktive Element aus. Escape schließt das Popover. Das entspricht den sichtbaren Hinweisen und wurde anhand des Titels der ausgewählten Detailansicht überprüft, nicht nur daran, ob ein Dropdown angezeigt wurde.
In einem anderen Produkt kann eine automatische Hervorhebung sinnvoll sein, sie verändert jedoch den Ausgangspunkt der Pfeilnavigation. Ist ein einzelnes Ergebnis bereits aktiv, kann ein weiterer Druck auf „Pfeil nach unten“ den Fokus zurück zum Eingabefeld bewegen. Das Beispiel vermeidet diese Abweichung und gestaltet das aktive Element über data-active-item. So bleibt die Tastaturposition klar vom gespeicherten Status in der Leseliste getrennt.
Gib „color“ ein und warte auf das passende Ergebnis.
Drücke „Pfeil nach unten“ und dann Enter. Prüfe anschließend das Detailfeld „Color roles“.
Suche nach einer nicht verfügbaren oder nicht vorhandenen Referenz und vergewissere dich, dass keine unbeabsichtigte Auswahl übernommen wird.
Ariakit-Designsystem: Aktive Option, Fokusring und gespeicherter Status haben unterschiedliche Kennzeichnungen
Aktive Option, Fokusring und gespeicherter Zustand haben unterschiedliche visuelle Kennzeichnungen
Eingabefeld und Schaltfläche zum Öffnen haben sichtbare Fokuskonturen. Das aktive Element erhält einen blassgrünen Hintergrund und eine ein Pixel breite Innenkontur über das native Attribut data-active-item. Deaktivierte Optionen werden weniger stark hervorgehoben und behalten ihre ausdrückliche Textkennzeichnung. Diese Gestaltung ist nicht allein vom Hover-Zustand abhängig.
Die Schaltfläche „Hinzufügen“ wird deaktiviert und ihr Text ändert sich, wenn sich die ausgewählte Referenz bereits in der Leseliste befindet. Dieser gespeicherte Status gehört zur Anwendung und ist vom aktuell aktiven Ergebnis im Combobox getrennt. Eine blassgrüne Oberfläche für die gespeicherte Aktion verhindert, dass eine deaktivierte Aktion wie eine weitere aktivierte primäre Schaltfläche wirkt.
Ariakit-Designsystem: Die Leseliste ersetzt nicht die aktuelle Referenz
Eine Leseliste ersetzt nicht die aktuelle Referenz
Beim Hinzufügen wird der Name einer Referenz höchstens einmal an ein lokales Array angehängt. Die aktuelle Referenz bleibt sichtbar, damit Nutzer ihre Hinweise ansehen können. Jede Zeile in der Leseliste hat eine Schaltfläche „Entfernen“ mit eindeutigem Namen. Wird ein Eintrag entfernt, ist „Hinzufügen“ wieder verfügbar, sofern diese Referenz noch ausgewählt ist. Die Anzahl wird aus der Länge des Arrays abgeleitet.
Die Beispieldetails enthalten Hinweise zu Typografie, Abständen und Komponenten, damit sich der Finder sinnvoll erkunden lässt. Die Werte sind eindeutig als ursprüngliche Beispielinhalte gekennzeichnet. Nutzer dürfen „Display 36px“ im Eintrag „Type scale“ nicht für ein Ariakit-Typografie-Token halten; Ariakit stellt diese Design-Sprache nicht bereit.
Ariakit-Designsystem: Ein Popover braucht Platz, ohne die ganze Seite zu vergrößern
Ein Popover braucht Platz, ohne die ganze Seite zu vergrößern
Das Popover richtet sich nach der Breite des Eingabefelds und begrenzt seine eigene Höhe auf 340px. Eine größere Ergebnismenge lässt sich innerhalb dieser Begrenzung scrollen, während die Karte mit den ausgewählten Details normaler Dokumentinhalt bleibt. Eingabefeld, Schaltfläche zum Öffnen und Options-Popup müssen miteinander verbunden bleiben, auch wenn die Detailkarte in eine andere Spalte verschoben wird. Die Übernahme eines Eintrags sollte weiterhin denselben ausgewählten Datensatz aktualisieren.
Am ursprünglichen Breakpoint von 700px werden Finder und Detailkarte untereinander angeordnet. Suchsteuerelemente, Tastaturhinweis und Leseliste bleiben in der Dokumentreihenfolge vor der ausgewählten Karte. Dekorative Referenzgrafiken werden vor Hilfstechnologien verborgen, da Titel und Hinweise die eigentliche Bedeutung vermitteln.
Begrenze lange Optionslisten direkt im jeweiligen Bereich und achte auf gut lesbare Abstände zwischen den Einträgen.
Lass das übernommene Detailfeld außerhalb des vorübergehend eingeblendeten Popovers.
Sichtbare Beschriftungen der Eingabefelder und Tastaturhinweise auch auf Mobilgeräten beibehalten.
Ariakit-Designsystem: Provider, Collection und Stylesheet verbinden
Provider, Collection und Stylesheet verbinden
Installiere @ariakit/react 0.4.40 im React-Projekt und übernimm die vollständige Provider-/Komponentenkomposition aus App.jsx. Das aktuelle Beispiel verwendet inputValue/setInputValue und selectedValue/setSelectedValue als getrennte kontrollierte Paare. Halte den ausgewählten Datensatz verfügbar, auch wenn die aktuelle Eingabeabfrage ihn aus dem Popup herausfiltert.
Importiere die bereitgestellte style.css zusammen mit der Komponente. Die data-active-item-Regel richtet sich nach der Tastaturposition im Combobox, während die Stile der gespeicherten Liste den Zustand der Anwendung abbilden. Wenn du asynchron geladene Ergebnisse einsetzt, müssen diese beiden Zustandskanäle sowie die Beziehungen zwischen Gruppen und Optionen erhalten bleiben. Ersetze das übernommene Detailfeld nicht durch eine vorübergehende Suchzeichenfolge.
Provider, Beschriftung, Eingabefeld, Schaltfläche zum Öffnen, gruppierte Popover-Elemente und Aktionen für die lokale Leseliste.
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 stellt Verhalten und Semantik bereit, nicht dieses Farb- oder Abstandssystem.
Das aktive Ergebnis wird über data-active-item gestaltet.
Das Popover hat eine eigene maximale Höhe und einen eigenen Scrollbereich.
04
Ariakit-Designsystem: Einrichtung des AI-Agenten
Ausgangspunkt für die Implementierung
Verifiziert mit @ariakit/react 0.4.40 und React 19. Verwendet die aktuellen Bezeichnungen inputValue/setInputValue und einen kontrollierten selectedValue.
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
Ein Prompt für dein Projekt
Agenten-Prompt
Verwende den bereitgestellten Referenzfinder für Ariakit 0.4.40 in React. Halte ComboboxProvider inputValue/setInputValue unabhängig von selectedValue/setSelectedValue, behalte native beschriftete Gruppen und die deaktivierte Option „Experimental grid“ bei und filtere die Daten, bevor Elemente gerendert werden. Bewahre den verifizierten Ablauf mit Abwärtstaste und anschließendem Enter bei deaktiviertem autoSelect und style data-active-item getrennt von der gespeicherten Zugehörigkeit. Füge die bestätigte Referenz einer duplikatfreien lokalen Leseliste hinzu und ermögliche das Entfernen, ohne die aktuelle Detailansicht zu verwerfen. Füge das vollständige Original-Stylesheet bei.
05
Quellen und Geltungsbereich des Ariakit-Designsystems
Ariakit React 0.4.40. Alle visuellen Tokens, Illustrationen und Beispielwerte für Referenzen sind eigens konfigurierte Angaben; es wird weder eine offizielle Ariakit-Palette noch eine offizielle Typografieskala beansprucht. Der Zustand der Leseliste wird lokal gespeichert.
