Usar sem React
A identidade visual do SEMEC Design System em qualquer tecnologia: HTML, PHP, Django, Flask, Vue, Angular, Android, iOS e Figma.
Os componentes do @semec/ds são React. Para os outros sistemas da Prefeitura existem dois pacotes sem React, gerados da mesma fonte de tokens: o @semec/ds-tokens (cores, fontes e medidas em vários formatos) e o @semec/ds-css (classes CSS prontas com o mesmo visual dos componentes React).
Qual pacote usar
| Seu caso | Pacote | O que vem |
|---|---|---|
| Página HTML, PHP, Django, Flask, Vue, Angular ou outro framework sem React | @semec/ds-css | Classes .semec-* prontas (botão, campos, cartão, alerta, cabeçalho, tabela…), com tokens e base incluídos. |
| Diálogo, abas, combobox, menu ou acordeão nessas mesmas páginas | @semec/ds-elements | Web Components acessíveis que dão o comportamento (teclado, foco, ARIA) ao HTML com as classes .semec-*. Veja Web Components. |
| App com CSS próprio (ou outro kit) que só quer as cores, fontes e medidas | @semec/ds-tokens | Variáveis CSS (tokens.css), base opcional (base.css), fonte Poppins (fonts.css). |
| Android, iOS, Figma, back-end, PDF ou e-mail | @semec/ds-tokens | tokens.json (DTCG), tokens em JS, colors.xml e dimens.xml, SemecTokens.swift, JSON do Tokens Studio. |
| App React | @semec/ds + Tailwind v4 | Componentes React acessíveis prontos. É o caminho da Introdução. |
| App sem React que já usa Tailwind v4 | @semec/ds (variante lite) + Tailwind v4 | Tokens como utilitários do Tailwind (bg-primary, text-text-muted…), sem os componentes. |
O @semec/ds-css já depende do @semec/ds-tokens: instale só ele quando quiser as classes. Os dois são somente CSS e dados, sem JavaScript de comportamento. Diálogo, abas, combobox, menu e acordeão ganham comportamento com os Web Components do @semec/ds-elements; foco do resumo de erros e mostrar o toast continuam com o código do seu app.
HTML puro
Com npm
npm install @semec/ds-cssNum projeto com bundler (Vite, webpack), importe uma vez, no arquivo de entrada. O index.css traz tokens, base e classes:
import "@semec/ds-tokens/fonts.css";
import "@semec/ds-css/index.css";Sem bundler, o navegador não entende os nomes do pacote: aponte o <link> para os arquivos reais. Copie dist/semec-ds.css do @semec/ds-css, e o dist/fonts.css com a pasta dist/fonts/ do @semec/ds-tokens, para a pasta pública do site. Mantenha fonts/ ao lado do fonts.css, porque os endereços das fontes são relativos.
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/semec-ds.css">Com CDN
Use sempre uma versão fixa e o atributo integrity (SRI). Assim o navegador recusa o arquivo se o conteúdo do CDN mudar:
<link rel="stylesheet" crossorigin="anonymous"
href="https://cdn.jsdelivr.net/npm/@semec/ds-tokens@1.0.0/dist/fonts.css"
integrity="sha384-JPaBLIHnh0Pteb6nPfiQvklhUDnfvln4jCKfD1ASorqT7xYuyugBAs5ZvE32NxXb">
<link rel="stylesheet" crossorigin="anonymous"
href="https://cdn.jsdelivr.net/npm/@semec/ds-css@1.1.1/dist/semec-ds.css"
integrity="sha384-fidW0owPdsWVRx89cAJc3pdox6KepexJueUrreuoNW1MNXGhmRfddyuPv/zT6v/G">Exemplo de marcação
<a class="semec-skip-link" href="#conteudo">Pular para o conteúdo</a>
<main id="conteudo" tabindex="-1">
<h1 class="semec-heading--1">Solicitar certidão</h1>
<form novalidate>
<div class="semec-form-field">
<label class="semec-label" for="cpf">
CPF <span class="semec-label__required" aria-hidden="true">*</span>
</label>
<input class="semec-field" id="cpf" name="cpf" required
aria-describedby="cpf-hint">
<p class="semec-hint" id="cpf-hint">Somente números.</p>
</div>
<button class="semec-btn semec-btn--primary" type="submit">Enviar</button>
</form>
</main>Com erro, troque a dica pela mensagem: o campo recebe aria-invalid="true" e aria-describedby passa a apontar para o <p class="semec-error">. As regras completas estão em Mensagens de erro.
Servidor e frameworks
Em PHP, Laravel, Symfony, Django ou Flask, prefira os modelos de servidor: parciais prontas de página, cabeçalho, campo, resumo de erros, alerta e botão, com o HTML e a acessibilidade do kit e o escape já feitos.
PHP
Copie os arquivos para a pasta pública (como no HTML puro) e carregue-os no layout comum a todas as páginas:
<!-- layout.php -->
<head>
<link rel="stylesheet" href="/css/fonts.css">
<link rel="stylesheet" href="/css/semec-ds.css">
</head>
<body>
<?php include __DIR__ . '/cabecalho.php'; ?>
<main id="conteudo" tabindex="-1"><?= $conteudo ?></main>
</body>Escape tudo que vem do usuário (htmlspecialchars) antes de pôr numa mensagem de erro ou num value.
Django
Coloque fonts.css, fonts/ e semec-ds.css em static/semec/ e use a tag static no template base:
{% load static %}
<link rel="stylesheet" href="{% static 'semec/fonts.css' %}">
<link rel="stylesheet" href="{% static 'semec/semec-ds.css' %}">No widget do formulário, passe a classe pelos atributos, por exemplo forms.TextInput(attrs={"class": "semec-field"}), e marque aria-invalid quando o campo tiver erro. Depois do collectstatic, confira na aba de rede que os .woff2 respondem 200.
Flask
<link rel="stylesheet" href="{{ url_for('static', filename='semec/fonts.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='semec/semec-ds.css') }}">Vue
// main.js
import "@semec/ds-tokens/fonts.css";
import "@semec/ds-css/index.css";<template>
<div class="semec-form-field">
<label class="semec-label" for="email">E-mail</label>
<input
id="email"
v-model="email"
class="semec-field"
:aria-invalid="erro ? 'true' : undefined"
:aria-describedby="erro ? 'email-error' : undefined"
/>
<p v-if="erro" id="email-error" class="semec-error">{{ erro }}</p>
</div>
</template>Angular
Declare os estilos no angular.json, antes do CSS do app:
"styles": [
"@semec/ds-tokens/fonts.css",
"@semec/ds-css/index.css",
"src/styles.css"
]<input
class="semec-field"
id="nome"
formControlName="nome"
[attr.aria-invalid]="form.controls.nome.invalid && form.controls.nome.touched ? 'true' : null"
/>Use [attr.aria-invalid]: com null, o Angular remove o atributo quando o campo está válido.
Android, iOS e Figma
Todos saem do mesmo tokens.json, gerado do CSS do pacote. Não edite os arquivos gerados: atualize o pacote e copie de novo.
Android
Copie android/colors.xml e android/dimens.xml de node_modules/@semec/ds-tokens/dist/ para app/src/main/res/values/. Cada recurso é o token com o prefixo semec_, em snake_case (--action-primary vira semec_action_primary). Texto sai em sp, o resto em dp:
<Button
android:background="@color/semec_action_primary"
android:padding="@dimen/semec_space_4" />iOS
Adicione dist/ios/SemecTokens.swift ao alvo do app no Xcode. Ele traz as cores (SemecTokens.Colors para SwiftUI, SemecTokens.UIColors para UIKit) e as medidas (SemecTokens.Dimensions, em pontos). Os nomes seguem os tokens em camelCase: --action-primary vira actionPrimary.
Text("Enviar")
.padding(SemecTokens.Dimensions.space4)
.background(SemecTokens.Colors.actionPrimary)Figma
No plugin Tokens Studio, importe dist/figma/tokens-studio.json (Tools → Load from file). Para variáveis nativas do Figma, use a exportação do plugin para variables. Os valores são os mesmos do código, então o design e o sistema não divergem.
Classes .semec-*
Os nomes abaixo são a API pública do @semec/ds-css e seguem BEM curto: bloco .semec-x, parte __parte, variação --variacao. O visual de cada classe é testado contra o componente React equivalente.
| Componente | Classes | Observação |
|---|---|---|
| Botão | .semec-btn + --primary, --secondary, --outline, --ghost, --destructive, --success, --link; tamanhos --sm, --md (padrão), --lg e --icon | Estado desabilitado por [disabled] ou [aria-disabled="true"]. --icon exige aria-label. |
| Campos | .semec-field (input, select, textarea), .semec-label, .semec-label__required, .semec-hint, .semec-error, .semec-form-field | Erro por [aria-invalid="true"] no campo. .semec-form-field é o wrapper com o espaçamento do FormField. |
| Escolha | .semec-checkbox, .semec-radio, .semec-choice | Estilizam o input nativo; a linha .semec-choice dá o alvo de 44 px. |
| Cartão | .semec-card, __header, __title, __description, __content, __footer | |
| Alerta | .semec-alert + --info, --success, --warning, --danger; __title, __description | Junte ícone ou título ao texto: cor sozinha não comunica. |
| Cabeçalho | .semec-header, __brand, __divider, __org, __separator, __service, __nav, __link | Link atual com [aria-current="page"]. |
| Rodapé | .semec-footer, __content, __section, __title, __links, __link, __bottom | |
| Pular para o conteúdo | .semec-skip-link | Primeiro elemento focável da página, apontando para o <main>. |
| Tabela | .semec-table, __wrapper, __caption | O __wrapper rola na horizontal: use role="region", tabindex="0" e aria-label. |
| Resumo de erros | .semec-error-summary, __title, __list, __link | O foco ao enviar o formulário fica com o JavaScript do app (ou com o autofocus dos modelos de servidor). |
| Badge | .semec-badge + --default, --secondary, --outline, --success, --warning, --danger, --info | |
| Toast | .semec-toast + --info, --success, --warning, --danger; __body, __title, __description, __action, __close | Só a aparência. Mostrar, anunciar (role="status") e fechar ficam com o app. |
| Títulos | .semec-heading + --1 a --6 | A escala do Heading. Mantenha a ordem h1 → h2 → h3 no HTML. |
| Diálogo | .semec-dialog + --alert; __header, __title, __description, __footer, __close | No <dialog> nativo. Comportamento: <semec-dialog> do @semec/ds-elements. |
| Abas | .semec-tabs, __list, __trigger, __panel | Comportamento: <semec-tabs>. |
| Combobox | .semec-combobox, __input, __listbox, __option, __empty, __check | A partir de um <select> nativo. Comportamento: <semec-combobox>. |
| Menu | .semec-menu, __item, __separator, __label | Sem JavaScript, os itens ficam visíveis no fluxo. Comportamento: <semec-menu>. |
| Acordeão | .semec-accordion, __item, __header, __trigger, __panel, __icon | Sem JavaScript, os painéis ficam abertos. Comportamento: <semec-accordion>. |
| Utilitário | .semec-sr-only | Texto só para leitor de tela. |
Armadilhas
Reset em sistema existente
O index.css e o semec-ds.css incluem o base.css: zera margens, define a fonte e a cor do body, sublinha links soltos e desenha o anel de foco. Num sistema que já tem reset próprio (ou Bootstrap), isso muda telas inteiras. Nesse caso, importe só @semec/ds-tokens/tokens.css e @semec/ds-css/components.css, adote o base.css aos poucos e garanta um foco visível equivalente.
outline: 0 em CSS legado
O base.css fica numa camada (@layer base). Uma regra antiga como :focus { outline: 0 } fora de camada vence o foco do design system, mesmo carregada antes. Remova essa regra. O axe não acusa foco apagado: percorra a tela com Tab e Shift+Tab e confira o anel em cada controle (veja Foco visível).
data-surface="brand" não pinta o fundo
O atributo só troca o anel de foco para branco, para ele aparecer sobre a cor da marca. O elemento precisa ter o fundo de marca próprio, background: var(--brand-hero). Sem esse fundo, o anel branco fica sobre a página clara com contraste de 1,08:1, e o foco some.
.faixa-destaque {
background: var(--brand-hero);
color: var(--text-on-brand);
}<section class="faixa-destaque" data-surface="brand">…</section>Caminhos do pacote
Nomes como @semec/ds-css/index.css só funcionam num bundler. No <link> e no CDN, use o caminho real do arquivo dentro do pacote e fixe a versão.
Para saber mais
- README do @semec/ds-tokens e README do @semec/ds-css.
- Decisões: ADR-026 (tokens e plataformas), ADR-028 (classes
.semec-*) e ADR-027 (pacote somente ESM), no índice de ADRs. - Para agentes de IA: a skill lite resume tokens, acessibilidade e padrões de tela sem React.