Eine Referenz zu HeroUI v3 mit echten semantischen CSS-Variablen, zusammengesetzten React-Steuerelementen, hellen und dunklen Oberflächen sowie einem funktionierenden Rezept für den Bildexport.
Qualität mit einem nativen Schieberegler ändern, Metadaten umschalten, Erscheinungsbild wechseln und ein lokales Rezept anwenden. Es wird weder ein Encoder noch ein Upload simuliert.
Natives @heroui/react 3.2.6 und @heroui/styles 3.2.6, kompiliertes CSS; Originalgrafik und -layout. · Implementierungsreferenz
02
Designreferenz für das HeroUI-Designsystem
Standarddesign von HeroUI 3.2.6, geprüft anhand von @heroui/styles/dist/themes/default/variables.css. Die folgenden OKLCH-Werte entsprechen den wörtlichen Paketwerten. Grafikfarben und Typografie sind Anwendungsentscheidungen, keine Marken-Design-Tokens von HeroUI.
Dieses Beispiel ist auf HeroUI 3.2.6 ausgelegt. Die Steuerelemente sind React-Komponenten mit React-Aria-Verhalten; die visuelle Ebene stammt von @heroui/styles. Die offizielle Schnellstartanleitung setzt React 19 und Tailwind CSS v4 voraus. Beim v3-Setup wird diese Anwendung nicht in das ältere HeroUIProvider-Muster eingebettet. Die Mischung von v2-Tutorials mit diesem zusammengesetzten Komponenten-API ist eine häufige Ursache für fehlende oder falsch formatierte Steuerelemente.
Das Beispiel zeigt einen Editor für Exportrezepte: links die Grafik, rechts die Qualitäts- und Metadatensteuerelemente. Die Illustration wurde mit originalem CSS gezeichnet. Es handelt sich nicht um ein von der Bibliothek verarbeitetes Bild. Beim Anwenden eines Rezepts werden die ausgewählten Einstellungen im lokalen Zustand von React gespeichert; eine Dateigröße oder ein Download-Ergebnis wird bewusst nicht vorgetäuscht.
Semantische Farben und Erscheinungsbild des HeroUI-Designsystems
Hintergrund, Oberflächen und schwebende Ebenen voneinander unterscheiden
Verwende --background für den äußeren Hintergrund, --surface für die Karten mit Grafik und Einstellungen und --overlay für ein späteres Popover oder Dialogfeld. Dies sind semantische Rollen, auch wenn zwei davon im hellen Modus weiß ergeben. Im dunklen Modus unterscheiden sich der Hintergrund und die erhöhten Oberflächen. Das Beispiel schaltet die dunkle Klasse auf document.documentElement um, sodass alle Nachfahren denselben Geltungsbereich des Designs verwenden.
Die Füllung des Schiebereglers und der ausgewählte Schalter verwenden die Akzentrolle. Ausgefüllte Akzent-Steuerelemente kombinieren sie mit --accent-foreground. Sekundärtext verwendet --muted, statt die Deckkraft einer ganzen Karte zu verringern. Die Grafik behält in beiden Darstellungen ihre eigenständige warme Palette, da sie Inhalt und keine interaktive Oberfläche ist.
Die Gestaltung mit HeroUI lässt sich in Tailwind-Utilities integrieren, aber diese Seite schreibt keine bestimmte Schriftart für HeroUI vor. Das ursprüngliche CSS verwendet Arial/Helvetica mit 16px Fließtext und einem Zeilenabstand von 1.5. Eine Überschrift mit 32px wird im schmalen Layout auf 28px verkleinert; die Überschrift der Einstellungen hat 24px. Die Referenztabelle unterscheidet diese Anwendungswerte von den Paketvariablen.
Das offizielle Primitiv --spacing hat den Wert 0.25rem. Diese Komposition verwendet 16px innerhalb des Rezepts, 24px zwischen den Spalten und um die Desktop-Karten sowie 32px um den Desktop-Hintergrund. Der Feldradius leitet sich vom offiziellen Radius-Primitiv mit 8px ab. Der Kartenradius beträgt bewusst das Dreifache dieses Primitivs. Der Wert von 24px ist daher eine Ableitung für diese Anwendung und kein behaupteter Standardwert der Card-Komponente.
Vollständigen Schieberegler im HeroUI-Designsystem erstellen
Aufbau und Zuständigkeit für den Wert gemeinsam betrachten
Das Slider-Root verwaltet value, onChange, minValue, maxValue und step. Sein Label stellt den zugänglichen Namen bereit. Slider.Output liest denselben Wert; Slider.Track enthält Slider.Fill und Slider.Thumb. Fehlen diese sichtbaren Teile, kann das Verhalten bestehen bleiben, während die erwartete Schiene oder der Griff fehlt. Dieses Beispiel verwendet eine einzelne Zahl statt eines Wertebereichs als Array.
Die Qualität ist auf 10–100 begrenzt und wird in Fünferschritten angepasst. Diese Grenzen sind lokale Produktentscheidungen. HeroUI selbst verwendet standardmäßig den Bereich 0–100 mit Schrittweite eins. Ein Qualitätswert lässt sich nicht zuverlässig und allgemeingültig in Bytes umrechnen. Der Hilfetext erläutert daher den Kompromiss, ohne eine Dateigröße zu schätzen. Für mehrere Griffe verwendest du ein Zahlenarray und gibst jedem Griff den passenden Index.
Fokussiere den Qualitätsregler und passe ihn mit einer Pfeiltaste um einen Schritt an.
Prüfe, ob sich die sichtbare Ausgabe und das aktuelle Rezept gemeinsam ändern.
Wende das Rezept an und bewege anschließend den Schieberegler erneut, um den Entwurf vom übernommenen Schnappschuss zu unterscheiden.
Boolesche Einstellung im HeroUI-Designsystem zusammenstellen
Ein Schalter besteht aus Steuerungs- und Inhaltsteilen.
Die Metadateneinstellung verwendet isSelected und onChange auf Switch. In der installierten Implementierung 3.2.6 umschließt Switch.Content Switch.Control und Label. Switch.Control enthält Switch.Thumb. Description steht neben Switch.Content als feldbezogener Hilfetext. Das entspricht dem installierten Quellcode, dessen SwitchField-/SwitchButton-Aufbau sich von einigen früheren Beispielen in der v3-Dokumentation unterscheidet. Die Beschreibung erläutert die Bedeutung des booleschen Werts, statt sich auf den blau markierten ausgewählten Zustand zu verlassen. Ein einzelner Metadatenstatus steuert sowohl das native Steuerelement als auch die Textdarstellung der Recipe.
Halte diesen booleschen Wert getrennt vom Anwenden. Beim Umschalten der Metadaten wird der aktuelle Entwurf sofort bearbeitet; durch Klicken auf „Auf Vorschau anwenden“ wird ein Snapshot gespeichert. Zurücksetzen stellt die Qualität 80 wieder her, entfernt die Metadaten und löscht diesen Snapshot. Eine Statusanzeige für gespeicherte Daten wird nicht für einen anderen Entwurf wiederverwendet. Bei einer Anbindung an einen Encoder übergib das angewendete Objekt an diesen Prozess, statt mehrdeutige Formulartexte auszulesen.
Das Artwork bleibt Inhalt und ist keine Dekoration hinter Steuerelementen
Auf dem Desktop wird ein 1.05fr/1fr-Raster verwendet. So erhält das Artwork etwas mehr Platz, während die Einstellungen gut lesbar bleiben. Am ursprünglichen Breakpoint von 700px wechselt das Raster zu einer einzelnen Spalte, der Header wird vertikal angeordnet und das Seitenverhältnis des Artworks ändert sich von 4:5 auf 4:3. Die Bildunterschrift bleibt außerhalb des Artworks, damit die Leseoberfläche stabil bleibt.
Alle interaktiven Steuerelemente liegen auf einer deckenden semantischen Oberfläche. Bei wenig Platz werden die Buttons umgebrochen. Die Höhe der Vorschau richtet sich nach ihrem Inhalt statt nach einer Mindesthöhe relativ zum Viewport. Das ist wichtig, wenn das Dokument in einem automatisch dimensionierten iframe eingebettet ist. Kein Scrollbereich mit fester Höhe verbirgt das Formular oder dessen Ergebnis.
Button verwendet onPress statt eines benutzerdefinierten, nur mit dem Zeiger auslösbaren Ereignisses. Slider unterstützt die Bedienung per Tastatur und gibt die Werte bekannt. Switch stellt seinen booleschen Zustand über die native Barrierefreiheitsimplementierung bereit. Ein benutzerdefiniertes Layout CSS entfernt nicht die Fokusdarstellung. Für deaktivierte Komponenten sollte isDisabled statt allein der Deckkraft verwendet werden; --disabled-opacity beschreibt nur das Erscheinungsbild.
Der Statusabsatz hat role=status, sodass ein angewendeter Snapshot angesagt werden kann, ohne den Tastaturfokus zu verschieben. Die Beschriftung des Buttons für das dunkle Erscheinungsbild beschreibt die nächste Aktion. Das Artwork hat eine aussagekräftige Bereichsbeschriftung; seine Formen bleiben dekorativ. Diese Demo verspricht nicht, dass Daten nach einem Neuladen erhalten bleiben.
Die Qualität ist ein begrenzter numerischer Wert mit sichtbarer Ausgabe.
Metadaten sind ein boolescher Wert mit Beschriftung und Erläuterung.
Mit „Anwenden“ wird ein lokaler Snapshot gespeichert; „Zurücksetzen“ löscht ihn und stellt den ursprünglichen Entwurf wieder her.
HeroUI Designsystem: Beispiel installieren und reproduzieren
Eine Stylesheet-Pipeline auswählen
Installiere in einer Vite-Anwendung React die festgelegten HeroUI-Pakete sowie Tailwind CSS v4 mit dem Vite-Plugin. Importiere im Hauptstylesheet zuerst tailwindcss und danach @heroui/styles und füge anschließend das ursprüngliche Layout CSS ein. Rendere App mit React createRoot; für diese Komposition ist kein v2-Provider erforderlich. Der Setup-Abschnitt enthält den Einstiegspunkt und die Vite-Konfiguration. Die vollständige App und CSS findest du weiter oben.
Das herunterladbare, eigenständige Beispiel verwendet das vorkompilierte heroui.min.css des Pakets sowie ein esbuild-React-Bundle, die beide eingebettet sind. Dadurch benötigt die Vorschau keine CDN-Abhängigkeiten. Es demonstriert dieselben nativen Steuerelemente, ist jedoch keine Anleitung, sowohl kompilierte als auch mit Tailwind generierte HeroUI-Styles in eine Produktionsanwendung zu importieren. Wähle eine einzige Pipeline, um doppelte Regeln zu vermeiden.
HeroUI Designsystem: Recipe erweitern, ohne einen Encoder zu erfinden
Funktionsgrenzen klar kenntlich machen
Füge für eine echte Bildkonvertierung ein Dateifeld und einen tatsächlich verfügbaren Encoder im Browser oder auf dem Server hinzu und verknüpfe die Zustände „Ausstehend“, „Fehlgeschlagen“ und „Abgeschlossen“ mit diesem Prozess. Slider wählt lediglich einen Wert aus und führt keine Komprimierung durch. Ein Button „Anwenden“ darf erst dann zu einem Button „Herunterladen“ werden, wenn tatsächlich ein Ausgabe-Blob vorliegt. Bewahre das Originalbild separat auf, damit wiederholte Änderungen an der Recipe nicht zu einer kumulierten verlustbehafteten Kodierung führen.
Überschreibe beim Theming der Anwendung semantische Farbpaare immer gemeinsam und teste sowohl das helle als auch das dunkle Erscheinungsbild. Wird nur --accent geändert und ein ungeeigneter Vordergrund beibehalten, kann der Buttonkontrast darunter leiden. Für umfangreichere Anpassungen solltest du dokumentierte Komponentenklassen und Datenzustände verwenden, statt das barrierefreie Eingabefeld der Komponente durch ein optisch ähnliches div zu ersetzen.
Zusammengesetzte Slider- und Switch-Komponenten übernehmen die offizielle Gestaltung. Ein separater angewendeter Snapshot macht den Unterschied zwischen Entwurf und angewendetem Zustand sichtbar.
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>;
}
Slider.Output gibt den gesteuerten Zahlenwert aus.
Switch.Control und Switch.Thumb sind erforderliche sichtbare Bestandteile.
onPress wendet eine Recipe an; es wird nicht behauptet, dass ein Bild kodiert wurde.
Ursprüngliches Layout CSS
Verweise auf Oberflächen und Radien verwenden HeroUI-Variablen; die Farben des Artworks, die Schriftgrößenskala und der Breakpoint sind explizite Entscheidungen der Anwendung.
Binde dieses CSS nach dem offiziellen Stylesheet ein.
Die Klasse dark auf html ändert die semantischen Werte für das gesamte Dokument.
04
HeroUI Designsystem: Setup für KI-Agenten
Ausgangspunkt für die Implementierung
Die native Vorschau wurde mit React 19 und HeroUI 3.2.6 überprüft. Die bereitgestellte App und das Layout CSS sind vollständig. Diese Vite-Konfiguration verwendet die dokumentierte Tailwind-v4-Importpipeline; das Offline-Beispiel bindet stattdessen das offizielle vorkompilierte Stylesheet ein.
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.
Ein Prompt für dein Projekt
Agenten-Prompt
Verwende die bereitgestellte App.jsx für HeroUI 3.2.6, das Stylesheet und die Tailwind-Integration, um die Bildexport-Anwendung zu erstellen. Verknüpfe den Qualitätsstatus von Slider und den Metadatenstatus von Switch mit der Exportzusammenfassung; übernimm Switch.Content, Control und Thumb samt Beschriftungen. Änderungen an Qualität oder Metadaten müssen den gespeicherten Snapshot ungültig machen. Die Steuerung für das dunkle Erscheinungsbild sollte dieselbe Dokumentklasse ändern, die auch das Stylesheet verwendet. Speichere ausdrücklich nur eine lokale Export-Recipe; erwecke nicht den Eindruck, eine Bilddatei sei verarbeitet oder heruntergeladen worden.
05
HeroUI Quellen und Umfang des Designsystems
Referenz für HeroUI 3.2.6. Offizielle Variablen sind von eigener Typografie, Artwork und eigenem Layout abgegrenzt. Die native Vorschau ändert nur die im Speicher gehaltenen Einstellungen und führt keine Bildkodierung durch.
