Créez une configuration d’espace de travail séquentielle avec les étapes de base recommandées par Semi, un Input et un Switch contrôlés, de véritables tokens de thème et un choix explicite entre les packages React 18 et React 19.
Interprétation hors ligne de HTML, des échelles du thème Semi et du comportement de Steps/Input/Switch. L’exemple natif de React est distinct. · Référence de mise en œuvre
02
Référence de conception du système de design Semi Design
Documentation officielle de Semi et instantané SCSS du thème par défaut. Les noms $ sont des constantes Sass résolues à la compilation ; les noms --semi-* sont des variables CSS à l’exécution. Les données du flux de travail de l’application sont originales.
Système de design Semi Design : choisissez le package correspondant à la version majeure réelle de React
Le suffixe change l’intégration
Le guide de démarrage rapide actuel de Semi distingue le package React 19 de celui utilisé par les versions antérieures de React. Cet exemple choisit explicitement React 18 et @douyinfe/semi-ui. Pour passer à React 19, il faut utiliser les imports @douyinfe/semi-ui-19 et la dépendance documentés.
Les bundlers pris en charge chargent les ressources CSS associées depuis le composant JavaScript. Les modifications à la compilation, comme un préfixe personnalisé, la compilation du thème ou les couches CSS, nécessitent une configuration distincte. Ne transformez pas un exemple d’importation de base en affirmation selon laquelle toute personnalisation du thème fonctionne sans configuration.
Système de design Semi Design : les échelles Sass nommées rendent la densité concrète
Utilisez les hauteurs de contrôle publiées : 24, 32 et 40px
Les trois constantes de hauteur de contrôle de Semi sont 24, 32 et 40px. Les noms d’espacement couvrent de 2 à 40px selon une progression non uniforme. Dans l’assistant, un champ par défaut peut avoir un espacement de 12px avant le texte d’aide et être séparé de 24px de la section suivante, sans introduire une nouvelle échelle d’espacement.
Ces valeurs sont des constantes Sass, et non des variables d’exécution automatiques. Le spécimen reprend leurs dimensions résolues dans la page d’origine CSS. Cette différence compte lorsqu’un développeur souhaite appliquer un thème à une mise en page à l’exécution plutôt que de reconstruire une feuille de style.
Système de design Semi Design : utilisez des paires réelles de taille et d’interligne
Le corps de texte et les titres ont des rythmes différents
Le mixin régulier associe un texte de 14px à un interligne de 20px ; le mixin petit associe 12px à 16px. Le titre 3 est en 24/32 et le titre 1 en 32/44. Un titre court dans un assistant peut utiliser le premier, en réservant le second à une hiérarchie de page plus marquée.
La famille de polices commence par Inter, suivie de polices de remplacement pour les plateformes et les caractères CJK. L’aperçu hors ligne utilise une pile système disponible et ne prétend pas avoir téléchargé une police particulière. Gardez les noms des étapes courts pour qu’ils restent lisibles lorsque la barre d’étapes passe sur plusieurs lignes dans une fenêtre étroite.
Semi Design Les rôles du thème du système de design et les canaux de la palette sont distincts
Utilisez les rôles résolus dans l’application CSS
Le rôle principal enveloppe une variable de canal de palette avec rgba. Utiliser --semi-color-primary convient à une propriété de couleur ordinaire ; une liste brute de canaux --semi-blue-5 ne constitue pas une couleur CSS complète. Les palettes claire et sombre modifient ces valeurs de canal.
Les rôles de texte utilisent également l’opacité. Le texte secondaire n’est pas un code hexadécimal arbitrairement plus clair, et le texte désactivé ne doit pas être réutilisé pour une aide importante. L’assistant conserve un message de fin neutre, car préparer une configuration ne crée pas de compte actif.
Semi Design Basic Steps du système de design indique la progression, pas l’autorisation d’ignorer la validation
L’application définit les règles de transition
Semi recommande type="basic" pour la barre d’étapes simple. current commence à zéro, tandis que l’étape actuelle peut avoir le statut process, error ou un autre statut pris en charge. L’apparence par défaut précédente est indiquée comme obsolète dans la documentation.
L’exemple fait délibérément avancer l’utilisateur au moyen des commandes Continuer et Précédent. Il ne relie pas chaque clic sur une étape à setCurrent, ce qui permettrait d’atteindre l’étape de vérification sans nom. L’apparence nav, documentée séparément, n’est pas interactive et ne doit pas être confondue avec le routage de l’assistant.
Validez le nom avant de quitter la première étape.
Conservez la valeur booléenne choisie pour le récapitulatif hebdomadaire lors du retour à l’étape précédente.
Affichez tous les paramètres sur la page de vérification.
Préparez la configuration locale sans prétendre qu’un compte ou un abonnement existe déjà.
Semi Design La validation visuelle du système de design ne valide pas la valeur
Utilisez correctement le rappel dont le premier argument est la valeur
Semi Input appelle onChange en transmettant la valeur avant l’événement. L’exemple peut donc passer directement setName. validateStatus ne modifie que l’apparence ; la vérification du nom vide relève de la logique de l’application et doit être accompagnée d’une explication visible.
Pour les textes qui déclenchent des requêtes en direct, la composition peut différer les rappels jusqu’à la confirmation de la composition par un IME. Le champ de nom de l’espace de travail ne déclenche pas de requête en direct ; l’exemple omet donc ce comportement facultatif au lieu de le présenter comme une exigence générale.
Semi Design Un choix du système de design reste compréhensible à côté de son interrupteur
Conservez l’état dans le composant parent
Switch utilise checked et un rappel onChange dont le premier argument est un booléen. Le libellé doit expliquer la préférence, par exemple « Récapitulatif hebdomadaire », tandis que le texte environnant précise ce que signifie ce paramètre. Les textes longs pour les états activé et désactivé doivent rester à l’extérieur du petit contrôle ; les interrupteurs de petite taille ne prennent pas en charge ces textes intégrés.
Utilisez un nom accessible explicite qui identifie la préférence.
Conservez la valeur de la préférence lors du passage d’une étape à l’autre de l’assistant.
Affichez la valeur finale sous forme de texte ordinaire sur la page de vérification.
Semi Design Dans le système de design, type et theme d’un Button répondent à des questions différentes
Rôle sémantique et traitement visuel
Semi Button utilise type pour définir un rôle, tel que primary ou danger. theme définit le traitement visuel : light, solid, borderless ou outline. L’exemple utilise une action Continuer principale et pleine, ainsi qu’une action Précédent plus discrète, au lieu d’utiliser à tort danger pour rendre un bouton plus visible.
Le spécimen hors ligne déplace le focus vers le titre de la nouvelle section lorsque l’étape change, puis vers le champ invalide en cas d’échec de la validation. Sa mise en page mobile et son ordre de navigation au clavier sont testés séparément de l’exemple natif vérifié à partir des sources React.
Semi Design Exemples de composants du système de design
Exemple interactif autonome complet
Enregistrez le document complet sous le nom index.html, puis ouvrez-le dans un navigateur. Interprétation hors ligne HTML des échelles de thème Semi et du comportement de Steps/Input/Switch. L’exemple natif React est distinct.
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>
Continuer valide le nom de l’espace de travail avant de passer à l’étape suivante. Ce document interprète les étapes ; l’entrée React distincte précise la limite de package entre React 18 et 19.
Un assistant de configuration validée en trois étapes
Basic Steps suit la progression actuelle ; Input et Switch conservent les valeurs d’une page à l’autre. Continuer valide le nom, et l’action finale prépare uniquement une configuration 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’exemple React 18 installe volontairement @douyinfe/semi-ui ; React 19 nécessite le package -19 indiqué dans Quick Start.
Dans les bundlers pris en charge, le composant Semi JavaScript importe les fichiers CSS qui lui sont associés ; la configuration par défaut ne nécessite pas d’étape inventée pour une feuille de style globale.
Le spécimen HTML intégré gère explicitement le déplacement du focus ; reproduisez ce comportement autour des composants natifs dans le produit.
04
Configuration de l’agent du système de design Semi Design
Point de départ de l’implémentation
Choisissez une branche de dépendance. L’exemple utilise React 18. La version actuelle de Quick Start indique que le composant JavaScript importe les fichiers CSS associés dans Vite/Webpack/Rspack ; la compilation du thème nécessite des outils supplémentaires.
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 pour votre projet
Prompt pour l’agent IA
Utilisez les composants Steps de base de Semi avec Input et Switch contrôlés. Faites correspondre le package React à la version majeure React installée. Validez avant de passer à l’étape suivante, conservez les données lors du retour en arrière et affichez une configuration locale finale sans prétendre qu’un compte a été créé.
05
Sources et périmètre du système de design Semi Design
Référence OpenDesign indépendante. Spécimen original de l’espace de travail ; aucun compte ni abonnement aux notifications n’est créé.
