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 casoPacoteO que vem
Página HTML, PHP, Django, Flask, Vue, Angular ou outro framework sem React@semec/ds-cssClasses .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-elementsWeb 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-tokensVariáveis CSS (tokens.css), base opcional (base.css), fonte Poppins (fonts.css).
Android, iOS, Figma, back-end, PDF ou e-mail@semec/ds-tokenstokens.json (DTCG), tokens em JS, colors.xml e dimens.xml, SemecTokens.swift, JSON do Tokens Studio.
App React@semec/ds + Tailwind v4Componentes React acessíveis prontos. É o caminho da Introdução.
App sem React que já usa Tailwind v4@semec/ds (variante lite) + Tailwind v4Tokens 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-css

Num 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.

ComponenteClassesObservação
Botão.semec-btn + --primary, --secondary, --outline, --ghost, --destructive, --success, --link; tamanhos --sm, --md (padrão), --lg e --iconEstado 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-fieldErro por [aria-invalid="true"] no campo. .semec-form-field é o wrapper com o espaçamento do FormField.
Escolha.semec-checkbox, .semec-radio, .semec-choiceEstilizam 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, __descriptionJunte ícone ou título ao texto: cor sozinha não comunica.
Cabeçalho.semec-header, __brand, __divider, __org, __separator, __service, __nav, __linkLink atual com [aria-current="page"].
Rodapé.semec-footer, __content, __section, __title, __links, __link, __bottom
Pular para o conteúdo.semec-skip-linkPrimeiro elemento focável da página, apontando para o <main>.
Tabela.semec-table, __wrapper, __captionO __wrapper rola na horizontal: use role="region", tabindex="0" e aria-label.
Resumo de erros.semec-error-summary, __title, __list, __linkO 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, __closeSó a aparência. Mostrar, anunciar (role="status") e fechar ficam com o app.
Títulos.semec-heading + --1 a --6A escala do Heading. Mantenha a ordem h1 → h2 → h3 no HTML.
Diálogo.semec-dialog + --alert; __header, __title, __description, __footer, __closeNo <dialog> nativo. Comportamento: <semec-dialog> do @semec/ds-elements.
Abas.semec-tabs, __list, __trigger, __panelComportamento: <semec-tabs>.
Combobox.semec-combobox, __input, __listbox, __option, __empty, __checkA partir de um <select> nativo. Comportamento: <semec-combobox>.
Menu.semec-menu, __item, __separator, __labelSem JavaScript, os itens ficam visíveis no fluxo. Comportamento: <semec-menu>.
Acordeão.semec-accordion, __item, __header, __trigger, __panel, __iconSem JavaScript, os painéis ficam abertos. Comportamento: <semec-accordion>.
Utilitário.semec-sr-onlyTexto 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