Una referencia de HeroUI v3 con variables CSS semánticas reales, controles compuestos de React, superficies claras y oscuras, y una receta funcional para exportar imágenes.
Guía de OpenDesign9 capítulos30 entradas de referenciaGuía de aplicación original
01
Vista previa de la interfaz de sistema de diseño HeroUI
Ajusta la calidad con un control deslizante nativo, activa o desactiva los metadatos, cambia la apariencia y aplica una receta local. No se simula ningún codificador ni carga.
CSS compilado con @heroui/react 3.2.6 y @heroui/styles 3.2.6 nativos; ilustración y diseño originales. · Referencia de implementación
02
Referencia de diseño de sistema de diseño HeroUI
Tema predeterminado de HeroUI 3.2.6, verificado con @heroui/styles/dist/themes/default/variables.css. Los valores OKLCH siguientes son valores literales del paquete. Los colores de la ilustración y la tipografía son decisiones de la aplicación, no tokens de marca de HeroUI.
componentes de React y una hoja de estilos semántica
Este ejemplo está pensado para HeroUI 3.2.6. Sus controles son componentes de React que incorporan el comportamiento de React Aria, mientras que la capa visual procede de @heroui/styles. La guía oficial de inicio rápido requiere React 19 y Tailwind CSS v4. La configuración de v3 no envuelve esta aplicación en el patrón anterior de HeroUIProvider. Mezclar tutoriales de v2 con este componente compuesto API suele provocar controles ausentes o con estilos incorrectos.
El ejemplo es un editor de ajustes de exportación: la ilustración está a la izquierda y los controles de calidad y metadatos, a la derecha. La ilustración está dibujada con CSS original. No es una imagen procesada por la biblioteca. Al aplicar un ajuste, la configuración seleccionada se guarda en el estado local React; deliberadamente, no se inventa el tamaño del archivo ni se simula una descarga.
Colores semánticos y apariencia del sistema de diseño de HeroUI
Diferenciar el lienzo, las superficies y las capas flotantes
Usa --background para el lienzo exterior, --surface para la ilustración y las tarjetas de configuración, y --overlay para un futuro cuadro emergente o diálogo. Son roles semánticos, aunque en el modo claro dos de ellos tengan el valor blanco. En el modo oscuro, el lienzo y las superficies elevadas se diferencian. El ejemplo activa la clase dark en document.documentElement para que todos sus descendientes compartan el mismo ámbito del tema.
El relleno del control deslizante y el interruptor seleccionado usan el rol de acento. Los controles de acento sólido lo combinan con --accent-foreground. El texto secundario usa --muted, en vez de reducir la opacidad de una tarjeta entera. La ilustración conserva su paleta cálida independiente en ambas apariencias porque es contenido, no parte de la interfaz interactiva.
Tipografía y espaciado del sistema de diseño de HeroUI
Especificar explícitamente la escala de la aplicación
Los estilos de HeroUI se integran con las utilidades de Tailwind, pero esta página no impone una única tipografía HeroUI. Su CSS original elige Arial/Helvetica, con texto de cuerpo de 16px e interlineado de 1.5. El encabezado de 32px pasa a 28px en la vista estrecha; el encabezado de configuración mide 24px. La tabla de referencia distingue estos valores de la aplicación de las variables del paquete.
La primitiva oficial --spacing equivale a 0.25rem. Esta composición usa 16px dentro del ajuste, 24px entre columnas y alrededor de las tarjetas de escritorio, y 32px alrededor del lienzo de escritorio. El radio del campo se basa en la primitiva oficial de radio de 8px. El radio de la tarjeta usa deliberadamente el triple de esa primitiva, por lo que el valor de 24px es una derivación de la aplicación, no un valor predeterminado de Card.
Crear un control deslizante completo en el sistema de diseño de HeroUI
Mantener juntos la estructura y el control del valor
La raíz Slider controla value, onChange, minValue, maxValue y step. Su Label proporciona el nombre accesible. Slider.Output lee el mismo valor, y Slider.Track contiene Slider.Fill y Slider.Thumb. Si se omiten estas partes visibles, el control puede funcionar sin mostrar la pista o el tirador esperados. Este ejemplo usa un solo número, no un arreglo de valores.
La calidad está limitada al intervalo de 10–100, en incrementos de cinco. Esos límites son decisiones propias del producto. HeroUI usa de forma predeterminada un intervalo de 0–100 con incrementos de uno. No existe una relación universal fiable entre el valor de calidad y los bytes, así que el texto de ayuda explica el equilibrio sin inventar una estimación del tamaño del archivo. Para admitir varios tiradores, usa un arreglo de números y asigna a cada tirador el índice correcto.
Enfoca el control deslizante de calidad y pulsa una tecla de flecha para cambiar un incremento.
Comprueba que el valor visible y el ajuste actual cambien a la vez.
Aplica el ajuste y, después, mueve el control deslizante para distinguir el borrador de la instantánea aplicada.
Crear una configuración booleana en el sistema de diseño de HeroUI
Un interruptor consta de partes de control y contenido
La configuración de metadatos usa isSelected y onChange en Switch. En la implementación instalada 3.2.6, Switch.Content envuelve Switch.Control y Label; Switch.Control contiene Switch.Thumb. Description se sitúa junto a Switch.Content como ayuda del campo. Esto se ajusta al código fuente instalado, cuya estructura SwitchField/SwitchButton difiere de la que aparece en algunos ejemplos anteriores de la documentación de v3. La descripción explica el significado del valor booleano en lugar de depender del color azul de la pista seleccionada. Un único estado de metadatos controla tanto el componente nativo como el texto del ajuste.
Mantén este valor booleano separado de la operación de aplicación. Al cambiar los metadatos se edita inmediatamente el borrador actual; al pulsar Aplicar a la vista previa se guarda una instantánea. Restablecer restaura la calidad a 80, elimina los metadatos y borra esa instantánea. No reutilices un indicador de estado guardado para representar un borrador distinto. Si se conectara a un codificador, pasa el objeto aplicado a ese proceso en vez de leer texto ambiguo del formulario.
Componer superficies adaptables en el sistema de diseño de HeroUI
La ilustración sigue siendo contenido, no un fondo decorativo detrás de los controles
En escritorio se usa una cuadrícula de 1.05fr/1fr para dar algo más de espacio a la ilustración sin restárselo a la legibilidad de la configuración. En el punto de quiebre original de 700px, la cuadrícula pasa a una sola columna, el encabezado se apila y la proporción de la ilustración cambia de 4:5 a 4:3. El pie de ilustración queda fuera de la imagen para mantener una superficie de lectura estable.
Todos los controles interactivos se encuentran en una superficie semántica sólida. Los botones se reorganizan en varias líneas cuando el espacio es limitado. La altura de la vista previa depende del contenido, no de una altura mínima basada en la ventana gráfica; esto es importante cuando el documento está integrado en un iframe cuyo tamaño se ajusta automáticamente. No hay ningún contenedor de desplazamiento de altura fija que oculte el formulario o su resultado.
Interacción, foco y resultados fiables en el sistema de diseño de HeroUI
Usar estados nativos en lugar de imitaciones visuales
Button usa onPress en lugar de un evento personalizado que solo responda al puntero. Slider admite la interacción mediante el teclado y anuncia los valores. Switch proporciona su estado booleano mediante la implementación nativa de accesibilidad. El diseño personalizado de CSS no elimina los estilos de foco. Para desactivar un componente, usa isDisabled en lugar de limitarte a reducir la opacidad; --disabled-opacity solo describe su apariencia.
El párrafo de estado tiene el rol status, por lo que se puede anunciar una instantánea aplicada sin mover el foco del teclado. La etiqueta del botón de apariencia oscura describe la siguiente acción. La ilustración tiene una etiqueta descriptiva de región y sus formas son decorativas. Esta demostración no promete que los datos persistan después de recargar la página.
La calidad es una opción numérica acotada cuyo valor se muestra.
Los metadatos son un valor booleano con etiqueta y texto explicativo.
Aplicar guarda una instantánea local; Restablecer la borra y restaura el borrador inicial.
Instalar el sistema de diseño HeroUI y reproducir el ejemplo
Elige una sola canalización de hojas de estilo
En una aplicación React con Vite, instala los paquetes HeroUI fijados y Tailwind CSS v4 con su complemento para Vite. En la hoja de estilo principal, importa primero tailwindcss y luego @heroui/styles; después, incluye el CSS de diseño original. Renderiza App con createRoot de React; esta composición no requiere un proveedor de v2. El bloque de configuración incluye el punto de entrada y la configuración de Vite; arriba están disponibles App y el CSS completos.
El ejemplo independiente descargable usa el heroui.min.css precompilado del paquete y un paquete de esbuild React, ambos insertados en línea. Así se evitan dependencias de CDN en la vista previa. El ejemplo muestra los mismos controles nativos, pero no indica que se deban importar en una misma aplicación de producción tanto los estilos HeroUI precompilados como los generados por Tailwind. Elige una sola canalización para evitar reglas duplicadas.
Amplía la receta del sistema de diseño HeroUI sin inventar un codificador
Deja claros los límites de las capacidades
Para añadir una conversión de imagen real, incorpora un campo de selección de archivos y un codificador real del navegador o del servidor; luego, vincula los estados pendiente, fallido y completado a ese proceso. Un Slider solo selecciona un valor; no comprime. El botón Aplicar no debe convertirse en Descargar hasta que exista un blob de salida real. Conserva la imagen original por separado para que los cambios repetidos en la receta no acumulen pérdidas por codificación.
Al aplicar un tema a la aplicación, sobrescribe juntos los pares semánticos y prueba tanto la apariencia clara como la oscura. Cambiar solo --accent y mantener un color de primer plano inadecuado puede reducir el contraste del botón. Para una personalización más compleja, usa las clases documentadas de los componentes y sus estados de datos, en lugar de reemplazar el campo accesible del componente por un div de apariencia similar.
Ejemplos de componentes del sistema de diseño HeroUI
Aplicación completa para recetas de exportación
Las partes compuestas de Slider heredan el estilo oficial. Una instantánea aplicada independiente permite distinguir el borrador del estado aplicado.
jsx
import React,{useState,useEffect} from 'react';
import {Button,Switch,Label,Description,Slider} from '@heroui/react';
import './style.css';
export default function App(){
const[quality,setQuality]=useState(80),[metadata,setMetadata]=useState(false),[dark,setDark]=useState(false),[saved,setSaved]=useState(null);
useEffect(()=>{document.documentElement.classList.toggle('dark',dark)},[dark]);
return <main className='export-app'><header><div><p className='eyebrow'>HeroUI · Export studio</p><h1>Make room for the image.</h1><p className='muted'>Inspect a local export recipe before handing it to an encoder.</p></div><Button variant='secondary' onPress={()=>setDark(!dark)}>{dark?'Light appearance':'Dark appearance'}</Button></header><div className='export-grid'><section className='art-panel' aria-label='Original CSS artwork preview'><div className='art'><div className='sun'/><div className='hill one'/><div className='hill two'/><span>FIELD NOTES<br/>COLLECTION 07</span></div><div className='art-caption'><strong>Morning in the dunes</strong><span>1600 × 1200 · sample composition</span></div></section><section className='settings'><p className='eyebrow'>WEBP PRESET</p><h2>Export settings</h2><p className='muted'>The controls update a recipe. They do not encode or upload an image.</p><Slider value={quality} onChange={setQuality} minValue={10} maxValue={100} step={5}><div className='slider-heading'><Label>Image quality</Label><Slider.Output/></div><Slider.Track><Slider.Fill/><Slider.Thumb/></Slider.Track></Slider><p className='helper'>Higher quality may preserve fine texture. File size depends on the source image and encoder.</p><Switch isSelected={metadata} onChange={setMetadata}><Switch.Content><Switch.Control><Switch.Thumb/></Switch.Control><Label>Keep metadata</Label></Switch.Content><Description>Include source metadata in the recipe.</Description></Switch><div className='recipe'><p className='eyebrow'>CURRENT RECIPE</p><code>format: webp<br/>quality: {quality}<br/>metadata: {metadata?'keep':'strip'}</code></div><div className='actions'><Button onPress={()=>setSaved({quality,metadata})}>Apply to preview</Button><Button variant='tertiary' onPress={()=>{setQuality(80);setMetadata(false);setSaved(null)}}>Reset</Button></div><p role='status' className='status'>{saved?`Preview recipe applied: quality ${saved.quality}, metadata ${saved.metadata?'kept':'stripped'}. No file was generated.`:'Adjust quality with the arrow keys, then apply the recipe.'}</p></section></div><footer>Native HeroUI 3.2.6 controls and official compiled styles. Artwork and page layout are original CSS.</footer></main>;
}
Switch.Control y Switch.Thumb son partes visibles obligatorias de la anatomía.
onPress aplica una receta; no afirma que se haya codificado una imagen.
CSS de diseño original
Las referencias a superficies y radios usan variables HeroUI; los colores de la ilustración, la escala tipográfica y el punto de ruptura son decisiones explícitas de la aplicación.
Carga este CSS después de la hoja de estilos oficial.
La clase dark de html cambia los valores semánticos de todo el documento.
04
Configuración de agente del sistema de diseño HeroUI
Punto de partida para la implementación
Vista previa nativa verificada con React 19 y HeroUI 3.2.6. App y el CSS de diseño proporcionados están completos. Esta configuración de Vite usa la canalización de importación documentada de Tailwind v4; el ejemplo sin conexión, en cambio, inserta en línea la hoja de estilos oficial precompilada.
jsx
// In a Vite React 19 project:
// npm install @heroui/[email protected] @heroui/[email protected] tailwindcss@^4 @tailwindcss/vite@^4
// vite.config.js
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({plugins:[react(),tailwindcss()]});
// globals.css: keep this import order
// @import "tailwindcss";
// @import "@heroui/styles";
// Paste the Original layout CSS after these imports.
// main.jsx
import React from 'react';
import {createRoot} from 'react-dom/client';
import './globals.css';
import App from './App.jsx';
createRoot(document.getElementById('root')).render(<App/>);
// App.jsx is the complete application above. Remove its './style.css'
// import when the same CSS is included in globals.css.
Una instrucción para tu proyecto
Instrucción para el agente
Usa App.jsx 3.2.6 de HeroUI, la hoja de estilos y la integración con Tailwind proporcionadas para crear el estudio de exportación de imágenes. Vincula el estado de calidad de Slider y el estado de metadatos de Switch al resumen de exportación; conserva Switch.Content, Control y Thumb junto con sus etiquetas. Los cambios en la calidad o los metadatos deben invalidar la instantánea guardada. El control de apariencia oscura debe cambiar la misma clase del documento que usa la hoja de estilos. Guarda una receta de exportación explícitamente local; no des a entender que se ha procesado o descargado un archivo de imagen.
05
Fuentes y alcance del sistema de diseño HeroUI
Referencia de HeroUI 3.2.6. Las variables oficiales se distinguen de la tipografía, la ilustración y el diseño originales. La vista previa nativa solo cambia ajustes guardados en memoria y no codifica imágenes.
