Système de composants sans interface · Nouvelle ressource
Système de design Headless UI.
Headless UI fournit des composants d’interaction React sans style prédéfini pour les boîtes de dialogue, les listes de sélection et les interrupteurs. Ce guide porte sur la composition de leur comportement natif en matière de focus, de sélection et de fenêtres contextuelles avec du CSS ordinaire, à partir d’un flux de partage de documents comme exemple fonctionnel.
Guide OpenDesign9 chapitres27 entrées de référenceGuide de l’application d’origine
01
Aperçu de l’interface du système de design Headless UI
Ouvrez la boîte de dialogue de partage, validez une adresse e-mail, choisissez une autorisation au clavier, ajoutez une invitation locale et activez ou désactivez le lien public.
@headlessui/react 2.2.10 natif avec React 19. Toutes les couleurs, la typographie, les espacements et la mise en page sont propres à cet exemple CSS ; ce ne sont pas des jetons officiels de Headless UI. · Référence de mise en œuvre
02
Référence de conception du système de design Headless UI
Headless UI ne possède aucune échelle officielle de jetons visuels. Chaque valeur numérique ou couleur ci-dessous appartient à cet exemple OpenDesign ; la documentation liée décrit les comportements et les API d’état. Version testée du package : @headlessui/react 2.2.10.
Système de design Headless UI : composer le comportement avant de styliser l’écran
Composer le comportement avant de styliser l’écran
Dialog, Listbox et Switch modélisent chacun une interaction différente. Dialog gère une tâche délimitée et le contexte de focus qui lui est associé ; Listbox représente un choix confirmé ; Switch représente un réglage booléen indépendant. Les combiner ne signifie pas fusionner leurs états : le brouillon d’invitation, l’autorisation choisie et le réglage du lien public restent distincts.
L’exemple utilise le composant API de React avec des importations directes, telles que DialogPanel et ListboxButton. Sa boîte de dialogue contient une liste de sélection : le positionnement et la fermeture du menu contextuel doivent donc fonctionner à l’intérieur d’une fenêtre déjà ouverte. Commencez par composer ces éléments avant d’ajouter le panneau du document et le récapitulatif des autorisations. Le CSS fourni présente un style complet pour ces éléments natifs.
Système de design Headless UI : anatomie de Dialog, Listbox et Switch
Délimiter intentionnellement les éléments superposés
DialogBackdrop est un élément frère du conteneur de positionnement fixe. DialogPanel est le panneau blanc délimité à l’intérieur de ce conteneur ; il ne remplit pas la fenêtre. DialogTitle nomme la tâche et Description explique ce qui se passe à la fermeture. Le champ de saisie natif comporte data-autofocus, et Headless UI gère le comportement du focus dans la boîte de dialogue.
Listbox sélectionne une valeur ; Switch modifie une valeur booléenne
ListboxButton affiche le rôle sélectionné. ListboxOptions utilise anchor="bottom" et une largeur basée sur --button-width, afin que le menu contextuel soit aligné sur son déclencheur. Chaque ListboxOption possède une valeur de chaîne stable. Les attributs natifs data-focus et data-selected contrôlent deux traitements visuels distincts de CSS.
Le Switch du lien public se trouve dans Field avec Label, plutôt que dans une pastille colorée sans libellé. Son état activé modifie le contrôle accessible et la phrase explicative visible. L’invitation locale est indépendante du réglage du lien public.
Système de design Headless UI : séparer sélection, fermeture et confirmation locale
Modèle d’état utilisé ici
À l’ouverture, un nouveau brouillon de destinataire est créé et le rôle Can view est sélectionné. Annuler, appuyer sur Échap ou cliquer à l’extérieur ferme la boîte de dialogue ; aucune de ces actions n’ajoute de destinataire. Lors de l’envoi, l’adresse e-mail est validée et toute adresse déjà présente est refusée ; l’invitation est ensuite ajoutée en mémoire et la boîte de dialogue se ferme. La confirmation précise qu’aucun e-mail n’a été envoyé.
La liste de sélection des autorisations modifie le rôle du brouillon, et non les autorisations d’un destinataire existant. L’état du lien public modifie une valeur booléenne distincte. On évite ainsi l’erreur fréquente qui consiste à traiter chaque fermeture comme un enregistrement des autorisations.
Saisie invalide : laissez la boîte de dialogue ouverte et associez l’erreur à l’adresse e-mail.
Destinataire en double : ne modifiez pas la liste des accès existante.
Invitation locale acceptée : mettez à jour la liste et signalez clairement le résultat, valable uniquement dans l’aperçu.
Système de design Headless UI : styliser la sélection et le positionnement au clavier séparément
Styliser la sélection et le positionnement au clavier séparément
ListboxOption expose data-focus et data-selected pour distinguer différentes situations. L’option active reçoit le traitement d’accentuation pâle, tandis que la permission sélectionnée est marquée d’une coche. Au clavier, il est ainsi possible de parcourir les options sans perdre de vue le choix déjà effectué.
La même distinction s’applique en dehors de la fenêtre contextuelle : le rôle d’erreur concerne le champ du destinataire invalide, tandis que l’apparence cochée de Switch correspond à l’accès par lien public. Limitez CSS à l’état du composant qu’il décrit. Un sélecteur trop général qui appliquerait la même couleur à tous les éléments actifs ou cochés masquerait ces différentes significations.
Rendre l’identité du document et les permissions lisibles — système de design Headless UI
Paramètres typographiques reproductibles
Le titre du document est en 28px avec une hauteur de ligne de 1.25, tandis que le titre de la boîte de dialogue est en 20px avec une hauteur de ligne de 1.3. Le texte courant est en 16px/1.5, dans la police système de la plateforme. Les libellés des champs et le texte d’aide sont en 14px. Ces valeurs exactes figurent dans style.css ; il n’est pas nécessaire de les déduire d’une capture d’écran.
Dans la liste des accès, le courriel utilise overflow-wrap:anywhere pour empêcher une adresse de forcer l’élargissement de sa colonne. La permission reste sur une ligne distincte. Dans la boîte de dialogue, le titre complet du document et la permission sélectionnée sont visibles au moment de l’ajout de l’invitation.
Positionnement complet de la fenêtre superposée et comportement adaptatif — système de design Headless UI CSS
La mise en page ne dépend pas d’un prérequis masqué
La feuille de style fournie comprend toute la fenêtre superposée : positionnement fixe avec inset, opacité de l’arrière-plan, z-index, largeur maximale, défilement vertical et marges intérieures. Sous 700px, les panneaux du document s’empilent et les marges intérieures de la boîte de dialogue diminuent. Aucune compilation Tailwind n’est requise.
Distinguez le conteneur de positionnement de DialogPanel. Le conteneur couvre la fenêtre disponible et ajoute une marge intérieure sur les bords ; le panneau fournit une surface de contenu aux dimensions limitées. Prévoyez une zone défilante pour les boîtes de dialogue au contenu long afin que le champ du destinataire, le choix de permission et les actions de fermeture restent accessibles sur les écrans étroits.
Utiliser le comportement natif des états et du focus — système de design Headless UI
Vérification au clavier
Ouvrez la boîte de dialogue et vérifiez que le focus est initialement placé sur le destinataire. Appuyez sur Tab pour atteindre le déclencheur de permission, puis utilisez les touches fléchées et Entrée pour choisir un rôle. Échap ferme la fenêtre contextuelle active ou la boîte de dialogue, selon le contexte de focus du composant natif. Après la fermeture de la boîte de dialogue, le focus doit revenir au déclencheur de partage.
Le champ de courriel utilise aria-invalid et aria-describedby pour afficher une erreur personnalisée. La coche d’une option est décorative, car Listbox fournit les indications de sélection. Le contrôle de lien public possède un libellé visible, et la phrase explicative reste affichée après son activation ou sa désactivation. La préférence de réduction des animations CSS supprime la transition décorative du curseur du commutateur.
Headless UI Utiliser un seul système de design pour générer React API de manière cohérente
Utiliser systématiquement une seule génération de React API
L’entrée React complète monte App, dont la feuille de style fournit la géométrie de la fenêtre superposée et les sélecteurs d’état. Dans l’exemple vérifié en version 2.2.10, DialogPanel, DialogBackdrop, ListboxButton et ListboxOptions sont importés directement. Les anciennes syntaxes des composants composés doivent être migrées délibérément, plutôt que mélangées à cette composition.
ListboxOptions utilise anchor="bottom" et la variable native --button-width pour aligner les options sur le déclencheur. Ces éléments font partie de l’intégration et ne sont pas de simples détails décoratifs : supprimer le conteneur de positionnement ou remplacer la largeur par une valeur fixe sans rapport peut casser une fenêtre contextuelle imbriquée, même si le champ fermé semble toujours correct.
Installez @headlessui/react dans le projet React.
Enregistrez App.jsx et style.css à partir des exemples, puis remplacez main.jsx comme indiqué.
Lancez le serveur de développement et testez la fermeture de la boîte de dialogue, le choix d’une permission et la gestion des courriels en double.
Examiner une interaction réelle de permission — système de design Headless UI
Critères d’acceptation
Pour effectuer une vérification utile, commencez par un document auquel un destinataire a déjà accès, plutôt que par une galerie de composants vide. Ajoutez une invitation valide avec la permission « Peut commenter », puis rouvrez la boîte de dialogue et essayez la même adresse. Vérifiez que la ligne existante est conservée et qu’un message d’erreur précis s’affiche pour le doublon. Activez le lien public et vérifiez son texte explicatif indépendant.
L’exemple illustre uniquement l’état local de l’interface. Il ne fournit ni recherche de destinataires ni service de partage. La connexion à un service réel nécessite un modèle de réponse avec états de chargement et d’erreur, ainsi qu’une politique explicite pour les changements de permission simultanés ; les primitives natives ne définissent pas les règles d’autorisation.
Exemples de composants du système de design Headless UI
App.jsx — composition native du partage
Dialog contrôlé complet, Listbox pour les permissions, Switch avec libellé et validation locale.
jsx
import React, { useState } from 'react';
import { Dialog, DialogBackdrop, DialogPanel, DialogTitle, Description, Listbox, ListboxButton, ListboxOptions, ListboxOption, Switch, Field, Label } from '@headlessui/react';
import './style.css';
const roles = ['Can view', 'Can comment', 'Can edit'];
export default function App() {
const [open,setOpen]=useState(false),[role,setRole]=useState(roles[0]),[publicLink,setPublicLink]=useState(false),[email,setEmail]=useState(''),[error,setError]=useState(''),[notice,setNotice]=useState('');
const [people,setPeople]=useState([{email:'[email protected]',role:'Can edit'}]);
const start=()=>{setEmail('');setError('');setRole(roles[0]);setOpen(true)};
const submit=e=>{e.preventDefault();if(!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)){setError('Enter a complete email address.');return;}if(people.some(p=>p.email===email)){setError('This person already appears in the access list.');return;}setPeople([...people,{email,role}]);setOpen(false);setNotice('Invitation added to this local example only. No email was sent.');};
return <main className='sharing-shell'>
<header><div><span className='eyebrow'>HEADLESS UI / CUSTOM SURFACE</span><h1>Quarterly brief</h1><p className='muted'>Research · Updated today</p></div><button className='primary' onClick={start}>Share document</button></header>
<div className='document-grid'><article className='paper'><span className='tag'>WORKING DOCUMENT</span><h2>Make the next decision clearer.</h2><p>Three research priorities for the coming quarter, shared with the people who need to review them.</p><div className='rule'/><h3>01 / Understand the handoff</h3><p>Compare where context is lost between research notes and the next product decision.</p><h3>02 / Review access deliberately</h3><p>Keep editing rights separate from the ability to read a document.</p></article>
<aside className='access'><h2>People with access</h2><p className='muted'>The list below is local demonstration state.</p>{people.map((p,i)=><div className='person' key={p.email}><span className='avatar'>{i===0?'AK':'+'}</span><div><strong>{p.email}</strong><small>{p.role}</small></div></div>)}<Field className='link-setting'><Label>Public link</Label><Switch checked={publicLink} onChange={setPublicLink} className='switch'><span /></Switch></Field><p className='link-detail'>{publicLink?'Anyone with the example link could view this document. This changes only the local preview.':'Restricted to the named people in this example.'}</p><p role='status' className='notice'>{notice}</p></aside></div>
<Dialog open={open} onClose={()=>setOpen(false)} className='dialog-root'><DialogBackdrop className='backdrop'/><div className='dialog-position'><DialogPanel className='dialog-panel'><DialogTitle as='h2'>Share quarterly brief</DialogTitle><Description className='muted'>Choose one recipient and a permission. Closing discards this invitation draft.</Description><form noValidate onSubmit={submit}><label className='field-label' htmlFor='recipient'>Recipient email</label><input id='recipient' data-autofocus type='email' value={email} onChange={e=>{setEmail(e.target.value);setError('')}} aria-invalid={!!error} aria-describedby={error?'email-error':undefined} placeholder='[email protected]'/>{error&&<p id='email-error' role='alert' className='error'>{error}</p>}<Listbox value={role} onChange={setRole}><Label className='field-label'>Permission</Label><ListboxButton className='role-button'>{role}<span aria-hidden='true'>⌄</span></ListboxButton><ListboxOptions anchor='bottom' className='role-options'>{roles.map(value=><ListboxOption key={value} value={value} className='role-option'><span>{value}</span><span className='selected' aria-hidden='true'>✓</span></ListboxOption>)}</ListboxOptions></Listbox><p className='muted permission-help'>{role==='Can edit'?'May change document content in this example.':role==='Can comment'?'May add comments without editing content.':'May read the document without changing it.'}</p><div className='dialog-actions'><button type='button' onClick={()=>setOpen(false)}>Cancel</button><button className='primary' type='submit'>Add invitation</button></div></form></DialogPanel></div></Dialog>
<footer>Native Dialog, Listbox, and Switch behavior. Original CSS below supplies all visual values; Headless UI does not ship this palette.</footer>
</main>;
}
Échap et Annuler abandonnent l’invitation non enregistrée.
style.css — système visuel original complet
Tous les jetons visuels, sélecteurs d’état, règles de positionnement de la fenêtre superposée et règles adaptatives nécessaires à App.jsx. Il s’agit de choix propres à l’exemple, et non des valeurs par défaut officielles de Headless UI.
Configuration de l’agent IA pour système de design Headless UI
Point de départ de l’implémentation
Les fichiers complets des styles et des composants sont fournis ci-dessus. Nécessite la version de Node prise en charge par la version de Vite sélectionnée. La démo intègre localement le même paquet de composants natifs.
texte
# Terminal
npm create vite@latest sharing-demo -- --template react
cd sharing-demo
npm install
npm install @headlessui/[email protected]
# Save the complete examples as src/App.jsx and src/style.css.
# Replace src/main.jsx with:
import React from 'react';
import {createRoot} from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')).render(<App/>);
# Terminal
npm run dev
Un prompt pour votre projet
Prompt pour l’agent IA
Utilisez App.jsx et style.css de Headless UI. Conservez la composition native de Dialog, Listbox et Switch, séparez les permissions provisoires des accès confirmés et préservez tous les sélecteurs de focus et d’état sélectionné. Remplacez l’ajout local d’invitations par notre API autorisé, avec des états de chargement et d’échec ; n’enregistrez jamais les changements dans onClose. Ne présentez pas la palette personnalisée CSS comme un thème officiel de Headless UI.
05
Sources et périmètre du système de design Headless UI
Configuration visuelle originale de OpenDesign et exemple React utilisant le comportement natif de Headless UI 2.2.10. Les valeurs de CSS sont explicitement des choix propres à l’application ; Headless UI ne fournit pas ce thème. Les invitations et les changements de permission n’existent que dans la mémoire locale de l’aperçu.
