# Semi Design Sistema di progettazione ## Anteprima dell’interfaccia del sistema di progettazione sistema di design Semi Design Convalida un nome, scegli una preferenza per il riepilogo, torna ai passaggi precedenti e controlla la configurazione locale finale. ## Riferimento di progettazione del sistema di progettazione sistema di design Semi Design Documentazione ufficiale di Semi e snapshot SCSS del tema predefinito. I nomi $ sono costanti Sass risolte in fase di compilazione; i nomi --semi-* sono variabili CSS disponibili a runtime. I dati del flusso di lavoro dell’applicazione sono originali. ### Spaziatura e dimensioni dei controlli | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | $height-control-small / default / large | 24 / 32 / 40px | Altezze dei controlli pubblicate. | | $spacing-super-tight | 2px | La spaziatura più ridotta. | | $spacing-extra-tight | 4px | Spaziatura molto ridotta. | | $spacing-tight | 8px | Spaziatura ridotta. | | $spacing-base-tight | 12px | Spaziatura compatta tra gruppi. | | $spacing-base | 16px | Spaziatura predefinita. | | $spacing-base-loose | 20px | Spaziatura più ampia tra i gruppi. | | $spacing-loose | 24px | Spaziatura tra le sezioni. | | $spacing-extra-loose | 32px | Separazione ampia. | | $spacing-super-loose | 40px | La spaziatura nominale più ampia di questo insieme. | ### Abbinamenti tipografici | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | font-size-small mixin | 12 / 16px | Dimensione da variables.scss, interlinea dal mixin. | | font-size-regular mixin | 14 / 20px | Testo del corpo. | | font-size-header-6 mixin | 16 / 22px | Titolo piccolo. | | font-size-header-4 mixin | 20 / 28px | Titolo di sezione. | | font-size-header-3 mixin | 24 / 32px | Opzione per il titolo della pagina. | | font-size-header-1 mixin | 32 / 44px | Il titolo nominale più grande. | ### Corrispondenze dei ruoli del tema | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | --semi-color-primary | rgba(var(--semi-blue-5),1) | La palette chiara corrisponde a rgb(0,100,250). | | --semi-color-primary-hover | rgba(var(--semi-blue-6),1) | La palette chiara corrisponde a rgb(0,98,214). | | --semi-color-text-0 | rgba(var(--semi-grey-9),1) | Il testo primario chiaro corrisponde a rgb(28,31,35). | | --semi-color-text-2 | Grey 9 at .62 opacity in light mode | Testo secondario; il tema scuro usa un’opacità diversa. | | --semi-color-fill-0 | Grey 8 at .05 opacity in light mode | Il riempimento tenue si adatta alla superficie su cui si trova. | | --semi-border-radius-small | 3px | Controlli comuni. | | --semi-border-radius-medium | 6px | Menu e superfici simili. | | --semi-border-radius-large | 12px | Ruolo per contenitori grandi. | | --semi-border-radius-full | 9999px | Stile a pillola. | ### Specifiche di Steps | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | type="basic" | Recommended simple step bar | La documentazione indica come deprecato lo stile predefinito precedente. | | current | Zero-based number | Inizia da 0. | | status | wait / process / finish / error / warning | Stato del passaggio corrente. | | type="nav" | Non-interactive navigation appearance | Non è una scorciatoia per creare una procedura guidata cliccabile. | | onChange(index) | Index includes initial offset | Spetta all’applicazione stabilire se la navigazione è consentita. | ### Input e Switch | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | Input onChange | (value,event) | Il primo argomento è il nuovo valore. | | Input validateStatus | default / error / warning | Solo stile visivo; non convalida i dati di business. | | Input composition | Boolean, false by default | Se abilitato, ritarda onChange fino alla conferma dell’input tramite IME. | | Input aria-describedby | Description ID | Collega il testo di aiuto e quello di errore. | ### Varianti di Switch e Button | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | Switch checked | Controlled Boolean | Mantieni la preferenza nello stato del componente padre. | | Switch onChange | (checked,event) | Usa direttamente il valore booleano. | | Switch aria-label | Meaningful state label | Descrivi la preferenza, non l’interruttore visivo. | | Switch size="small" | No checkedText / uncheckedText treatment | Mantieni le etichette lunghe all’esterno dell’interruttore. | ## Guida completa al sistema di progettazione sistema di design Semi Design 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 progettazione sistema di design Semi Design: scegli il pacchetto corrispondente alla major effettiva di React ### Il suffisso cambia l’integrazione > La Quick Start attuale di Semi distingue il pacchetto React 19 da quello usato nelle versioni precedenti di React. Questo esempio sceglie esplicitamente React 18 e @douyinfe/semi-ui. Per passare a React 19, occorre usare gli import documentati di @douyinfe/semi-ui-19 e scegliere la dipendenza corrispondente. I bundler supportati caricano gli CSS correlati dai componenti JavaScript. Le modifiche in fase di compilazione, come un prefisso personalizzato, la compilazione del tema o i livelli CSS, richiedono considerazioni specifiche sugli strumenti. Non trasformare un esempio di importazione di base nell’affermazione che ogni personalizzazione del tema funzioni senza configurazione. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: le scale Sass nominali rendono concreta la densità ### Usa le altezze dei controlli pubblicate: 24, 32 e 40px Le tre costanti di Semi per l’altezza dei controlli sono 24, 32 e 40px. I valori di spaziatura nominali vanno da 2 a 40px, con incrementi non uniformi. Un campo predefinito nella procedura guidata può usare 12px di spazio per il testo di aiuto e una separazione di 24px dalla sezione successiva, senza introdurre un nuovo sistema di spaziatura. Questi valori sono costanti Sass, non variabili disponibili automaticamente a runtime. L’esempio usa le dimensioni corrispondenti nel CSS originale della pagina. Questa differenza è importante quando uno sviluppatore vuole applicare un tema al layout a runtime invece di ricompilare un foglio di stile. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: usa le coppie corrette di dimensione e interlinea ### Il testo del corpo e i titoli hanno ritmi diversi Il mixin regular abbina testo da 14px a un’interlinea di 20px; il mixin small abbina 12px a 16px. Il titolo di livello 3 è 24/32, mentre il titolo di livello 1 è 32/44. Il primo si adatta a un breve titolo della procedura guidata, lasciando il secondo a una gerarchia di pagina più marcata. La famiglia di font di origine inizia con Inter, seguito dai fallback di piattaforma e CJK. L’anteprima offline usa uno stack di sistema disponibile e non dichiara di aver scaricato un font specifico. Mantieni brevi i nomi dei passaggi, così resteranno chiari anche quando la barra dei passaggi va a capo su uno schermo stretto. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: i ruoli del tema sono distinti dai canali della palette ### Usa i ruoli risolti nel CSS dell’applicazione Il ruolo primario racchiude una variabile di canale della palette con rgba. Usare --semi-color-primary è adatto a una normale proprietà di colore; un elenco di canali grezzo come --semi-blue-5, da solo, non è un colore CSS completo. Le palette chiare e scure modificano i valori di questi canali. Anche i ruoli del testo usano l’opacità. Il testo secondario non è un codice esadecimale arbitrariamente più chiaro e il testo disabilitato non va riutilizzato per informazioni di aiuto importanti. La procedura guidata mantiene neutro il messaggio di completamento, perché preparare la configurazione non crea un account attivo. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: Steps di base comunica l’avanzamento, non autorizza a saltare la convalida ### Le regole di transizione spettano all’applicazione Per una barra dei passaggi semplice, Semi consiglia type="basic". current inizia da zero, mentre al passaggio corrente si può assegnare lo stato process, error o un altro stato supportato. La documentazione contrassegna come deprecato l’aspetto predefinito precedente. L’esempio fa avanzare deliberatamente l’utente con i controlli Continua e Precedente. Non collega il clic su ogni passaggio a setCurrent, perché ciò permetterebbe di arrivare alla revisione senza aver inserito un nome. L’aspetto nav, descritto separatamente nella documentazione, non è interattivo e non va confuso con la navigazione della procedura guidata. 1. Convalida il nome prima di lasciare il primo passaggio. 2. Mantieni il valore booleano scelto per il riepilogo settimanale quando si torna indietro. 3. Mostra tutte le impostazioni nella revisione. 4. Prepara una configurazione locale senza dichiarare che esistano già un account o un abbonamento. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: la convalida visiva non verifica il valore ### Usa correttamente la callback che riceve prima il valore In Semi Input, onChange riceve prima il valore e poi l’evento. L’esempio può quindi passare direttamente setName. validateStatus modifica solo l’aspetto; il controllo del nome vuoto è logica dell’applicazione e richiede una spiegazione visibile. Per il testo che attiva query in tempo reale, la composizione può rimandare le callback fino alla conferma tramite IME. Il campo del nome dell’area di lavoro non esegue query in tempo reale, quindi l’esempio omette questo comportamento facoltativo invece di presentarlo come un requisito universale. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: una preferenza resta comprensibile accanto al relativo interruttore ### Mantieni lo stato nel componente padre Switch usa checked e una callback onChange che riceve prima il valore booleano. L’etichetta dovrebbe descrivere la preferenza, per esempio Riepilogo settimanale, mentre il testo circostante ne spiega il significato. Le stringhe lunghe per gli stati attivo e disattivo vanno tenute all’esterno del piccolo controllo; gli switch piccoli non supportano questi testi al loro interno. - Usa un nome accessibile chiaro che identifichi la preferenza. - Mantieni il valore della preferenza passando da un passaggio all’altro della procedura guidata. - Mostra il valore finale con testo normale nella pagina di revisione. Leggi la specifica di supporto ## Sistema di progettazione sistema di design Semi Design: il tipo e il tema di un pulsante rispondono a domande diverse ### Ruolo semantico e trattamento visivo In Semi, type di Button definisce un ruolo, per esempio primary o danger. theme seleziona il trattamento visivo: light, solid, borderless o outline. L’esempio usa un’azione Continua primaria e piena e un’azione Precedente più discreta, invece di usare impropriamente danger per dare maggiore risalto a un pulsante. Nell’esempio offline, quando cambia il passaggio il focus viene spostato sul titolo della nuova sezione, mentre in caso di convalida non riuscita torna al campo non valido. Il layout per dispositivi mobili e la sequenza da tastiera sono verificati separatamente dall’esempio nativo di React, il cui codice è verificato alla fonte. Leggi la specifica di supporto ## Esempi di componenti del sistema di progettazione sistema di design Semi Design ### Esempio interattivo completo e autonomo Salva il documento completo come index.html e aprilo in un browser. Interpretazione offline di HTML delle scale del tema Semi e del comportamento di Steps/Input/Switch. L’esempio nativo di React è separato. ``` Semi workspace setup interpretation
◒ WorkspaceConfiguration studio

Make room for your team

Three steps to prepare a workspace configuration.

  1. 1Name workspace
  2. 2Choose updates
  3. 3Review settings

Independent HTML interpretation of Semi’s theme and components. This example stores a draft only in memory; it does not create an account.

``` Riferimento del codice - Continua convalida il nome dell’area di lavoro prima di procedere. Questo documento interpreta i passaggi; la voce separata di React specifica la distinzione tra i pacchetti React 18 e 19. ### Procedura guidata di configurazione in tre passaggi con convalida Steps di base tiene traccia dell’avanzamento; Input e Switch conservano i valori tra le pagine. Continua convalida il nome e l’azione finale prepara soltanto la configurazione locale. ``` // React 18 example. React 19 uses @douyinfe/semi-ui-19 instead. // npm install react@18 react-dom@18 @douyinfe/semi-ui import React,{useState} from 'react'; import {createRoot} from 'react-dom/client'; import {Steps,Input,Switch,Button} from '@douyinfe/semi-ui'; function WorkspaceSetup(){ const [current,setCurrent]=useState(0),[name,setName]=useState(''); const [digest,setDigest]=useState(true),[error,setError]=useState(''); const [prepared,setPrepared]=useState(false); function next(){ if(current===0&&!name.trim()){setError('Enter a workspace name.');return;} setError('');setCurrent(n=>Math.min(2,n+1)); } return

Workspace setup

{current===0&&<> } {current===1&&<>

Weekly digest

Include a weekly activity summary in the local configuration.

} {current===2&&<>

Review your draft

Workspace
{name}
Weekly digest
{digest?'Enabled':'Disabled'}

No workspace or notification subscription is created.

}
{current>0&&} {current<2 ? : }

{prepared?'Configuration prepared locally. No account created.':''}

; } createRoot(document.getElementById('root')).render(); ``` Riferimento del codice - L’esempio per React 18 installa intenzionalmente @douyinfe/semi-ui; React 19 richiede il pacchetto -19 indicato nella Quick Start. - Nei bundler supportati, JavaScript dei componenti Semi importano gli CSS correlati; la configurazione predefinita non richiede di aggiungere un passaggio inesistente per importare un foglio di stile globale. - L’esempio HTML incorporato gestisce esplicitamente lo spostamento del focus; nel prodotto, riproduci questo comportamento intorno ai componenti nativi. ## Configurazione dell’agente per il sistema di progettazione sistema di design Semi Design ### Punto di partenza per l’implementazione Scegli un ramo di dipendenze. L’esempio usa React 18. La Quick Start attuale specifica che, in Vite/Webpack/Rspack, JavaScript dei componenti importa il relativo CSS; la compilazione del tema richiede strumenti aggiuntivi. ``` npm install react@18 react-dom@18 @douyinfe/semi-ui # For a React 19 application instead: # npm install react@19 react-dom@19 @douyinfe/semi-ui-19 ``` ### Un prompt per il tuo progetto ``` Usa Steps di base di Semi con Input e Switch controllati. Scegli il pacchetto React corrispondente alla major React installata. Convalida prima di procedere, conserva i dati tornando indietro con Precedente e mostra una configurazione locale finale senza fingere che sia stato creato un account. ``` ## Fonti e ambito del sistema di progettazione sistema di design Semi Design Riferimento indipendente a OpenDesign. Esempio originale dell’area di lavoro; non viene creato alcun account né attivata alcuna iscrizione alle notifiche. - Guida rapida Suddivisione del pacchetto React-major e caricamento di CSS. - Variabili del tema Spaziature, dimensioni e corpi del carattere effettivi. - Mixin tipografici Altezze di riga definite. - Ruoli a runtime Ruoli colore, raggi e selettori del tema. - Canali della palette Valori risolti dei canali chiari e scuri. - Passaggi Aspetto consigliato e stato corrente. - Input Callback e limiti di validazione. - Switch Stato controllato delle preferenze. - Button Ruolo e trattamento visivo. ## Risorse correlate al sistema di design Semi Design ### Semrush Intergalactic Una guida Intergalactic con token semantici e per grafici aggiornati, controlli nativi per i filtri, confronto a scala fissa, dettagli dell’elemento selezionato e un fixture completo e riproducibile. ### ServiceNow Horizon Esplora i riferimenti esatti a spaziature, raggi e tipografia di Horizon Workspace attraverso un flusso completo di revisione delle richieste locali, con conservazione delle bozze, convalida, filtri di stato e recupero. ### ServiceTitan Anvil Rendi concreto Anvil2 con il suo modello di token a tre livelli, valori dei ruoli verificati per temi chiari e scuri e un’interazione completa per l’assegnazione dei servizi, con stati sincronizzati di tecnico, orario e revisione. - [Riferimento per l’implementazione](https://semi.design/en-US/navigation/steps) - [Fonte](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/variables.scss) - [Fonte](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_font.scss) - [Fonte](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/global.scss) - [Fonte](https://semi.design/en-US/navigation/steps) - [Fonte](https://semi.design/en-US/input/input) - [Fonte](https://semi.design/en-US/input/switch) - [Leggi la specifica di supporto](https://semi.design/en-US/start/getting-started) - [Leggi la specifica di supporto](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/variables.scss) - [Leggi la specifica di supporto](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_font.scss) - [Leggi la specifica di supporto](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/global.scss) - [Leggi la specifica di supporto](https://semi.design/en-US/navigation/steps) - [Leggi la specifica di supporto](https://semi.design/en-US/input/input) - [Leggi la specifica di supporto](https://semi.design/en-US/input/switch) - [Leggi la specifica di supporto](https://semi.design/en-US/basic/button) - [Riferimento del codice](https://semi.design/en-US/navigation/steps) - [Guida rapida Suddivisione del pacchetto React-major e caricamento di CSS.](https://semi.design/en-US/start/getting-started) - [Variabili del tema Spaziature, dimensioni e corpi del carattere effettivi.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/variables.scss) - [Mixin tipografici Altezze di riga definite.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_font.scss) - [Ruoli a runtime Ruoli colore, raggi e selettori del tema.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/global.scss) - [Canali della palette Valori risolti dei canali chiari e scuri.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_palette.scss) - [Passaggi Aspetto consigliato e stato corrente.](https://semi.design/en-US/navigation/steps) - [Input Callback e limiti di validazione.](https://semi.design/en-US/input/input) - [Switch Stato controllato delle preferenze.](https://semi.design/en-US/input/switch) - [Button Ruolo e trattamento visivo.](https://semi.design/en-US/basic/button)