Crea una configuración secuencial del espacio de trabajo con los Steps básicos recomendados por Semi, Input y Switch controlados, tokens de tema reales y una elección explícita entre los paquetes React 18 y React 19.
Interpretación sin conexión de HTML de las escalas del tema Semi y el comportamiento de Steps/Input/Switch. El ejemplo nativo de React es independiente. · Referencia de implementación
02
Referencia de diseño del sistema de diseño Semi Design
Documentación oficial de Semi y captura de SCSS del tema predeterminado. Los nombres $ son constantes de Sass en tiempo de compilación; los nombres --semi-* son variables de CSS en tiempo de ejecución. Los datos del flujo de trabajo de la aplicación son originales.
Sistema de diseño Semi Design: elige el paquete para la versión principal real de React
El sufijo cambia la integración
La guía de inicio rápido actual de Semi diferencia el paquete para React 19 del que se usa en versiones anteriores de React. Este ejemplo elige explícitamente React 18 y @douyinfe/semi-ui. Para cambiar a React 19, hay que usar las importaciones de @douyinfe/semi-ui-19 y elegir la dependencia correspondiente, tal como se documenta.
Los empaquetadores compatibles cargan los CSS relacionados desde el JavaScript del componente. Los cambios en tiempo de compilación, como un prefijo personalizado, la compilación de temas o las capas de CSS, requieren consideraciones de herramientas específicas. No conviertas un ejemplo de importación básica en una afirmación de que todas las personalizaciones de tema funcionan sin configuración.
Sistema de diseño Semi Design: las escalas Sass con nombre concretan la densidad
Usa las alturas de controles publicadas de 24, 32 y 40px
Las tres constantes de altura de controles de Semi son 24, 32 y 40px. Los valores de espaciado con nombre abarcan de 2 a 40px con una progresión no uniforme. Un campo predeterminado del asistente puede usar 12px de espacio para la ayuda y 24px de separación respecto de la sección siguiente, sin introducir un nuevo sistema de espaciado.
Estos valores son constantes de Sass, no variables disponibles automáticamente en tiempo de ejecución. El ejemplo usa sus dimensiones resueltas en el código original de la página CSS. Esta diferencia importa cuando un desarrollador quiere aplicar un tema al diseño en tiempo de ejecución en lugar de volver a compilar una hoja de estilos.
Sistema de diseño Semi Design: usa pares reales de tamaño y altura de línea
El texto del cuerpo y los encabezados tienen ritmos distintos
El mixin regular combina texto de 14px con una altura de línea de 20px; el mixin pequeño combina 12 con 16. El encabezado 3 es de 24/32 y el encabezado 1, de 32/44. El título breve de un asistente puede usar el primero y reservar el segundo para una jerarquía de página más marcada.
La familia tipográfica de origen empieza con Inter, seguida de fuentes alternativas para plataformas y caracteres CJK. La vista previa sin conexión usa una pila de fuentes disponible en el sistema y no afirma haber descargado una fuente concreta. Mantén breves los nombres de los pasos para que sigan siendo comprensibles cuando la barra de pasos se ajuste en una ventana gráfica estrecha.
Sistema de diseño Semi Design: los roles del tema y los canales de la paleta son independientes
Usa los roles resueltos en el CSS de la aplicación
El rol primario combina una variable de canal de la paleta con rgba. Usar --semi-color-primary es adecuado para una propiedad de color habitual; una lista de canales sin procesar, como --semi-blue-5, no es un color CSS completo. Las paletas claras y oscuras cambian esos valores de canal.
Los roles de texto también usan opacidad. El texto secundario no es simplemente un código hexadecimal arbitrariamente más claro, y el texto deshabilitado no debe reutilizarse para información de ayuda importante. El asistente mantiene un tono neutro en el mensaje de finalización porque preparar la configuración no crea una cuenta activa.
Sistema de diseño Semi Design: Steps básico comunica el progreso, no el permiso para omitir la validación
La aplicación controla las reglas de transición
Semi recomienda type="basic" para una barra de pasos sencilla. current empieza en cero; el paso actual puede tener el estado process, error u otro estado compatible. La documentación marca como obsoleta la apariencia predeterminada anterior.
El ejemplo avanza deliberadamente mediante los controles Continuar y Anterior. No vincula el clic en cada paso a setCurrent, lo que permitiría al usuario llegar a Revisar sin haber introducido un nombre. La apariencia nav, documentada por separado, no es interactiva y no debe confundirse con la navegación del asistente.
Valida el nombre antes de salir del primer paso.
Conserva el valor booleano elegido para el resumen semanal al volver a pasos anteriores.
Muestra todos los ajustes en Revisar.
Prepara la configuración local sin afirmar que ya existe una cuenta o suscripción.
Sistema de diseño Semi Design: la validación visual no valida el valor
Usa correctamente la devolución de llamada que recibe primero el valor
Semi Input invoca onChange con el valor antes que con el evento. Por tanto, el ejemplo puede pasar setName directamente. validateStatus solo cambia la apariencia; comprobar si el nombre está vacío es lógica de la aplicación y requiere una explicación visible.
En el caso del texto que activa consultas en tiempo real, la composición puede posponer las devoluciones de llamada hasta que se confirme la composición del IME. El campo del nombre del espacio de trabajo no realiza consultas en tiempo real, así que el ejemplo omite ese comportamiento opcional en lugar de presentarlo como un requisito universal.
Semi Design El sistema de diseño mantiene comprensible la preferencia junto al interruptor
Mantén el estado en el componente padre
Switch usa checked y una devolución de llamada onChange que recibe un booleano como primer argumento. La etiqueta debe explicar la preferencia, por ejemplo, Resumen semanal, mientras que el texto que la rodea debe explicar qué significa ese ajuste. Las cadenas largas para los estados activado y desactivado deben ir fuera del control pequeño; los interruptores pequeños no admiten esos tratamientos de texto en su interior.
Usa un nombre accesible claro que identifique la preferencia.
Conserva el valor de la preferencia al pasar de un paso del asistente a otro.
Muestra el valor final como texto corriente en la página de revisión.
Semi Design El sistema de diseño distingue entre el tipo y el tema de Button
Rol semántico frente a tratamiento visual
El tipo de Semi Button selecciona un rol, como primario o peligro. theme selecciona el tratamiento visual: claro, sólido, sin borde o contorneado. El ejemplo usa una acción Continue primaria y sólida, y una acción Previous más discreta, en lugar de usar incorrectamente el estilo de peligro para dar más visibilidad a un botón.
El ejemplo sin conexión mueve el foco al encabezado de la nueva sección cuando cambia el paso y lo devuelve al campo no válido si falla la validación. El diseño para móviles y la secuencia de teclado se prueban por separado del ejemplo nativo React cuya fuente se ha comprobado.
Semi Design Ejemplos de componentes del sistema de diseño
Muestra interactiva independiente completa
Guarda el documento completo como index.html y ábrelo en un navegador. Interpretación sin conexión de HTML de las escalas de tema de Semi y del comportamiento de Steps/Input/Switch. El ejemplo nativo React es independiente.
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>
Continue valida el nombre del espacio de trabajo antes de avanzar. Este documento interpreta los pasos; la entrada independiente React especifica el límite entre los paquetes React 18 y 19.
Asistente de configuración validado en tres pasos
Basic Steps registra el progreso actual; Input y Switch conservan los valores entre páginas. Continue valida el nombre y la acción final solo prepara la configuración local.
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 />);
El ejemplo React 18 instala intencionalmente @douyinfe/semi-ui; React 19 requiere el paquete -19 documentado en Inicio rápido.
En empaquetadores compatibles, el componente Semi JavaScript importa su CSS correspondiente; la configuración predeterminada no requiere añadir un paso ficticio para una hoja de estilos global.
El ejemplo integrado HTML gestiona explícitamente el movimiento del foco; reproduce ese comportamiento alrededor de los componentes nativos del producto.
04
Semi Design Configuración de agente del sistema de diseño
Punto de partida para la implementación
Elige una de las ramas de dependencias. El ejemplo usa React 18. La guía de Inicio rápido actual indica que, en Vite/Webpack/Rspack, el componente JavaScript importa su CSS correspondiente; la compilación del tema requiere herramientas adicionales.
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
Una instrucción para tu proyecto
Instrucción para el agente
Usa Basic Steps de Semi con Input y Switch controlados. Asegúrate de que el paquete React coincida con la versión principal de React instalada. Valida antes de avanzar, conserva los datos al volver con Previous y presenta una configuración local final sin fingir que se ha creado una cuenta.
05
Semi Design Fuentes y alcance del sistema de diseño
Referencia independiente de OpenDesign. Ejemplo original del espacio de trabajo; no crea ninguna cuenta ni suscripción a notificaciones.
