# Sistema di design HeroUI

## Anteprima dell'interfaccia del sistema di design HeroUI

Modifica la qualità con uno slider nativo, attiva o disattiva i metadati, cambia l'aspetto e applica una configurazione locale. Non viene simulato alcun encoder o caricamento.

## Riferimento di progettazione del sistema di design HeroUI

Tema predefinito HeroUI 3.2.6, verificato con @heroui/styles/dist/themes/default/variables.css. I valori OKLCH riportati di seguito sono i valori letterali del pacchetto. I colori dell'illustrazione e la tipografia sono scelte applicative, non design token del brand HeroUI.

### Superfici semantiche e contrasto

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --background | oklch(0.9702 0 0) | Tela chiara della pagina; in modalità scura diventa oklch(12% 0.005 285.823). |
| --foreground | var(--eclipse) | Colore del testo chiaro; in modalità scura assume il valore --snow. |
| --surface | var(--white) | Sfondo chiaro della scheda; in modalità scura è oklch(0.2103 0.0059 285.89). |
| --overlay | var(--white) | Sfondo del livello flottante, con un ruolo distinto da quello della superficie anche quando i valori chiari coincidono. |
| --accent | oklch(0.6204 0.195 253.83) | Riempimento dello switch selezionato, dello slider e del pulsante primario. |
| --accent-foreground | var(--snow) | Testo sull'accento pieno. |
| --muted | oklch(0.5517 0.0138 285.94) | Testo secondario; in modalità scura è oklch(70.5% 0.015 286.067). |
| --border | oklch(90% 0.004 286.32) | Bordi chiari; in modalità scura è oklch(28% 0.006 286.033). |
| --focus | var(--accent) | Indicatore di messa a fuoco da tastiera. |
| --field-background | var(--white) | Superfici chiare dei campi; in modalità scura seguono il valore eclipse. |
### Forma, spaziatura e stato

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --spacing | 0.25rem | Unità di spaziatura di base; 4px con una radice di 16px. |
| --radius | 0.5rem | Raggio primitivo predefinito; 8px con una radice di 16px. |
| --field-radius | calc(var(--radius) * 1.5) | Raggio predefinito dei campi: 12px. |
| --border-width | 1px | Spessore predefinito dei bordi. |
| --field-border-width | 0px | I campi predefiniti non si affidano a un bordo di contorno. |
| --disabled-opacity | 0.5 | Stile visivo disabilitato; usare comunque la proprietà isDisabled del componente. |
| --ring-offset-width | 2px | Spazio tra il controllo e l'anello di messa a fuoco. |
| --tooltip-delay | 1500ms | Ritardo iniziale dei tooltip nel pacchetto predefinito. |
| --tooltip-close-delay | 500ms | Ritardo di chiusura del tooltip. |
### Tipografia e layout dell’applicazione

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| body | 16px / 1.5, Arial, Helvetica, sans-serif | Scelta esplicita del font per l'anteprima; non rappresenta un font obbligatorio di HeroUI. |
| h1 | 32px / 1.15; 28px below 700px | Scala originale dei titoli della pagina. |
| h2 | 24px / 1.25 | Titolo delle impostazioni di esportazione. |
| helper text | 13px / inherited 1.5 | Spiegazione della qualità e risultato locale. |
| desktop gap | 24px | Griglia a due colonne per illustrazione e impostazioni. |
| mobile breakpoint | 700px | Regola responsive originale, non un breakpoint token di HeroUI. |
| card radius | calc(var(--radius) * 3) | Composizione applicativa di 24px che usa il primitivo ufficiale. |
### Configurazione dei controlli nativi

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| quality range | minValue=10; maxValue=100; step=5 | Intervallo della configurazione dell'encoder applicativo, non un valore predefinito di HeroUI. |
| Slider | value + onChange | La modifica controllata del numero aggiorna il risultato e la configurazione. |
| Switch | isSelected + onChange | Il booleano controllato mantiene un'unica fonte di verità. |
| Button | onPress | L'evento press di React Aria supporta l'attivazione con puntatore e tastiera. |
## Guida completa al sistema di design HeroUI

Una guida pratica per scegliere, applicare e valutare questo sistema in un’interfaccia reale.

Indicazioni complete, un punto di partenza per l’implementazione e link alle fonti.

## Sistema di design HeroUI v3 e lo Studio di esportazione

### Componenti React e un foglio di stile semantico

> Questo esempio è pensato per HeroUI 3.2.6. I controlli sono componenti React basati sul comportamento di React Aria, mentre il livello visivo deriva da @heroui/styles. La guida rapida ufficiale richiede React 19 e Tailwind CSS v4. La configurazione v3 non racchiude questa applicazione nel vecchio schema HeroUIProvider. Mischiare tutorial v2 con questo componente composto API è una causa concreta di controlli mancanti o stilizzati in modo errato.

L'esempio è un editor di configurazioni di esportazione: l'illustrazione è a sinistra, i controlli di qualità e metadati a destra. L'illustrazione è disegnata con CSS originale. Non è un'immagine elaborata dalla libreria. Applicando una configurazione, le impostazioni selezionate vengono salvate nello stato locale React; volutamente non vengono inventate dimensioni del file né risultati di download.

Leggi la specifica di supporto

## Colori semantici e aspetto del sistema di design HeroUI

### Separa la tela, le superfici e i livelli flottanti

Usa --background per la tela esterna, --surface per le schede dell'illustrazione e delle impostazioni e --overlay per un futuro popover o una finestra di dialogo. Sono ruoli semantici, anche quando in modalità chiara due di essi corrispondono al bianco. In modalità scura, la tela e le superfici rialzate assumono colori diversi. L'esempio attiva la classe dark su document.documentElement, così tutti gli elementi discendenti condividono lo stesso ambito del tema.

Il riempimento dello slider e lo switch selezionato usano il ruolo accent. I controlli con accento pieno lo abbinano a --accent-foreground. Il testo secondario usa --muted, invece di ridurre l'opacità di un'intera scheda. L'illustrazione mantiene la propria palette calda in entrambe le modalità, perché è contenuto e non un elemento dell'interfaccia interattiva.

Leggi la specifica di supporto

## Tipografia e spaziatura del sistema di design HeroUI

### Dichiara esplicitamente la scala dell'applicazione

Lo stile di HeroUI si integra con le utility di Tailwind, ma questa pagina non impone un unico font HeroUI. Il suo CSS originale sceglie Arial/Helvetica, con testo del corpo a 16px e interlinea 1.5. Un titolo di 32px diventa di 28px nel layout stretto; il titolo delle impostazioni è di 24px. La tabella di riferimento distingue questi valori dell'applicazione dalle variabili del pacchetto.

Il primitivo ufficiale --spacing è 0.25rem. Questa composizione usa 16px all'interno della configurazione, 24px tra le colonne e attorno alle schede desktop e 32px attorno alla tela desktop. Il raggio dei campi deriva dal primitivo ufficiale di 8px. Il raggio delle schede usa intenzionalmente tre volte quel primitivo: il valore di 24px è quindi una derivazione dell'applicazione, non un valore predefinito dichiarato per Card.

Leggi la specifica di supporto

## Crea uno slider completo con il sistema di design HeroUI

### Mantieni insieme struttura e gestione del valore

La radice Slider gestisce value, onChange, minValue, maxValue e step. Label fornisce il nome accessibile. Slider.Output legge lo stesso valore e Slider.Track contiene Slider.Fill e Slider.Thumb. Se si omettono queste parti visibili, il componente può comportarsi correttamente ma non mostrare la traccia o la maniglia previste. Questo esempio usa un singolo numero, non un array di intervalli.

La qualità è limitata all'intervallo 10–100, con incrementi di cinque. Questi limiti sono decisioni locali del prodotto. HeroUI usa come valori predefiniti un intervallo da 0 a 100 con step uno. Non esiste una relazione universale affidabile tra un valore di qualità e i byte, quindi il testo di aiuto spiega il compromesso senza inventare una stima delle dimensioni del file. Per supportare più maniglie, usa un array di numeri e assegna a ogni maniglia l'indice corretto.

1. Porta lo slider della qualità in primo piano e usa un tasto freccia per modificare il valore di uno step.

2. Verifica che il valore visibile e la configurazione corrente cambino insieme.

3. Applica la configurazione, poi sposta di nuovo lo slider per distinguere la bozza dall'istantanea applicata.

Leggi la specifica di supporto

## Componi un'impostazione booleana con il sistema di design HeroUI

### Uno switch è composto da parti di controllo e contenuto

L'impostazione dei metadati usa isSelected e onChange su Switch. Nell'implementazione installata della versione 3.2.6, Switch.Content racchiude Switch.Control e Label; Switch.Control contiene Switch.Thumb. Description è accanto a Switch.Content e fornisce assistenza a livello di campo. Questa struttura segue il codice sorgente installato, in cui la composizione di SwitchField/SwitchButton differisce da alcuni esempi della documentazione v3 precedente. La descrizione spiega il significato del booleano, invece di affidarsi alla traccia blu dello switch selezionato. Un unico stato dei metadati controlla sia il controllo nativo sia la configurazione testuale.

Mantieni questo booleano separato dall'operazione di applicazione. Attivare o disattivare i metadati modifica immediatamente la bozza corrente; premendo Applica all'anteprima si registra un'istantanea. Reimposta ripristina la qualità a 80, rimuove i metadati e cancella l'istantanea. Non riutilizzare un indicatore di stato salvato per rappresentare una bozza diversa. Se fosse collegato a un encoder, passa l'oggetto applicato a quel processo invece di leggere testo ambiguo dal modulo.

Leggi la specifica di supporto

## Componi superfici responsive con il sistema di design HeroUI

### L'illustrazione rimane contenuto, non una decorazione dietro ai controlli

Su desktop si usa una griglia 1.05fr/1fr, che lascia un po' più spazio all'illustrazione mantenendo leggibili le impostazioni. Al breakpoint originale di 700px, la griglia diventa a colonna singola, l'intestazione si dispone in verticale e il rapporto d'aspetto dell'illustrazione passa da 4:5 a 4:3. La didascalia resta fuori dall'immagine per mantenere una superficie di lettura stabile.

Tutti i controlli interattivi si trovano su una superficie semantica piena. Se lo spazio è limitato, i pulsanti vanno a capo. L'altezza dell'anteprima dipende dal contenuto, anziché da un'altezza minima basata sulla finestra: è importante quando il documento è incorporato in un iframe con dimensioni automatiche. Nessuna casella di scorrimento ad altezza fissa nasconde il modulo o il risultato.

Leggi la specifica di supporto

## Interazione, messa a fuoco e risultati trasparenti nel sistema di design HeroUI

### Usa gli stati nativi invece di sostituti puramente visivi

Button usa onPress invece di un evento personalizzato limitato al puntatore. Slider supporta la manipolazione da tastiera e annuncia i valori. Switch espone il proprio stato booleano tramite l'implementazione nativa delle funzionalità di accessibilità. Il layout personalizzato CSS non rimuove gli stili di messa a fuoco. Per disabilitare un componente, usa isDisabled anziché la sola opacità; --disabled-opacity descrive solo l'aspetto.

Il paragrafo di stato usa role=status, così l'istantanea applicata può essere annunciata senza spostare la messa a fuoco da tastiera. Il testo del pulsante per l'aspetto scuro cambia per descrivere l'azione successiva. L'illustrazione ha un'etichetta descrittiva per la regione e le sue forme restano decorative. Questa demo non promette che i dati persistano dopo il ricaricamento.

- La qualità è un valore numerico limitato, con un output visibile.

- I metadati sono un valore booleano, con un'etichetta e un testo esplicativo.

- Applica salva un'istantanea locale; Reimposta la cancella e ripristina la bozza iniziale.

Leggi la specifica di supporto

## Installa e riproduci l'esempio del sistema di design HeroUI

### Scegli una pipeline per il foglio di stile

In un’applicazione Vite con React, installa i pacchetti con versione bloccata HeroUI e Tailwind CSS v4 con il relativo plugin per Vite. Nel foglio di stile principale importa prima tailwindcss e poi @heroui/styles, quindi includi il CSS di layout originale. Esegui il rendering di App con createRoot di React; per questa composizione non è necessario un provider v2. Il blocco di configurazione mostra il file di ingresso e la configurazione di Vite; qui sopra sono disponibili App e CSS completi.

L’esempio autonomo scaricabile usa il file heroui.min.css precompilato del pacchetto e un bundle React creato con esbuild, entrambi incorporati. In questo modo l’anteprima non dipende da CDN. L’esempio mostra gli stessi controlli nativi, ma non invita a importare nella stessa app di produzione sia gli stili HeroUI compilati sia quelli generati da Tailwind. Scegli una sola pipeline per evitare regole duplicate.

Leggi la specifica di supporto

## Sistema di design HeroUI — Estendi la ricetta senza inventare un codificatore

### Rendi evidenti i limiti delle funzionalità

Per aggiungere una vera conversione delle immagini, inserisci un input per i file e un codificatore effettivo, nel browser o sul server, poi collega a tale processo gli stati in attesa, di errore e di completamento. Uno Slider seleziona soltanto un valore: non comprime le immagini. Il pulsante Apply non deve diventare un pulsante Download finché non esiste un vero blob di output. Conserva separatamente l’immagine originale, così le modifiche ripetute alla ricetta non si accumulano in una codifica con perdita di qualità.

Quando definisci il tema dell’applicazione, sovrascrivi insieme le coppie semantiche e verifica l’aspetto sia chiaro sia scuro. Modificare solo --accent mantenendo un colore di primo piano inadatto può compromettere il contrasto dei pulsanti. Per personalizzazioni più elaborate, usa le classi dei componenti e gli stati data documentati invece di sostituire l’input accessibile del componente con un div dall’aspetto simile.

Leggi la specifica di supporto

## Sistema di design HeroUI — Esempi di componenti

### Applicazione completa per la ricetta di esportazione

Le parti composte Slider e Switch ereditano lo stile ufficiale. Uno snapshot applicato separato rende visibile la distinzione tra stato in bozza e stato applicato.

```
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>;
}
```

Riferimento del codice

- Slider.Output riflette il valore numerico controllato.

- Switch.Control e Switch.Thumb sono parti visibili necessarie.

- onPress applica una ricetta; non dichiara che un’immagine sia stata codificata.

### CSS di layout originale

I riferimenti a superfici e raggi usano le variabili HeroUI; i colori delle illustrazioni, la scala tipografica e il breakpoint sono scelte esplicite dell’applicazione.

```
*{box-sizing:border-box}body{margin:0;background:var(--background);color:var(--foreground);font-family:Arial,Helvetica,sans-serif;font-size:16px;line-height:1.5}.export-app{max-width:1120px;padding:32px;margin:auto}header{display:flex;justify-content:space-between;align-items:start;gap:24px;margin-bottom:28px}h1{font-size:32px;font-weight:700;letter-spacing:-.035em;line-height:1.15;margin:8px 0 12px}h2{font-size:24px;font-weight:650;line-height:1.25;margin:8px 0 12px}.eyebrow{font-size:11px;letter-spacing:.12em;font-weight:700}.muted,.helper,footer{color:var(--muted)}.muted{margin:0 0 24px}.export-grid{display:grid;grid-template-columns:1.05fr 1fr;gap:24px}.art-panel,.settings{background:var(--surface);border-radius:calc(var(--radius)*3);padding:24px;box-shadow:var(--surface-shadow)}.art{position:relative;aspect-ratio:4/5;background:#f0d8b8;border-radius:calc(var(--radius)*2);overflow:hidden}.sun{width:40%;aspect-ratio:1;background:#bf532f;position:absolute;top:13%;left:30%;border-radius:50%}.hill{position:absolute;width:180%;height:70%;border-radius:50%;transform:rotate(-24deg)}.one{top:50%;left:-60%;background:#c59162}.two{top:66%;left:-10%;background:#69402e}.art span{position:absolute;top:6%;left:8%;font-size:11px;letter-spacing:.2em;color:#563324}.art-caption{display:flex;flex-direction:column;gap:4px;margin-top:16px}.art-caption span{color:var(--muted);font-size:12px}.settings{display:flex;flex-direction:column;gap:16px}.settings .muted{margin-bottom:0}.slider-heading{display:flex;justify-content:space-between;gap:16px}.helper{font-size:13px;margin:0}.recipe{border:var(--border-width) solid var(--border);padding:16px;border-radius:var(--field-radius)}.recipe .eyebrow{margin-top:0}code{font-size:14px}.actions{display:flex;flex-wrap:wrap;gap:8px}.status{font-size:13px;margin:0}footer{font-size:12px;margin-top:20px}@media(max-width:700px){.export-app{padding:16px}header{flex-direction:column}h1{font-size:28px}.export-grid{grid-template-columns:1fr}.art{aspect-ratio:4/3}.art-panel,.settings{padding:20px}}
```

Riferimento del codice

- Carica questo CSS dopo il foglio di stile ufficiale.

- La classe dark su html modifica i valori semantici per l’intero documento.

## Sistema di design HeroUI Configurazione dell’agente

### Punto di partenza per l’implementazione

Anteprima nativa verificata con React 19 e HeroUI 3.2.6. App e il CSS di layout forniti sono completi. Questa configurazione di Vite usa la pipeline di importazione documentata di Tailwind v4; l’esempio offline incorpora invece il foglio di stile ufficiale precompilato.

```
// In a Vite React 19 project:
// npm install @heroui/react@3.2.6 @heroui/styles@3.2.6 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.
```

### Un prompt per il tuo progetto

```
Usa App.jsx 3.2.6 di HeroUI, il foglio di stile e l’integrazione Tailwind forniti per creare lo studio di esportazione delle immagini. Collega lo stato della qualità di Slider e quello dei metadati di Switch al riepilogo dell’esportazione; mantieni Switch.Content, Control e Thumb insieme alle rispettive etichette. Modificare la qualità o i metadati deve invalidare lo snapshot salvato. Il controllo dell’aspetto scuro deve modificare la stessa classe del documento usata dal foglio di stile. Salva una ricetta di esportazione esplicitamente locale; non suggerire che un file immagine sia stato elaborato o scaricato.
```

## HeroUI Fonti e ambito del sistema di design

Riferimento a HeroUI 3.2.6. Le variabili ufficiali sono distinte da tipografia, illustrazioni e layout originali. L’anteprima nativa modifica solo impostazioni conservate in memoria e non esegue codifiche di immagini.

- Avvio rapido Requisiti di React e Tailwind e relativo ordine di importazione.

- Colori Ruoli dei colori semantici.

- Temi Personalizzazione del tema CSS.

- Slider Struttura composta e valori numerici controllati.

- Switch Composizione booleana e stato.

- Stile Approccio alla definizione degli stili dei componenti.

## HeroUI Risorse correlate sul sistema di design

### Ionic Framework

Un’interfaccia nativa Ionic per le preferenze di lettura, con ruoli cromatici verificati, geometrie degli intervalli per iOS e Material, comportamento effettivo di segmenti e interruttori e un articolo che si adatta alle scelte di font, dimensione e sfondo.

### Kobalte

Kobalte offre componenti headless per Solid, inclusi campi numerici con valori grezzi e formattati separati, l’anatomia composta delle checkbox e pulsanti con stato premuto. Questa guida collega le primitive ai segnali Solid attraverso uno scaler di ricette con quantità derivate e caselle degli ingredienti ripristinabili.

### Mantine

Una guida di riferimento per Mantine 9, basata su una tabella nativa dei partecipanti e un drawer per la pianificazione. Esamina le scale effettive del tema, collega useForm a TextInput, Select, Checkbox e DatePickerInput e prova la convalida prima di aggiungere un record locale.


- [Riferimento per l’implementazione](https://heroui.com/en/docs/react/components/slider)
- [Fonte](https://heroui.com/en/docs/react/handbook/colors)
- [Fonte](https://heroui.com/en/docs/react/handbook/theming)
- [Fonte](https://heroui.com/en/docs/react/handbook/styling)
- [Fonte](https://heroui.com/en/docs/react/components/slider)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/getting-started/quick-start)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/handbook/colors)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/handbook/theming)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/components/slider)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/components/switch)
- [Leggi la specifica di supporto](https://heroui.com/en/docs/react/handbook/styling)
- [Riferimento del codice](https://heroui.com/en/docs/react/components/slider)
- [Riferimento del codice](https://heroui.com/en/docs/react/handbook/styling)
- [Avvio rapido Requisiti di React e Tailwind e relativo ordine di importazione.](https://heroui.com/en/docs/react/getting-started/quick-start)
- [Colori Ruoli dei colori semantici.](https://heroui.com/en/docs/react/handbook/colors)
- [Temi Personalizzazione del tema CSS.](https://heroui.com/en/docs/react/handbook/theming)
- [Slider Struttura composta e valori numerici controllati.](https://heroui.com/en/docs/react/components/slider)
- [Switch Composizione booleana e stato.](https://heroui.com/en/docs/react/components/switch)
- [Stile Approccio alla definizione degli stili dei componenti.](https://heroui.com/en/docs/react/handbook/styling)