Sistema de componentes sin estilos · Nuevo recurso
Sistema de diseño Headless UI.
Headless UI proporciona componentes de interacción React sin estilos para diálogos, listas desplegables y conmutadores. Esta guía se centra en combinar su comportamiento nativo de enfoque, selección y ventanas emergentes con CSS convencional, usando como ejemplo práctico un flujo para compartir documentos.
Guía de OpenDesign9 capítulos27 entradas de referenciaGuía de aplicación original
01
Vista previa de la interfaz del sistema de diseño Headless UI
Abre el diálogo para compartir, valida un correo electrónico, elige un permiso con el teclado, añade una invitación local y cambia el estado del enlace público.
@headlessui/react 2.2.10 nativo con React 19. Todos los colores, la tipografía, el espaciado y la composición son CSS originales de ejemplo, no tokens oficiales de Headless UI. · Referencia de implementación
02
Referencia de diseño del sistema de diseño Headless UI
Headless UI no tiene una escala oficial de tokens visuales. Todos los valores numéricos o de color que aparecen a continuación pertenecen a este ejemplo de OpenDesign; la documentación enlazada proporciona las API de comportamiento y estado. Paquete probado: @headlessui/react 2.2.10.
Sistema de diseño Headless UI: compón el comportamiento antes de dar estilo a la pantalla
Compón el comportamiento antes de dar estilo a la pantalla
Dialog, Listbox y Switch modelan interacciones distintas. Dialog controla una tarea delimitada y su contexto de foco; Listbox representa una elección confirmada; Switch representa un ajuste booleano independiente. Combinarlos no exige unificar su estado: el borrador de la invitación, el permiso seleccionado y el ajuste del enlace público siguen siendo independientes.
El ejemplo usa el componente React API mediante importaciones directas, como DialogPanel y ListboxButton. El diálogo contiene una lista de opciones, por lo que el posicionamiento de la ventana emergente y su cierre deben funcionar dentro de una superposición existente. Empieza con esa composición antes de añadir el panel del documento y el resumen de acceso a su alrededor. El CSS proporcionado muestra una apariencia completa para estas partes nativas.
Anatomía de Dialog, Listbox y Switch del sistema de diseño Headless UI
Delimita la superposición intencionadamente
DialogBackdrop es un elemento hermano del contenedor de posicionamiento fijo. DialogPanel es el panel blanco delimitado dentro de ese contenedor; no ocupa toda la ventana. DialogTitle nombra la tarea y Description explica qué ocurre al cerrar. El campo de entrada nativo tiene data-autofocus y Headless UI gestiona el comportamiento del foco en el diálogo.
Un cuadro de lista selecciona un valor; un interruptor cambia un valor booleano
ListboxButton muestra el rol seleccionado. ListboxOptions usa anchor="bottom" y un ancho basado en --button-width, para que la ventana emergente se alinee con el activador. Cada ListboxOption tiene un valor de cadena estable. Los atributos nativos data-focus y data-selected aplican dos tratamientos CSS distintos.
El Switch del enlace público está dentro de Field con Label, en lugar de presentarse como una pastilla visual sin etiqueta. Su estado activado cambia el control accesible y la frase explicativa visible. La invitación local es independiente del ajuste del enlace público.
Sistema de diseño Headless UI: separa la selección, el cierre y la confirmación local
El modelo de estado utilizado aquí
Al abrirlo, se inicializa un nuevo borrador del destinatario y se selecciona el rol Puede ver. Cancelar, pulsar Escape y hacer clic fuera cierran el diálogo; ninguna de estas acciones añade un destinatario. Al enviar, se valida el correo electrónico y se rechaza si la dirección ya existe. Después, se añade una invitación a la memoria y se cierra el diálogo. La confirmación indica explícitamente que no se ha enviado ningún correo.
El cuadro de lista de permisos cambia el rol del borrador, no el acceso de los destinatarios existentes. El estado del enlace público modifica un booleano independiente. Así se evita el error habitual de tratar cada evento de cierre como si guardara los permisos.
Entrada no válida: mantén abierto el diálogo y asocia el error al correo electrónico.
Destinatario duplicado: no modifiques la lista de accesos existente.
Invitación local aceptada: actualiza la lista y anuncia que el resultado es solo una vista previa.
Sistema de diseño Headless UI: aplica estilos por separado a la selección y a la posición del foco del teclado
Aplica estilos por separado a la selección y a la posición del foco del teclado
ListboxOption expone data-focus y data-selected para condiciones distintas. La opción enfocada recibe un tratamiento de acento pálido, mientras que el permiso confirmado se indica con una marca de verificación. Así, quienes usan el teclado pueden recorrer las alternativas sin perder de vista la opción elegida.
La misma distinción se aplica fuera de la ventana emergente: el rol del error corresponde al campo del destinatario no válido, mientras que el aspecto activado de Switch corresponde al acceso mediante enlace público. Limita CSS al estado del componente que describe. Un selector general que aplicara el mismo color a todos los elementos enfocados o activados ocultaría estos significados distintos.
Sistema de diseño Headless UI: facilita la lectura de la identidad del documento y los permisos
Ajustes tipográficos reproducibles
El título del documento mide 28px y tiene una altura de línea de 1.25; el título del diálogo mide 20px y tiene una altura de línea de 1.3. El texto del cuerpo usa 16px/1.5 y la fuente del sistema de la plataforma. Las etiquetas de campo y el texto de ayuda miden 14px. Estos valores exactos están en style.css; no hace falta deducirlos a partir de una captura de pantalla.
El correo electrónico de la lista de accesos usa overflow-wrap:anywhere para evitar que una dirección ensanche su columna. El permiso aparece en una línea aparte. Dentro del diálogo, el título completo del documento y el permiso seleccionado se ven cuando se añade la invitación.
Posicionamiento completo de la superposición y diseño adaptativo CSS del sistema de diseño Headless UI
La composición no está oculta en un requisito previo
La hoja de estilos proporcionada incluye toda la superposición: posicionamiento fijo con inset, opacidad del fondo, z-index, ancho máximo, desplazamiento vertical y relleno. Por debajo de 700px, los paneles del documento se apilan y el diálogo reduce su relleno. No se presupone una compilación de Tailwind.
Mantén el contenedor de posicionamiento separado de DialogPanel. El contenedor cubre la ventana gráfica disponible y proporciona espacio en los bordes; el panel proporciona la superficie de contenido acotada. Si el contenido del diálogo es extenso, añade una región desplazable para que el campo del destinatario, la opción de permiso y las acciones para cerrarlo sigan siendo accesibles en pantallas estrechas.
Headless UI Usa el comportamiento nativo de estado y foco del sistema de diseño
Verificación con el teclado
Abre el diálogo y verifica que el foco inicial esté en el destinatario. Usa Tab para llegar al activador de permisos; usa las flechas y Enter para elegir un rol. Escape cierra la ventana emergente o el diálogo activo según el contexto de foco actual del componente nativo. Al cerrar el diálogo, el foco debe volver al activador para compartir.
El correo electrónico usa aria-invalid y aria-describedby para su error personalizado. La marca de verificación de una opción es decorativa, ya que Listbox proporciona la semántica de selección. El control de enlace público tiene una etiqueta visible y la oración explicativa permanece después de activarlo o desactivarlo. El ajuste de movimiento reducido CSS elimina la transición decorativa del pulgar del interruptor.
Headless UI Usa de forma coherente una sola generación del sistema de diseño React API
Usa de forma coherente una sola generación de React API
La entrada completa de React monta App, cuya hoja de estilos proporciona la geometría de la superposición y los selectores de estado. DialogPanel, DialogBackdrop, ListboxButton y ListboxOptions se importan directamente en el ejemplo verificado de la versión 2.2.10. Las formas compuestas más antiguas deben migrarse de forma deliberada, en lugar de mezclarse con esta composición.
ListboxOptions usa anchor="bottom" y la variable nativa --button-width para alinear las opciones con el activador. Estos detalles forman parte de la integración, no son adornos opcionales: eliminar el contenedor de posicionamiento o sustituir el ancho por un valor fijo sin relación puede romper una ventana emergente anidada, aunque el campo cerrado siga teniendo el aspecto correcto.
Instala @headlessui/react en el proyecto React.
Guarda App.jsx y style.css de los ejemplos y luego sustituye main.jsx como se muestra.
Inicia el servidor de desarrollo y prueba el cierre del diálogo, la selección de permisos y la recuperación ante correos electrónicos duplicados.
Headless UI Inspecciona una interacción de permisos real del sistema de diseño
Criterios de aceptación
Una revisión útil parte de un documento y de un destinatario existente, no de una galería de componentes vacía. Añade una invitación válida con permiso Puede comentar, vuelve a abrirla e intenta usar el mismo correo electrónico. Confirma que se conserva la fila original y que el duplicado genera un error específico. Activa el enlace público y revisa su explicación independiente.
El ejemplo solo demuestra el estado local de la interfaz. No incluye búsqueda de destinatarios ni un backend para compartir. Conectar un servicio real requiere un modelo de respuestas pendientes y de error, así como una política explícita para los cambios simultáneos de permisos; las primitivas nativas no determinan las reglas de autorización.
Headless UI Ejemplos de componentes del sistema de diseño
App.jsx — composición nativa para compartir
Diálogo controlado completo, Listbox de permisos, Switch con etiqueta y validación local.
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>;
}
No se envía ningún correo electrónico ni solicitud.
Escape y Cancelar descartan la invitación sin guardar.
style.css — sistema visual original completo
Todos los tokens visuales, selectores de estado, ubicación de la superposición y reglas adaptables necesarios para App.jsx. Son opciones del ejemplo, no valores predeterminados oficiales de Headless UI.
Headless UI Configuración del agente del sistema de diseño
Punto de partida para la implementación
Los archivos completos de estilos y componentes se proporcionan arriba. Se requiere una versión de Node compatible con la versión de Vite seleccionada. La demostración incluye localmente el mismo paquete de componentes nativos.
Texto
# 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
Una instrucción para tu proyecto
Instrucción para el agente
Usa App.jsx y style.css de Headless UI proporcionados. Conserva la composición nativa de Dialog, Listbox y Switch, separa los permisos en borrador del acceso confirmado y mantén todos los selectores de foco y estado seleccionado. Sustituye la incorporación local de invitaciones por nuestra API autorizada, incluidos los estados pendiente y fallido; nunca guardes al ejecutar onClose. No presentes la paleta personalizada de CSS como un tema oficial de Headless UI.
05
Headless UI Fuentes y alcance del sistema de diseño
Configuración visual original de OpenDesign y ejemplo de React con el comportamiento nativo de Headless UI 2.2.10. Los valores de CSS son explícitamente opciones de la aplicación; Headless UI no proporciona este tema. Las invitaciones y los cambios de permisos solo existen en la memoria de la vista previa local.
