# Sistema de design Semi Design ## Prévia da interface do sistema de design Semi Design Valide um nome, escolha uma preferência para o resumo, revisite etapas anteriores e inspecione a configuração local final. ## Referência de design do sistema de design Semi Design Documentação oficial do Semi e captura do SCSS do tema padrão. Os nomes $ são constantes Sass avaliadas em tempo de compilação; os nomes --semi-* são variáveis CSS de tempo de execução. Os dados do fluxo de trabalho da aplicação são originais. ### Espaçamento e tamanhos dos controles | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | $height-control-small / default / large | 24 / 32 / 40px | Alturas de controle publicadas. | | $spacing-super-tight | 2px | Espaçamento mais reduzido. | | $spacing-extra-tight | 4px | Espaçamento muito reduzido. | | $spacing-tight | 8px | Espaçamento reduzido. | | $spacing-base-tight | 12px | Espaçamento compacto entre grupos. | | $spacing-base | 16px | Espaçamento padrão. | | $spacing-base-loose | 20px | Agrupamento mais espaçado. | | $spacing-loose | 24px | Espaçamento entre seções. | | $spacing-extra-loose | 32px | Separação ampla. | | $spacing-super-loose | 40px | Maior espaçamento nomeado deste conjunto. | ### Combinações tipográficas | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | font-size-small mixin | 12 / 16px | Tamanho de variables.scss; altura da linha do mixin. | | font-size-regular mixin | 14 / 20px | Texto do corpo. | | font-size-header-6 mixin | 16 / 22px | Título pequeno. | | font-size-header-4 mixin | 20 / 28px | Título da seção. | | font-size-header-3 mixin | 24 / 32px | Opção de título da página. | | font-size-header-1 mixin | 32 / 44px | Maior título nomeado. | ### Mapeamentos de funções do tema | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | --semi-color-primary | rgba(var(--semi-blue-5),1) | A paleta clara resulta em rgb(0,100,250). | | --semi-color-primary-hover | rgba(var(--semi-blue-6),1) | A paleta clara resulta em rgb(0,98,214). | | --semi-color-text-0 | rgba(var(--semi-grey-9),1) | O texto principal no tema claro resulta em rgb(28,31,35). | | --semi-color-text-2 | Grey 9 at .62 opacity in light mode | Texto secundário; no tema escuro, a opacidade é diferente. | | --semi-color-fill-0 | Grey 8 at .05 opacity in light mode | O preenchimento sutil se adapta à superfície. | | --semi-border-radius-small | 3px | Controles comuns. | | --semi-border-radius-medium | 6px | Menus e superfícies semelhantes. | | --semi-border-radius-large | 12px | Função de contêiner grande. | | --semi-border-radius-full | 9999px | Estilo em formato de pílula. | ### Contrato de Steps | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | type="basic" | Recommended simple step bar | O estilo padrão anterior está obsoleto na documentação. | | current | Zero-based number | Começa em 0. | | status | wait / process / finish / error / warning | Status da etapa atual. | | type="nav" | Non-interactive navigation appearance | Não é um atalho para um assistente clicável. | | onChange(index) | Index includes initial offset | A aplicação decide se a navegação é permitida. | ### Input e Switch | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | Input onChange | (value,event) | O primeiro argumento é o novo valor. | | Input validateStatus | default / error / warning | Apenas altera o estilo visual; não valida dados de negócio. | | Input composition | Boolean, false by default | Quando ativado, adia onChange até a confirmação da composição do IME. | | Input aria-describedby | Description ID | Associe os textos de ajuda e de erro. | ### Variantes de switch e botão | Nome / Regra | Valor / Configuração | Uso | | --- | --- | --- | | Switch checked | Controlled Boolean | Mantenha a preferência no estado do componente pai. | | Switch onChange | (checked,event) | Use o valor booleano diretamente. | | Switch aria-label | Meaningful state label | Descreva a preferência, não o controle visual. | | Switch size="small" | No checkedText / uncheckedText treatment | Mantenha os rótulos longos fora do switch. | ## Guia completo do sistema de design Semi Design Um guia prático para escolher, aplicar e avaliar este sistema em uma interface real. Orientações completas, um ponto de partida para a implementação e links para o código-fonte. ## Sistema de design Semi Design: escolha o pacote para a versão principal real React ### O sufixo altera a integração > O Quick Start atual do Semi separa o pacote React 19 daquele usado nas versões React anteriores. Este exemplo escolhe explicitamente React 18 e @douyinfe/semi-ui. Para usar React 19, é necessário adotar as importações documentadas de @douyinfe/semi-ui-19 e escolher a dependência correspondente. Os empacotadores compatíveis carregam os CSS relacionados a partir do componente JavaScript. Alterações em tempo de compilação, como prefixo personalizado, compilação de tema ou camadas CSS, exigem considerações específicas sobre as ferramentas. Não transforme um exemplo básico de importação em uma afirmação de que toda personalização de tema funciona sem configuração. Consulte a especificação de apoio ## Sistema de design Semi Design: escalas Sass nomeadas tornam a densidade concreta ### Use as alturas de controle publicadas: 24, 32 e 40px As três constantes de altura de controle do Semi são 24, 32 e 40px. Os nomes de espaçamento abrangem de 2 a 40px, com uma progressão não uniforme. Um campo padrão no assistente pode usar um espaçamento de 12px para a ajuda e uma separação de 24px até a próxima seção, sem introduzir uma nova escala de espaçamento. Esses valores são constantes Sass, não variáveis de tempo de execução automáticas. O exemplo usa as dimensões resultantes na página CSS original. Essa diferença importa quando o desenvolvedor quer aplicar um tema ao layout em tempo de execução, em vez de recompilar uma folha de estilos. Consulte a especificação de apoio ## Sistema de design Semi Design: use pares reais de tamanho e altura de linha ### O texto do corpo e os títulos têm ritmos diferentes O mixin regular combina texto de 14px com altura de linha de 20px; o mixin pequeno combina 12px com 16px. O título 3 usa 24/32 e o título 1, 32/44. Um título curto para o assistente pode usar o primeiro par, reservando o segundo para uma hierarquia de página mais marcante. A família de fontes de origem começa com Inter, seguida de fontes alternativas da plataforma e para caracteres CJK. A prévia offline usa uma pilha de fontes do sistema disponível e não afirma ter baixado uma fonte específica. Mantenha os nomes das etapas curtos para que continuem claros quando a barra de etapas quebrar em uma janela estreita. Consulte a especificação de apoio ## Sistema de design Semi Design: funções do tema e canais da paleta são coisas distintas ### Use funções resolvidas na aplicação CSS A função de cor primária envolve uma variável de canal da paleta com rgba. Usar --semi-color-primary é adequado para uma propriedade de cor comum; uma lista bruta de canais como --semi-blue-5, por si só, não é uma cor CSS completa. As paletas clara e escura alteram esses valores de canal. As funções de texto também usam opacidade. O texto secundário não é apenas um código hexadecimal qualquer mais claro, e o texto desativado não deve ser reutilizado para informações de ajuda importantes. O assistente mantém neutra a mensagem de conclusão porque preparar a configuração não cria uma conta ativa. Consulte a especificação de apoio ## Sistema de design Semi Design: Basic Steps comunica o progresso, não a permissão para ignorar a validação ### A aplicação controla as regras de transição O Semi recomenda type="basic" para uma barra de etapas simples. current começa em zero, e a etapa atual pode ter um status compatível, como process ou error. A aparência padrão antiga está marcada como obsoleta na documentação. O exemplo avança intencionalmente pelos controles Continuar e Anterior. Ele não associa cada clique em uma etapa a setCurrent, o que permitiria ao usuário chegar à Revisão sem informar um nome. A aparência nav, documentada separadamente, não é interativa e não deve ser confundida com a navegação do assistente. 1. Valide o nome antes de sair da primeira etapa. 2. Mantenha o valor booleano escolhido para o resumo semanal ao voltar. 3. Mostre todas as configurações na etapa Revisão. 4. Prepare a configuração local sem afirmar que uma conta ou assinatura já existe. Consulte a especificação de apoio ## Sistema de design Semi Design: a validação visual não valida o valor ### Use corretamente o callback que recebe o valor primeiro O Input do Semi chama onChange com o valor antes do evento. Portanto, o exemplo pode passar setName diretamente. validateStatus altera apenas a aparência; a verificação de nome vazio é uma lógica da aplicação e precisa de uma explicação visível. Para textos que acionam consultas em tempo real, a composição pode adiar os callbacks até que a composição do IME seja confirmada. O campo de nome do workspace não faz consultas em tempo real, então o exemplo omite esse comportamento opcional, em vez de tratá-lo como uma exigência universal. Consulte a especificação de apoio ## Sistema de design Semi Design: uma preferência continua clara junto ao switch ### Mantenha o estado no componente pai O Switch usa checked e um callback onChange cujo primeiro argumento é booleano. O rótulo deve explicar a preferência, por exemplo, Resumo semanal, enquanto o texto ao redor explica o significado da configuração. As opções longas de ativado e desativado devem ficar fora do controle pequeno, que não oferece suporte a esse tipo de texto interno. - Use um nome acessível e claro que identifique a preferência. - Mantenha o valor da preferência ao navegar entre as etapas do assistente. - Exiba o valor final em texto simples na página de revisão. Consulte a especificação de apoio ## Sistema de design Semi Design: type e theme do botão respondem a perguntas diferentes ### Função semântica versus aparência visual No Button do Semi, type define uma função, como primary ou danger. theme define a aparência: light, solid, borderless ou outline. O exemplo usa uma ação Continuar com aparência solid e função primary, e uma ação Anterior mais discreta, em vez de usar danger indevidamente para dar mais destaque ao botão. A demonstração offline move o foco para o título da nova seção quando a etapa muda e de volta para o campo inválido quando a validação falha. O layout para dispositivos móveis e a sequência de navegação por teclado são testados independentemente do exemplo nativo React, cuja implementação foi conferida na fonte. Consulte a especificação de apoio ## Exemplos de componentes do sistema de design Semi Design ### Exemplo interativo completo e independente Salve o documento completo como index.html e abra-o em um navegador. Interpretação offline de HTML das escalas de tema do Semi e do comportamento de Steps/Input/Switch. O exemplo nativo React é separado. ``` 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.

``` Referência de código - Continuar valida o nome do workspace antes de avançar. Este documento interpreta as etapas; a entrada React separada especifica a diferença entre os pacotes React 18 e 19. ### Assistente de configuração validada em três etapas Basic Steps acompanha o progresso atual; Input e Switch preservam os valores entre páginas. Continuar valida o nome, e a ação final apenas prepara a configuração local. ``` // 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(); ``` Referência de código - O exemplo React 18 instala intencionalmente @douyinfe/semi-ui; React 19 exige o pacote -19 documentado no Quick Start. - Nos empacotadores compatíveis, o componente JavaScript do Semi importa os CSS relacionados; a configuração padrão não exige uma etapa inventada para incluir uma folha de estilos global. - A demonstração incorporada de HTML define explicitamente o movimento do foco; reproduza esse comportamento nos componentes nativos do produto. ## Configuração do agente do sistema de design Semi Design ### Ponto de partida para implementação Escolha uma das opções de dependência. O exemplo usa React 18. O Quick Start atual informa que o componente JavaScript importa os CSS relacionados no Vite/Webpack/Rspack; a compilação de temas exige ferramentas adicionais. ``` 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 ``` ### Um prompt para seu projeto ``` Use Steps básico do Semi com Input e Switch controlados. Combine o pacote React com a versão principal instalada do React. Valide antes de avançar, preserve os dados ao voltar e apresente a configuração local final sem fingir que uma conta foi criada. ``` ## Fontes e escopo do sistema de design Semi Design Referência independente de OpenDesign. Exemplo original de workspace; nenhuma conta ou assinatura de notificações é criada. - Quick Start Divisão de pacotes por versão principal de React e carregamento de CSS. - Variáveis do tema Valores reais de espaçamento, dimensões e tamanhos de fonte. - Mixins de fontes Alturas de linha definidas. - Funções de tempo de execução Funções de cor, raios e seletores de tema. - Canais da paleta Valores resolvidos dos canais para os temas claro e escuro. - Steps Aparência recomendada e estado atual. - Input Callbacks e limites da validação. - Switch Estado controlado da preferência. - Button Função e aparência visual. ## Recursos relacionados ao sistema de design Semi Design ### Semrush Intergalactic Um guia do Intergalactic com tokens semânticos e de gráficos atuais, controles nativos de filtragem, comparação em escala fixa, detalhes do item selecionado e um conjunto de dados completo e reproduzível. ### ServiceNow Horizon Explore as referências exatas de espaçamento, raio e tipografia do Horizon Workspace em um fluxo local completo de revisão de solicitações, com retenção de rascunhos, validação, filtros de status e recuperação. ### ServiceTitan Anvil Torne o Anvil2 concreto com seu modelo de tokens em três níveis, valores de função verificados para os modos claro e escuro e uma interação completa de atribuição de serviço, com estados sincronizados de técnico, horário e revisão. - [Referência de implementação](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) - [Consulte a especificação de apoio](https://semi.design/en-US/start/getting-started) - [Consulte a especificação de apoio](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/variables.scss) - [Consulte a especificação de apoio](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_font.scss) - [Consulte a especificação de apoio](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/global.scss) - [Consulte a especificação de apoio](https://semi.design/en-US/navigation/steps) - [Consulte a especificação de apoio](https://semi.design/en-US/input/input) - [Consulte a especificação de apoio](https://semi.design/en-US/input/switch) - [Consulte a especificação de apoio](https://semi.design/en-US/basic/button) - [Referência de código](https://semi.design/en-US/navigation/steps) - [Quick Start Divisão de pacotes por versão principal de React e carregamento de CSS.](https://semi.design/en-US/start/getting-started) - [Variáveis do tema Valores reais de espaçamento, dimensões e tamanhos de fonte.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/variables.scss) - [Mixins de fontes Alturas de linha definidas.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_font.scss) - [Funções de tempo de execução Funções de cor, raios e seletores de tema.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/global.scss) - [Canais da paleta Valores resolvidos dos canais para os temas claro e escuro.](https://raw.githubusercontent.com/DouyinFE/semi-design/main/packages/semi-theme-default/scss/_palette.scss) - [Steps Aparência recomendada e estado atual.](https://semi.design/en-US/navigation/steps) - [Input Callbacks e limites da validação.](https://semi.design/en-US/input/input) - [Switch Estado controlado da preferência.](https://semi.design/en-US/input/switch) - [Button Função e aparência visual.](https://semi.design/en-US/basic/button)