Crea una configurazione sequenziale dell’area di lavoro con i componenti Steps di base consigliati da Semi, Input e Switch controllati, token tema reali e una scelta esplicita del pacchetto React 18 o React 19.
Interpretazione offline di HTML delle scale del tema Semi e del comportamento di Steps/Input/Switch. L’esempio nativo di React è separato. · Riferimento per l’implementazione
02
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.
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.
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.
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.
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.
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.
Convalida il nome prima di lasciare il primo passaggio.
Mantieni il valore booleano scelto per il riepilogo settimanale quando si torna indietro.
Mostra tutte le impostazioni nella revisione.
Prepara una configurazione locale senza dichiarare che esistano già un account o un abbonamento.
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.
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.
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.
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.
html
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Semi workspace setup interpretation</title><style>
*{box-sizing:border-box}body{margin:0;background:#f5f6f8;color:#1c1f23;font:14px/20px Inter,system-ui,sans-serif}button,input{font:inherit}button{cursor:pointer;min-height:32px;border:0;border-radius:3px;padding:6px 16px;background:rgba(46,50,56,.05);color:inherit}button.primary{background:#0064fa;color:white}button.primary:hover{background:#0062d6}button:focus-visible,input:focus-visible{outline:2px solid #0064fa;outline-offset:3px}header{padding:20px 32px;border-bottom:1px solid rgba(28,31,35,.08);background:white;display:flex;justify-content:space-between;gap:16px}header strong{font-size:16px}header span,.muted{color:#63656a}main{max-width:950px;margin:32px auto;padding:0 24px}h1{font-size:24px;line-height:32px;font-weight:600;margin:0 0 8px}h2{font-size:20px;line-height:28px;font-weight:600;margin:0 0 12px}p{margin:0 0 16px}.card{background:white;border:1px solid rgba(28,31,35,.08);border-radius:12px;overflow:hidden;margin-top:24px}.steps{padding:24px;display:flex;list-style:none;margin:0;border-bottom:1px solid rgba(28,31,35,.08);gap:12px}.steps li{flex:1;display:flex;align-items:center;gap:8px;color:#63656a;font-size:12px}.steps b{height:24px;width:24px;border-radius:50%;display:grid;place-items:center;background:#eee;flex-shrink:0}.steps [aria-current]{color:#0064fa}.steps [aria-current] b{background:#0064fa;color:white}.steps .done b{background:#eaf5ff;color:#0064fa}.workspace{display:grid;grid-template-columns:1fr 240px;min-height:300px}.panel{padding:32px}.illustration{background:#eaf5ff;display:flex;flex-direction:column;justify-content:center;padding:24px;gap:12px}.mini{background:white;box-shadow:0 6px 20px #0064fa12;border-radius:6px;padding:16px;transform:rotate(-3deg)}.mini i{display:block;height:8px;background:#eaf5ff;width:80%;margin:8px 0;border-radius:3px}.mini i:first-child{background:#0064fa;width:36%}.mini i:nth-child(3){width:55%}.mini:last-child{transform:rotate(4deg);margin-left:20px}.mini span{font-size:12px;color:#63656a}.form-label{display:block;font-weight:600;margin:20px 0 8px}input[type=text]{height:32px;background:rgba(46,50,56,.05);border:1px solid transparent;border-radius:3px;padding:5px 12px;width:100%}input[aria-invalid=true]{border-color:#d52515}.error{color:#b21b13;min-height:20px;font-size:12px;margin:8px 0}.preference{border:1px solid #eee;border-radius:6px;padding:16px;display:flex;align-items:center;justify-content:space-between;gap:20px}.preference p{margin:4px 0 0;font-size:12px}.toggle{appearance:none;width:40px;height:24px;border-radius:999px;background:#bbb;position:relative;cursor:pointer;flex-shrink:0}.toggle:checked{background:#0064fa}.toggle:before{content:'';position:absolute;left:3px;top:3px;background:white;border-radius:50%;width:18px;height:18px}.toggle:checked:before{left:19px}footer{display:flex;justify-content:space-between;padding:20px 32px;border-top:1px solid rgba(28,31,35,.08)}dl{margin:20px 0}dt{color:#63656a;font-size:12px}dd{margin:4px 0 20px;font-size:16px;font-weight:600;overflow-wrap:anywhere}#result{margin-top:16px;border-radius:6px;background:#eaf5ff;padding:16px}#result:empty{display:none}.boundary{font-size:12px;margin-top:20px;color:#63656a}h2:focus{outline:none}@media(max-width:600px){header{padding:16px}header span{display:none}main{margin:24px auto;padding:0 16px}.workspace{grid-template-columns:1fr}.illustration{display:none}.steps{padding:16px;gap:8px}.steps li{flex-direction:column;align-items:flex-start;gap:4px}.panel{padding:24px 20px}footer{padding:16px 20px;gap:12px}footer button{padding:6px 12px}}
</style><header><strong>◒ Workspace</strong><span>Configuration studio</span></header><main><h1>Make room for your team</h1><p class="muted">Three steps to prepare a workspace configuration.</p><div class="card"><ol class="steps" aria-label="Setup progress"><li><b>1</b>Name workspace</li><li><b>2</b>Choose updates</li><li><b>3</b>Review settings</li></ol><div class="workspace"><section class="panel" id="panel"></section><aside class="illustration" aria-hidden="true"><div class="mini"><i></i><i></i><i></i><span>A place for shared ideas</span></div><div class="mini"><i></i><i></i><i></i><span>Updates on your terms</span></div></aside></div><footer><button id="previous">Previous</button><button class="primary" id="next">Continue</button></footer></div><div id="result" role="status"></div><p class="boundary">Independent HTML interpretation of Semi’s theme and components. This example stores a draft only in memory; it does not create an account.</p></main><script>
let step=0,name='',digest=true;const panel=document.querySelector('#panel'),next=document.querySelector('#next'),previous=document.querySelector('#previous'),result=document.querySelector('#result');function render(focus=false){document.querySelectorAll('.steps li').forEach((el,i)=>{el.className=i<step?'done':'';el.removeAttribute('aria-current');if(i===step)el.setAttribute('aria-current','step')});previous.style.visibility=step?'visible':'hidden';next.textContent=step===2?'Prepare configuration':'Continue';if(step===0){panel.innerHTML='<h2 tabindex="-1">Name your workspace</h2><p class="muted">Choose a name your team will recognize.</p><label class="form-label" for="name">Workspace name</label><input id="name" type="text" placeholder="e.g. Studio North" autocomplete="organization" aria-describedby="help error"><p id="error" class="error" role="alert"></p><p id="help" class="muted">You can revisit this step before preparing the configuration.</p>';let input=document.querySelector('#name');input.value=name;input.oninput=()=>{name=input.value;input.removeAttribute('aria-invalid');document.querySelector('#error').textContent='';result.textContent=''};input.onkeydown=e=>{if(e.key==='Enter')next.click()}}else if(step===1){panel.innerHTML='<h2 tabindex="-1">Choose your updates</h2><p class="muted">Keep the weekly digest in your configuration, or switch it off.</p><label class="preference"><span><strong>Weekly digest</strong><p class="muted">A weekly summary of workspace activity.</p></span><input class="toggle" type="checkbox" role="switch" aria-label="Weekly digest" id="digest"></label>';let input=document.querySelector('#digest');input.checked=digest;input.onchange=()=>{digest=input.checked;result.textContent=''}}else{panel.innerHTML='<h2 tabindex="-1">Review settings</h2><p class="muted">Check the draft before preparing it.</p><dl><dt>Workspace name</dt><dd id="review-name"></dd><dt>Weekly digest</dt><dd id="review-digest"></dd></dl>';document.querySelector('#review-name').textContent=name.trim();document.querySelector('#review-digest').textContent=digest?'Enabled':'Disabled'}if(focus)panel.querySelector('h2').focus()}
next.onclick=()=>{if(step===0&&!name.trim()){document.querySelector('#error').textContent='Enter a workspace name.';let input=document.querySelector('#name');input.setAttribute('aria-invalid','true');input.focus();return}if(step<2){step++;render(true)}else result.textContent='Configuration prepared locally: '+name.trim()+' · Weekly digest '+(digest?'enabled':'disabled')+'. No account created.'};previous.onclick=()=>{step=Math.max(0,step-1);result.textContent='';render(true)};render();
</script></html>
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.
jsx
// 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 <main style={{maxWidth:760,margin:'auto',padding:24,color:'var(--semi-color-text-0)'}}>
<h1>Workspace setup</h1>
<Steps type="basic" current={current} status={error?'error':'process'}>
<Steps.Step title="Name workspace"/>
<Steps.Step title="Choose updates"/>
<Steps.Step title="Review settings"/>
</Steps>
<section style={{padding:'24px 0'}}>
{current===0&&<><label htmlFor="workspace-name">Workspace name</label>
<Input id="workspace-name" value={name} onChange={setName}
validateStatus={error?'error':'default'} aria-invalid={!!error} aria-describedby="error" />
<p id="error" role="alert">{error}</p></>}
{current===1&&<><h2>Weekly digest</h2><p>Include a weekly activity summary in the local configuration.</p>
<Switch checked={digest} onChange={setDigest} aria-label="Weekly digest"/></>}
{current===2&&<><h2>Review your draft</h2><dl><dt>Workspace</dt><dd>{name}</dd>
<dt>Weekly digest</dt><dd>{digest?'Enabled':'Disabled'}</dd></dl>
<p>No workspace or notification subscription is created.</p></>}
</section>
{current>0&&<Button onClick={()=>{setCurrent(n=>n-1);setPrepared(false);}}>Previous</Button>}
{current<2 ? <Button theme="solid" type="primary" onClick={next}>Continue</Button> :
<Button theme="solid" type="primary" onClick={()=>setPrepared(true)}>Prepare configuration</Button>}
<p role="status">{prepared?'Configuration prepared locally. No account created.':''}</p>
</main>;
}
createRoot(document.getElementById('root')).render(<WorkspaceSetup />);
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.
04
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.
bash
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
Prompt per l’agente
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.
05
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.
