Uma referência de HeroUI v3 com variáveis CSS semânticas reais, controles compostos de React, superfícies claras e escuras e um procedimento funcional de exportação de imagens.
Guia OpenDesign9 capítulos30 entradas de referênciaGuia de aplicação original
01
Prévia da interface do sistema de design HeroUI
Altere a qualidade com um slider nativo, ative ou desative os metadados, mude a aparência e aplique uma receita local. Nenhum codificador nem envio é simulado.
CSS compilado com @heroui/react 3.2.6 e @heroui/styles 3.2.6 nativos; arte e layout originais. · Referência de implementação
02
Referência de design do sistema de design HeroUI
Tema padrão HeroUI 3.2.6, verificado em @heroui/styles/dist/themes/default/variables.css. Os valores OKLCH abaixo são os valores literais do pacote. As cores da arte e a tipografia são escolhas do aplicativo, não tokens de marca HeroUI.
React componentes e uma folha de estilos semântica
Este exemplo usa HeroUI 3.2.6. Seus controles são componentes React com comportamento Aria fornecido por React, enquanto a camada visual vem de @heroui/styles. O início rápido oficial requer React 19 e Tailwind CSS v4. A configuração da v3 não envolve este aplicativo no padrão mais antigo de HeroUIProvider. Misturar tutoriais da v2 com este API de componente composto é uma causa prática de controles ausentes ou estilizados incorretamente.
O exemplo é um editor de receitas de exportação: a arte fica à esquerda, e os controles de qualidade e metadados, à direita. A ilustração foi desenhada com CSS original. Ela não é uma imagem processada pela biblioteca. Ao aplicar uma receita, as configurações selecionadas são registradas no estado local de React; não há um tamanho de arquivo ou resultado de download inventado.
HeroUI Cores semânticas e aparência do sistema de design
Separe a tela de fundo, as superfícies e as camadas flutuantes
Use --background para a tela de fundo externa, --surface para a arte e os cartões de configurações e --overlay para um futuro popover ou diálogo. Essas são funções semânticas, mesmo quando duas delas resultam em branco no modo claro. No modo escuro, a tela de fundo e as superfícies elevadas têm cores diferentes. O exemplo alterna a classe dark em document.documentElement para que todos os elementos descendentes compartilhem o mesmo escopo de tema.
O preenchimento do controle deslizante e a opção selecionada do switch usam a função de destaque. Os controles de destaque sólido combinam essa função com --accent-foreground. O texto secundário usa --muted, em vez de reduzir a opacidade do cartão inteiro. A arte mantém sua paleta quente própria nos dois modos de aparência porque é conteúdo, não um elemento de interface interativo.
HeroUI Tipografia e espaçamento do sistema de design
Defina explicitamente a escala do aplicativo
A estilização de HeroUI se integra aos utilitários do Tailwind, mas esta página não determina uma única família tipográfica obrigatória para HeroUI. Seu CSS original escolhe Arial/Helvetica, com corpo de 16px e entrelinha de 1.5. O título de 32px passa a 28px no layout estreito; o título das configurações tem 24px. A tabela de referência distingue esses valores do aplicativo das variáveis do pacote.
A primitiva oficial --spacing é 0.25rem. Esta composição usa 16px dentro da receita, 24px entre colunas e ao redor dos cartões no desktop, e 32px ao redor da tela de fundo no desktop. O raio dos campos deriva da primitiva oficial de raio de 8px. O raio dos cartões usa deliberadamente três vezes essa primitiva; portanto, o valor de 24px é uma derivação do aplicativo, não um valor padrão declarado para Card.
Sistema de design HeroUI Crie um controle deslizante completo
Mantenha a estrutura e a propriedade do valor juntas
A raiz Slider controla value, onChange, minValue, maxValue e step. Seu Label fornece o nome acessível. Slider.Output lê o mesmo valor, e Slider.Track contém Slider.Fill e Slider.Thumb. Omitir essas partes visíveis pode manter o comportamento, mas deixar de exibir a trilha ou o indicador esperados. Este exemplo usa um único número, não um array de intervalo.
A qualidade fica entre 10 e 100, em incrementos de cinco. Esses limites são decisões locais do produto. Por padrão, o próprio HeroUI usa um intervalo de 0 a 100, com passo de um. Um valor de qualidade não tem uma relação universal confiável com a quantidade de bytes; por isso, o texto auxiliar explica essa troca sem inventar uma estimativa do tamanho do arquivo. Para dar suporte a vários indicadores, use um array de números e atribua o índice correto a cada indicador.
Foque o controle deslizante de qualidade e use uma tecla de seta para alterar um passo.
Confira se o valor exibido e a receita atual mudam juntos.
Aplique a receita e mova o controle deslizante novamente para diferenciar o rascunho do estado aplicado.
Sistema de design HeroUI Crie uma configuração booleana
Um switch tem partes de controle e conteúdo
A configuração de metadados usa isSelected e onChange no Switch. Na implementação 3.2.6 instalada, Switch.Content envolve Switch.Control e Label; Switch.Control contém Switch.Thumb. Description fica ao lado de Switch.Content como ajuda do campo. Isso segue o código-fonte instalado, cuja estrutura SwitchField/SwitchButton difere de alguns exemplos da documentação anterior da v3. A descrição explica o significado do valor booleano, em vez de depender da trilha azul quando selecionada. Um único estado de metadados controla tanto o controle nativo quanto o texto da receita.
Mantenha esse valor booleano separado da operação de aplicação. Alternar os metadados edita o rascunho atual imediatamente; clicar em Aplicar à pré-visualização registra um estado. Redefinir restaura a qualidade para 80, remove os metadados e limpa esse estado. Nenhum indicador de estado salvo é reutilizado para outro rascunho. Se isso estivesse conectado a um codificador, o objeto aplicado deveria ser passado a esse processo, em vez de ler texto ambíguo do formulário.
Sistema de design HeroUI Componha superfícies responsivas
A arte continua sendo conteúdo, não decoração atrás dos controles
No desktop, usa-se uma grade de 1.05fr/1fr para dar um pouco mais de espaço à arte sem comprometer a legibilidade das configurações. No breakpoint original de 700px, a grade passa a ter uma única coluna, o cabeçalho é empilhado e a proporção da arte muda de 4:5 para 4:3. A legenda fica fora da arte para manter uma área de leitura estável.
Todos os controles interativos ficam em uma superfície semântica sólida. Os botões se reorganizam em várias linhas quando o espaço é limitado. A altura da pré-visualização é determinada pelo conteúdo, não por uma altura mínima relativa à janela de visualização; isso é importante quando o documento é incorporado a um iframe com dimensionamento automático. Nenhuma caixa de rolagem com altura fixa oculta o formulário ou o resultado.
Sistema de design HeroUI Interação, foco e resultados confiáveis
Use estados nativos em vez de substitutos visuais
Button usa onPress, não um evento personalizado acionado apenas pelo ponteiro. Slider permite interação pelo teclado e anuncia os valores. Switch fornece seu estado booleano por meio da implementação nativa de acessibilidade. O layout personalizado de CSS não remove o estilo de foco. Para desativar o comportamento de um componente, use isDisabled, em vez de apenas reduzir a opacidade; --disabled-opacity descreve somente a aparência.
O parágrafo de status tem role=status, permitindo anunciar um resumo aplicado sem mover o foco do teclado. O rótulo do botão de aparência escura muda para descrever a próxima ação. A arte tem um rótulo descritivo de região, e suas formas permanecem decorativas. Esta demonstração não promete persistência após recarregar a página.
A qualidade é uma opção numérica limitada, com um resultado visível.
Os metadados são um valor booleano, com rótulo e texto explicativo.
Aplicar salva um resumo local; Redefinir o limpa e restaura o rascunho inicial.
HeroUI Instalação do sistema de design e reprodução do exemplo
Escolha um único fluxo de estilos
Em uma aplicação Vite React, instale os pacotes fixados HeroUI e o Tailwind CSS v4 com o plug-in do Vite. Na folha de estilos principal, importe primeiro tailwindcss e depois @heroui/styles; em seguida, inclua o layout CSS original. Renderize App com React createRoot; essa composição não exige o provider v2. O bloco de configuração apresenta a entrada e a configuração do Vite, e o App completo e o CSS estão disponíveis acima.
O exemplo independente para download usa o heroui.min.css pré-compilado do pacote e um bundle React do esbuild, ambos incorporados. Isso evita dependências de CDN na prévia. Ele demonstra os mesmos controles nativos, mas não recomenda importar estilos HeroUI compilados e gerados pelo Tailwind no mesmo aplicativo de produção. Escolha um único fluxo para evitar regras duplicadas.
Sistema de design HeroUI: amplie a receita sem inventar um codificador
Deixe claros os limites dos recursos
Para adicionar uma conversão de imagem real, inclua um campo de entrada de arquivo e um codificador real, no navegador ou no servidor; em seguida, conecte os estados pendente, com falha e concluído a esse processo. Um Slider apenas seleciona um valor; não oferece compressão. O botão Aplicar não deve se tornar um botão Baixar até que exista um blob de saída real. Preserve a imagem original separadamente para que alterações repetidas na receita não acumulem perdas de codificação.
Ao aplicar um tema ao aplicativo, substitua os pares semânticos em conjunto e teste as aparências clara e escura. Alterar apenas --accent e manter uma cor de primeiro plano inadequada pode comprometer o contraste do botão. Para personalizações mais elaboradas, use classes de componentes e estados de dados documentados, em vez de substituir a entrada acessível do componente por uma div visualmente semelhante.
HeroUI Exemplos de componentes do sistema de design
Aplicativo completo de receita de exportação
As partes compostas do Slider e do Switch herdam o estilo oficial. Um resumo aplicado separado deixa visível a diferença entre o estado de rascunho e o 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 e Switch.Thumb são partes visíveis obrigatórias da estrutura.
onPress aplica uma receita; não afirma que uma imagem foi codificada.
Layout CSS original
As referências de superfície e raio usam variáveis HeroUI; as cores da arte, a escala tipográfica e o ponto de interrupção são decisões explícitas do aplicativo.
Carregue este CSS depois da folha de estilos oficial.
A classe dark de html altera os valores semânticos do documento inteiro.
04
Configuração do agente do sistema de design HeroUI
Ponto de partida para implementação
A prévia nativa foi verificada com React 19 e HeroUI 3.2.6. O App e o layout CSS fornecidos estão completos. Esta configuração do Vite usa o fluxo de importação documentado do Tailwind v4; o exemplo offline, por sua vez, incorpora a folha de estilos pré-compilada oficial.
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.
Um prompt para seu projeto
Prompt para agente de IA
Use o App.jsx HeroUI 3.2.6, a folha de estilos e a integração com o Tailwind fornecidos para criar o estúdio de exportação de imagens. Mantenha os estados de qualidade do Slider e de metadados do Switch conectados ao resumo de exportação; preserve Switch.Content, Control e Thumb com seus rótulos. Alterar a qualidade ou os metadados deve invalidar o resumo salvo. O controle de aparência escura deve alterar a mesma classe do documento usada pela folha de estilos. Salve uma receita de exportação explicitamente local; não dê a entender que um arquivo de imagem foi processado ou baixado.
05
HeroUI Fontes e escopo do sistema de design
Referência HeroUI 3.2.6. As variáveis oficiais são diferenciadas da tipografia, da arte e do layout originais. A prévia nativa altera apenas configurações mantidas na memória e não codifica imagens.
