` escrito à mão: cada valor sai da escala oficial, não da memória de quem escreve.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Box } from '@1doc/1ds-vue';`
## Quando usar
Agrupar conteúdo numa superfície com respiro e fundo: painel de filtros, bloco de resumo, área destacada dentro de uma tela.
## Quando NÃO usar
Para um item de listagem com título, ações e elevação própria — use `Card`, que já tem essa anatomia. Para só distribuir filhos no eixo sem desenhar nada, use `Stack`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `padding` | `BoxSpacing` | Padding em todos os lados, na escala do DS |
| `paddingX` | `BoxSpacing` | Padding horizontal (sobrescreve padding) |
| `paddingY` | `BoxSpacing` | Padding vertical (sobrescreve padding) |
| `background` | `"none" \| "surface" \| "muted" \| "primary-light" \| "positive-light" \| "negative-light" \| "info-light"` | Fundo semântico do DS |
| `bordered` | `boolean` | Desenha borda de 1px na cor neutra |
| `radius` | `"none" \| "sm" \| "pill" \| "circular"` | Raio da borda |
| `shadow` | `"none" \| "level1" \| "level2" \| "level3"` | Elevação |
| `fullWidth` | `boolean` | Ocupa 100% da largura disponível |
| `className` | `string` | Classes CSS adicionais |
| `children` | `any` | Conteúdo da caixa. |
## Slots
- `default`
## API de eventos
`Box` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo Box
```
---
# Breadcrumb
> Breadcrumb component — navegação estrutural (trilha de páginas).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Breadcrumb } from '@1doc/1ds-vue';`
## Quando usar
Mostrar ONDE o usuário está na hierarquia do sistema e permitir subir de nível. Use em páginas com profundidade 2 ou mais.
## Quando NÃO usar
Para progresso dentro de um fluxo de etapas — use `Stepper`. Para navegar entre seções da mesma página, use `Tabs`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `ariaLabel` | `string` | Rótulo acessível do trilha. @default 'Navegação estrutural' |
| `items` | `BreadcrumbItem[]` | Lista de itens da trilha; o último é a página atual |
| `separator` | `string` | Separador entre itens (padrão '/') |
| `className` | `string` | Classes CSS adicionais |
## API de eventos
`Breadcrumb` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface BreadcrumbItem {
label: string;
href?: string;
onClick?: () => void;
}
```
## Exemplo
```vue
```
---
# Button
> Button — botão de ação com variantes, tamanhos, ícones e estado de carregamento.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Button } from '@1doc/1ds-vue';`
## Quando usar
AÇÃO que muda estado: salvar, enviar, abrir modal, confirmar. Use `variant="icon"` para ação só com ícone (sempre com `ariaLabel`).
## Quando NÃO usar
Para NAVEGAR para outra página ou recurso — use `Link`, que gera `
` e permite abrir em nova aba. A regra: se o usuário pode querer "abrir em nova aba", é `Link`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "neutral" \| "text" \| "negative" \| "negative-outlined" \| "icon"` | Variante visual: 'primary' \| 'secondary' \| 'neutral' \| 'text' \| 'negative' \| 'negative-outlined' \| 'icon' |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho do botão: 'sm' \| 'md' \| 'lg' |
| `disabled` | `boolean` | Desabilita o botão |
| `type` | `"button" \| "submit" \| "reset"` | Tipo nativo do botão: 'button' \| 'submit' \| 'reset' |
| `children` | `any` | — |
| `onClick` | `(event?: any) => void` | Callback disparado no clique |
| `className` | `string` | Classes CSS adicionais |
| `startIcon` | `IconProp` | Ícone (Font Awesome) exibido antes do texto |
| `endIcon` | `IconProp` | Ícone (Font Awesome) exibido após o texto |
| `loading` | `boolean` | Exibe o spinner de carregamento (marca o botão com aria-busy) |
| `loadingIcon` | `IconProp` | Ícone usado como spinner (padrão: faRefresh — glifo arrows-rotate) |
| `loadingPosition` | `"start" \| "end" \| "center"` | Posição do spinner: 'start' \| 'end' \| 'center' |
| `fullWidth` | `boolean` | Ocupa 100% da largura do container |
| `ariaLabel` | `string` | Descrição acessível do botão (vira `aria-label`). OBRIGATÓRIO se o botão não possuir texto visível (ex: icon-only). Caso não fornecido, o texto interno será usado. Prop camelCase (não "aria-label" com hífen): o gerador Vue do Mitosis não serializa acesso via props["aria-label"]. |
| `id` | `string` | Id nativo do botão |
| `name` | `string` | Atributo `name` nativo (participação em formulários) |
| `value` | `string` | Atributo `value` nativo (participação em formulários) |
| `form` | `string` | Id do formulário ao qual o botão pertence |
| `autoFocus` | `boolean` | Foca o botão automaticamente ao montar |
| `tabIndex` | `number` | Ordem de tabulação nativa |
## Slots
- `default`
- `end-icon`
- `start-icon`
## API de eventos
`Button` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo Button
```
---
# Card
> Componente Card — container de conteúdo com header opcional. Suporta variações de padding, sombra e efeito de hover.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Card } from '@1doc/1ds-vue';`
## Quando usar
Agrupar conteúdo relacionado num bloco com elevação: item de lista, resumo, painel. É a unidade visual padrão de listagem.
## Quando NÃO usar
Para dados tabulares comparáveis coluna a coluna — use `DataTable`. Para só organizar em colunas, use `Grid` (Card é superfície, Grid é layout).
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `hoverable` | `boolean` | Ativa o estilo de hover (elevação de sombra e realce da borda). |
| `padding` | `"none" \| "sm" \| "md" \| "lg"` | Espaçamento interno. |
| `shadow` | `"none" \| "xs" \| "sm" \| "md" \| "lg"` | Intensidade da sombra. |
| `title` | `string` | Título do header (ativa o card-header). |
| `description` | `string` | Descrição exibida abaixo do título. |
| `className` | `string` | Classes CSS adicionais. |
| `children` | `any` | Conteúdo do card. |
## Slots
- `default`
## API de eventos
`Card` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo Card
```
---
# Checkbox
> Componente Checkbox — caixa de seleção com suporte a estados marcado, indeterminado, inválido, sucesso e desabilitado.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Checkbox } from '@1doc/1ds-vue';`
## Quando usar
Opções INDEPENDENTES, onde cada uma liga/desliga sozinha, ou um aceite único ("Li e concordo"). Suporta estado indeterminado para "marcar todos" parcial.
## Quando NÃO usar
Para escolher UMA entre várias mutuamente exclusivas — use `Radio`. Para ligar/desligar uma configuração com efeito imediato, use `Switch`. Para muitas opções numa lista, use `MultiSelect`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `checked` | `boolean` | Estado marcado controlado |
| `defaultChecked` | `boolean` | Estado marcado inicial (não controlado) |
| `disabled` | `boolean` | Desabilita a caixa de seleção |
| `required` | `boolean` | Marca o campo como obrigatório |
| `indeterminate` | `boolean` | Estado indeterminado (visual) |
| `readOnly` | `boolean` | Somente leitura: o valor não muda, mas o campo continua focável e é enviado no submit. Diferente de `disabled`, que tira das duas coisas. |
| `tabIndex` | `number` | Ordem de tabulação do input nativo |
| `decorative` | `boolean` | Modo PURAMENTE VISUAL: não renderiza o input nativo (nem participa de form/foco/AT). Para indicadores de seleção dentro de widgets que já têm semântica própria (ex.: options do MultiSelect com aria-selected). |
| `invalid` | `boolean` | Estado de erro/inválido |
| `errorMessage` | `any` | Mensagem de erro abaixo do rótulo (ativa o estado inválido) |
| `success` | `boolean` | Estado de sucesso |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho: 'sm' \| 'md' \| 'lg' (nomenclatura padrão do 1DS) |
| `background` | `boolean` | Variante com fundo destacado no label |
| `name` | `string` | Atributo name do input nativo |
| `value` | `string` | Atributo value do input nativo |
| `id` | `string` | ID do input nativo |
| `label` | `string` | Texto do rótulo |
| `description` | `string` | Texto de descrição abaixo do rótulo |
| `helperText` | `string` | Texto de apoio abaixo do campo. É o nome canônico na família de campos (Input, Textarea, DatePicker, TimePicker, PhoneInput, FileInput já usam). `description` continua funcionando como apelido, para não quebrar quem já escreveu — mas o nome novo é este. |
| `ariaLabel` | `string` | Nome acessível quando não há label visível (vira aria-label no input). |
| `className` | `string` | Classes CSS adicionais |
| `onChange` | `(checked: boolean) => void` | Callback acionado ao alternar o estado (recebe o novo boolean) |
## Slots
- `error-message`
## API de eventos
`Checkbox` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
```
---
# Chips
> Chips component — rótulo interativo compacto, usado principalmente no MultiSelect e como tags removíveis.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Chips } from '@1doc/1ds-vue';`
## Quando usar
Item REMOVÍVEL que representa uma escolha já feita pelo usuário: valor selecionado dentro de um MultiSelect, filtro aplicado que pode ser desfeito, destinatário adicionado a um campo. Também serve como filter chip acionável (`selected` + `onClick`).
## Quando NÃO usar
Para rótulo apenas informativo que o usuário não remove nem aciona — use `Tag`. A regra prática: se não há `onRemove` nem `onClick`, o componente certo é `Tag`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `label` | `string` | Texto exibido no chip (obrigatório) |
| `removable` | `boolean` | Exibe o botão × para remover o chip |
| `disabled` | `boolean` | Desabilita o chip (visual esmaecido e sem interação) |
| `size` | `"sm" \| "md"` | Tamanho do chip: 'sm' \| 'md' |
| `variant` | `"default" \| "primary" \| "positive" \| "negative" \| "info"` | Variante visual: 'default' \| 'primary' \| 'positive' \| 'negative' \| 'info' |
| `selected` | `boolean` | Estado selecionado (filter chip) — vira aria-pressed |
| `className` | `string` | Classes CSS adicionais |
| `onClick` | `(event: any) => void` | Torna o chip acionável (filter chip): o label vira um transparente próprio, coexistindo com o × de remover sem nested-interactive |
| `onRemove` | `(event: any) => void` | Callback acionado ao clicar no botão de remover |
## API de eventos
`Chips` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
```
---
# ConfirmAIAction
> ConfirmAIAction — confirmação de ação sugerida por IA, escalonada por nível de risco. PREVIEW: a API pode mudar sem aviso.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { ConfirmAIAction } from '@1doc/1ds-vue';`
## Quando usar
Ação sugerida por IA que o usuário não pode desfazer sozinho, ou que dispara efeito em cascata: despachar, tramitar, arquivar, notificar o cidadão. Cascata conta como risco alto mesmo quando cada passo é reversível.
## Quando NÃO usar
Ação reversível em um clique — mantenha só o "desfazer" e não interrompa. Para confirmação que não veio de sugestão de IA, use `ConfirmDialog` direto.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `impactLabel` | `string` | Rótulo acessível do bloco de impacto. @default 'O que será afetado' |
| `open` | `any` | Diálogo aberto |
| `risk` | `"baixo" \| "medio" \| "alto"` | Nível de risco: 'baixo' \| 'medio' \| 'alto'. Determina o quanto o usuário precisa fazer para confirmar. |
| `title` | `string` | Título da ação a confirmar |
| `description` | `string` | O que a ação faz, em uma frase |
| `affected` | `string[]` | O que será afetado, item a item. Obrigatório em risco alto: é esta lista que permite ao usuário perceber que a sugestão pegou o processo errado. |
| `confirmPhrase` | `string` | Palavra que o usuário digita para confirmar em risco alto (padrão: "CONFIRMAR"). Só é exigida em risco alto. |
| `typedValue` | `string` | O que o usuário digitou (controlado pelo host) |
| `onTypedValueChange` | `(valor: string) => void` | Callback da digitação (recebe a string) |
| `confirmLabel` | `string` | Rótulo do botão de confirmar |
| `cancelLabel` | `string` | Rótulo do botão de cancelar |
| `confirmLoading` | `any` | Estado de carregamento do confirmar |
| `onConfirm` | `(event?: any) => void` | Confirmação. Só dispara quando o risco permite. |
| `onCancel` | `(event?: any) => void` | Cancelamento |
| `className` | `string` | Classes CSS adicionais LACUNA CONHECIDA: o `ConfirmDialog` não expõe `confirmDisabled`, então em risco alto o botão de confirmar continua clicável e o bloqueio acontece no handler. A tela diz isso em vez de fingir botão desabilitado. Pedido ao time do DS. |
| `children` | `any` | — |
## Slots
- `default`
## API de eventos
`ConfirmAIAction` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo ConfirmAIAction
```
---
# ConfirmDialog
> Componente ConfirmDialog — diálogo modal de confirmação. Exibe um overlay com título, descrição e dois botões (confirmar/cancelar). A variante semântica altera a cor e o ícone do topo. Renderizado inline (sem Portal), assim como o Modal do 1DS.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { ConfirmDialog } from '@1doc/1ds-vue';`
## Quando usar
Confirmar ou cancelar UMA ação, especialmente destrutiva ("Excluir este processo?"). Conteúdo é só título, mensagem e dois botões.
## Quando NÃO usar
Quando o diálogo tem formulário ou conteúdo próprio — use `Modal`. Para avisar sem exigir decisão, use `Alert` (na página) ou `Toast` (transitório).
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `open` | `boolean` | Controla a visibilidade do diálogo. |
| `title` | `string` | Título em destaque exibido no topo. |
| `description` | `string` | Descrição/apoio exibida abaixo do título. |
| `variant` | `"negative" \| "info"` | Variante semântica — altera cor do ícone e do botão primário. - "negative": ação destrutiva/irreversível (vermelho, ícone circle-exclamation). - "info": atenção/confirmação padrão (laranja de atenção, ícone triangle-exclamation). Unifica as antigas "warning" e "info" — pela decisão de 14/07 ambas já usavam o mesmo laranja (feedback-info). |
| `confirmLabel` | `string` | Texto do botão de confirmação. |
| `cancelLabel` | `string` | Texto do botão de cancelamento. |
| `confirmLoading` | `boolean` | Desabilita o botão de confirmação e exibe estado de carregamento. |
| `inline` | `boolean` | Renderiza o diálogo inline (overlay relativo, sem fixed) — útil para documentação/Storybook, onde o overlay fixed ficaria preso em containers com transform. Mesmo contrato do Modal. |
| `className` | `string` | Classes CSS adicionais aplicadas no container do diálogo. |
| `children` | `any` | Conteúdo adicional exibido abaixo da descrição. |
| `onConfirm` | `(event?: any) => void` | Callback acionado ao confirmar. |
| `onCancel` | `(event?: any) => void` | Callback acionado ao cancelar (botão, clique no overlay ou tecla Esc). |
| `closeOnEsc` | `boolean` | Permite fechar com a tecla Esc. Quando empilhado sobre um Modal, apenas o diálogo do topo da pilha reage ao Esc (o Modal por baixo não fecha). |
## Slots
- `default`
## API de eventos
`ConfirmDialog` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo ConfirmDialog
```
---
# Container
> Container — centraliza o conteúdo e limita a largura máxima. A largura vem dos breakpoints oficiais do DS, então a medida de linha fica consistente entre telas em vez de cada página escolher um `max-width` próprio. O respiro lateral acompanha o tamanho da tela.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Container } from '@1doc/1ds-vue';`
## Quando usar
Envolver o conteúdo de uma página para que ele não estique de ponta a ponta em telas largas. É o invólucro mais externo do conteúdo, abaixo do cabeçalho e da barra lateral.
## Quando NÃO usar
Dentro de um card, painel ou modal — ali a largura já está limitada pelo pai. Para distribuir filhos no eixo, use `Stack`; para uma superfície com fundo, `Box`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "xxl"` | Largura máxima, pelos breakpoints do DS |
| `gutter` | `"none" \| "xxs" \| "xs" \| "sm" \| "md"` | Respiro lateral (padding horizontal) |
| `fluid` | `boolean` | Ignora a largura máxima e ocupa tudo |
| `className` | `string` | Classes CSS adicionais |
| `children` | `any` | Conteúdo da página. |
## Slots
- `default`
## API de eventos
`Container` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo Container
```
---
# DataTable
> DataTable component — tabela de dados com ordenação, seleção e estados de loading/vazio.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { DataTable } from '@1doc/1ds-vue';`
## Quando usar
Dados TABULARES que se comparam coluna a coluna, com ordenação, seleção e paginação. Semântica de tabela para leitor de tela.
## Quando NÃO usar
Para hierarquia pai-filho — use `Tree`. Para cards em grade sem comparação coluna a coluna, use `Grid` com `Card`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `columns` | `DataTableColumn[]` | Definição das colunas |
| `data` | `Record[]` | Linhas de dados (array de objetos) |
| `loading` | `boolean` | Exibe linhas skeleton enquanto carrega |
| `emptyMessage` | `string` | Mensagem exibida quando não há dados |
| `selectable` | `boolean` | Ativa a seleção de linhas via checkbox |
| `selectedRows` | `number[]` | Índices das linhas selecionadas (controlado; relativo à página atual — para seleção estável entre páginas/ordenações use rowKey + selectedKeys) |
| `rowKey` | `string \| ((row: Record) => string \| number)` | Identidade estável da linha: nome do campo id ou função (row) => id. Quando presente, a seleção passa a operar por CHAVE (selectedKeys/onSelectKeys) em vez de índice — sobrevive a paginação e ordenação. |
| `selectedKeys` | `Array` | Chaves das linhas selecionadas (controlado; requer rowKey) |
| `density` | `"default" \| "compact"` | Densidade das células: 'default' \| 'compact' |
| `sortKey` | `string` | Chave da coluna atualmente ordenada |
| `sortDirection` | `"asc" \| "desc"` | Direção da ordenação: 'asc' \| 'desc' |
| `skeletonRows` | `number` | Número de linhas skeleton exibidas no loading |
| `className` | `string` | Classes CSS adicionais |
| `onSort` | `(key: string, direction: "asc" \| "desc") => void` | Callback ao ordenar uma coluna (recebe key e direção) |
| `onSelect` | `(selectedIndexes: number[]) => void` | Callback ao alterar a seleção (recebe array de índices) |
| `onSelectKeys` | `(selectedKeys: Array) => void` | Callback ao alterar a seleção por chave (requer rowKey) |
| `onRowClick` | `(rowIndex: number, row: Record) => void` | Callback ao clicar numa linha (recebe índice e a linha); cliques no checkbox de seleção não disparam |
## API de eventos
`DataTable` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface DataTableColumn {
key: string;
label: string;
sortable?: boolean;
width?: string;
align?: "left" | "center" | "right";
render?: (row: Record, rowIndex: number) => any;
}
```
## Exemplo
```vue
```
---
# DatePicker
> DatePicker — filtro de período "de/até" com dois meses lado a lado. O painel é renderizado num Portal e posicionado via @floating-ui/dom (não é clipado por containers com overflow; acompanha o scroll via autoUpdate). Primeiro clique define o início (e dispara onChange parcial, com `to` undefined); segundo clique define o fim e fecha o painel. Clicar numa data anterior ao início reinicia a seleção a partir dela.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { DatePicker } from '@1doc/1ds-vue';`
## Quando usar
Escolher DATA em calendário. `mode="range"` cobre período (data inicial e final) no mesmo componente.
## Quando NÃO usar
Para hora — use `TimePicker`. Para data digitada livremente sem calendário, `Input` com máscara. Não existe `DateRangePicker` separado: período é `mode="range"` aqui.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `clearLabel` | `string` | Rótulo acessível do botão de limpar. @default 'Limpar período' |
| `previousMonthLabel` | `string` | Rótulo acessível do botão de mês anterior. @default 'Mês anterior' |
| `nextMonthLabel` | `string` | Rótulo acessível do botão de próximo mês. @default 'Próximo mês' |
| `mode` | `"single" \| "range"` | Modo de seleção. "single" = uma data; "range" = período de duas datas. |
| `format` | `"DD/MM/YYYY" \| "MM/DD/YYYY" \| "YYYY-MM-DD"` | Formato de exibição da data. |
| `value` | `string` | Período selecionado (modo controlado). |
| `defaultValue` | `string` | Período inicial (modo não-controlado). |
| `range` | `DateRange` | Período (modo range). |
| `defaultRange` | `DateRange` | Período inicial no modo não-controlado. |
| `min` | `string` | Data mínima selecionável (YYYY-MM-DD). |
| `max` | `string` | Data máxima selecionável (YYYY-MM-DD). |
| `label` | `string` | Label visível acima do campo. |
| `placeholder` | `string` | Texto exibido quando não há período selecionado. |
| `presets` | `DatePickerPreset[]` | Atalhos de período na coluna lateral do painel. |
| `name` | `string` | Form nativo: emite hidden inputs `${name}_from` e `${name}_to` (ISO). |
| `disabled` | `boolean` | Desabilita o campo (não abre o painel). |
| `readOnly` | `boolean` | Somente leitura (focável, mas não abre o painel). |
| `required` | `boolean` | Marca o campo como obrigatório (* no label + aria-required). |
| `invalid` | `boolean` | Ativa o estado de erro (borda vermelha + aria-invalid). |
| `error` | `boolean` | quebrar quem já usa. |
| `errorMessage` | `any` | Mensagem exibida abaixo do campo quando invalid. |
| `helperText` | `any` | Texto de ajuda exibido abaixo do campo. |
| `fullWidth` | `boolean` | Expande o campo para 100% da largura. |
| `id` | `string` | Id do trigger (base dos ids de erro/ajuda). |
| `className` | `string` | Classes CSS adicionais. |
| `ariaLabel` | `string` | Nome acessível quando não há label visível. |
| `locale` | `DateRangeLocale` | Sobrescreve meses/dias da semana (default PT-BR). |
| `onChange` | `(value: string) => void` | Callback a cada mudança do período (recebe o DateRange em ISO). |
| `onRangeChange` | `(range: DateRange) => void` | Acionado no modo range, com o período. |
## Slots
- `error-message`
- `helper-text`
## API de eventos
`DatePicker` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface DateRange {
/** Data inicial do período (YYYY-MM-DD). */
from?: string;
/** Data final do período (YYYY-MM-DD). */
to?: string;
}
```
```ts
export interface DatePickerPreset {
/** Texto do atalho (ex.: "Últimos 30 dias"). */
label: string;
/** Data inicial aplicada pelo atalho (YYYY-MM-DD). */
from: string;
/** Data final aplicada pelo atalho (YYYY-MM-DD). */
to: string;
}
```
```ts
export interface DateRangeLocale {
/** Nomes dos 12 meses (substitui o default em português). */
months?: string[];
/** Nomes curtos dos 7 dias da semana, começando no domingo. */
weekdays?: string[];
}
```
```ts
export interface DatePickerCell {
day: number;
month: "prev" | "cur" | "next";
iso: string;
}
```
## Exemplo
```vue
```
---
# Divider
> Divider component to separate content
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Divider } from '@1doc/1ds-vue';`
## Quando usar
Separar visualmente blocos de conteúdo, na horizontal ou vertical.
## Quando NÃO usar
Para dar respiro entre elementos, use espaçamento (tokens de spacing) — linha só quando a separação precisa ser explícita.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | Orientação do divider: 'horizontal' ou 'vertical' |
| `variant` | `"solid" \| "dashed" \| "dotted"` | Estilo da linha: 'solid', 'dashed', 'dotted' |
| `spacing` | `"none" \| "sm" \| "md" \| "lg"` | Espaçamento ao redor: 'none', 'sm', 'md', 'lg' |
| `thickness` | `string \| number` | Espessura da linha |
| `className` | `string` | — |
## API de eventos
`Divider` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
```
---
# Dropdown
> Dropdown component — menu de ações ancorado a um trigger. Abre por clique; fecha ao selecionar, pressionar Esc ou clicar fora. O painel é renderizado num Portal e posicionado via @floating-ui/dom.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Dropdown } from '@1doc/1ds-vue';`
## Quando usar
Menu de AÇÕES ancorado a um gatilho: "mais opções", editar, excluir, duplicar. O que sai dele são comandos, não valores de formulário.
## Quando NÃO usar
Para escolher valor de campo — use `Select` ou `MultiSelect`. Para navegação entre seções, use `Tabs`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `items` | `DropdownItem[]` | Itens do menu. |
| `placement` | `"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"` | Posição do painel: 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'. |
| `open` | `boolean` | Controla a visibilidade externamente (modo controlado). |
| `minWidth` | `number` | Largura mínima do painel em px. |
| `ariaLabel` | `string` | Rótulo acessível do menu. |
| `className` | `string` | Classes CSS adicionais. |
| `children` | `any` | — |
| `onSelect` | `(item: DropdownItem) => void` | Callback ao selecionar um item. |
| `onOpenChange` | `(open: boolean) => void` | Callback ao abrir/fechar. |
## Slots
- `default`
## API de eventos
`Dropdown` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface DropdownItem {
key: string;
label: string;
icon?: IconProp;
disabled?: boolean;
danger?: boolean;
dividerAfter?: boolean;
}
```
## Exemplo
```vue
Exemplo Dropdown
```
---
# EmptyState
> EmptyState component — estado vazio com ícone, título, descrição e ação opcional.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { EmptyState } from '@1doc/1ds-vue';`
## Quando usar
Quando NÃO HÁ dados para mostrar: lista vazia, busca sem resultado, área ainda não configurada. Traz ícone, mensagem e ação opcional.
## Quando NÃO usar
Enquanto os dados ainda estão CARREGANDO — use `Skeleton` ou `Spinner`. Estado vazio é resposta definitiva, não espera.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `icon` | `IconProp` | Ícone FontAwesome: objeto importado (recomendado — ex.: faInbox de free-solid-svg-icons), nome ('inbox') ou par ['far','inbox']. Nomes/pares exigem registro prévio na library. Decorativo (aria-hidden). |
| `title` | `string` | Título principal do estado vazio (obrigatório) |
| `description` | `string` | Texto de apoio exibido abaixo do título |
| `actionLabel` | `string` | Rótulo do botão de ação (exibido junto com onAction) |
| `onAction` | `() => void` | Callback acionado ao clicar no botão de ação |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho do bloco: 'sm' \| 'md' \| 'lg' |
| `className` | `string` | Classes CSS adicionais |
## API de eventos
`EmptyState` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
```
---
# FileInput
> FileInput component — campo de upload com drag-and-drop e lista de arquivos.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { FileInput } from '@1doc/1ds-vue';`
## Quando usar
Enviar arquivo, por seleção ou arrastar-e-soltar, com lista de progresso por arquivo.
## Quando NÃO usar
Para exibir arquivos JÁ enviados sem enviar novos, monte a lista na aplicação — este componente é sobre o envio.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `accept` | `string` | Tipos aceitos (ex.: ".pdf,.docx") |
| `multiple` | `boolean` | Permite selecionar múltiplos arquivos |
| `maxSize` | `number` | Tamanho máximo em bytes (exibido como dica na variante base) |
| `disabled` | `boolean` | Desabilita a seleção de arquivos |
| `variant` | `"base" \| "card"` | Variante visual: 'base' (linha) \| 'card' (preview visual) |
| `label` | `string` | Rótulo exibido acima do campo |
| `files` | `FileInputFile[]` | Arquivos atualmente listados (controlado) |
| `name` | `string` | Nome do campo no submit de form nativo. Com name, os File selecionados/arrastados são mantidos no input nativo (via DataTransfer) e entram no FormData; a remoção pela lista remove também do input (índices alinhados com a ordem de seleção). Sem name, comportamento anterior (input sempre limpo). |
| `invalid` | `boolean` | Marca o campo como invalido (borda de erro + aria-invalid) |
| `errorMessage` | `string` | Mensagem exibida abaixo do campo quando invalid |
| `helperText` | `string` | Texto de ajuda exibido abaixo do campo |
| `className` | `string` | Classes CSS adicionais |
| `onChange` | `(files?: File[]) => void` | Callback ao selecionar/soltar arquivos (recebe array de File) |
| `onRemove` | `(index?: number) => void` | Callback ao remover um arquivo (recebe o índice) |
## API de eventos
`FileInput` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface FileInputFile {
name: string;
size: number;
progress?: number;
status?: "uploading" | "completed" | "error";
error?: string;
}
```
## Exemplo
```vue
```
---
# Grid
> Sistema de layout em colunas responsivas.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Grid } from '@1doc/1ds-vue';`
## Quando usar
Distribuir conteúdo em COLUNAS responsivas: formulário de 2 colunas, galeria de cards, layout de página.
## Quando NÃO usar
Para dados tabulares com cabeçalho e ordenação — use `DataTable`. Grid é layout, não tabela, e não tem semântica de tabela.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `alignItems` | `"flex-start" \| "center" \| "flex-end" \| "stretch" \| "baseline"` | — |
| `children` | `any` | — |
| `container` | `boolean` | — |
| `direction` | `"row" \| "row-reverse" \| "column" \| "column-reverse"` | — |
| `item` | `boolean` | — |
| `justifyContent` | `"flex-start" \| "center" \| "flex-end" \| "space-between" \| "space-around" \| "space-evenly"` | — |
| `lg` | `boolean \| number \| "auto"` | — |
| `md` | `boolean \| number \| "auto"` | — |
| `sm` | `boolean \| number \| "auto"` | — |
| `spacing` | `"quarck" \| "nano" \| "xxxs" \| "xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxl" \| "xxxl" \| "huge" \| "giant"` | Sufixo do token de espaçamento (--umds-primitive-spacing-*) usado como gap — NÃO é valor CSS cru |
| `wrap` | `"nowrap" \| "wrap" \| "wrap-reverse"` | — |
| `xl` | `boolean \| number \| "auto"` | — |
| `xxl` | `boolean \| number \| "auto"` | — |
| `xs` | `boolean \| number \| "auto"` | — |
| `className` | `string` | — |
| `style` | `any` | Atributos HTML repassados ao elemento raiz (style, data-*, aria-*…). |
| `id` | `string` | — |
## Slots
- `default`
## API de eventos
`Grid` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
Exemplo Grid
```
---
# Icon
> Componente de ícone (Font Awesome) do 1DS — recebe o ícone como objeto importado do pacote Font Awesome e o desenha como SVG. Tamanho vem da escala do DS (`size`) ou de um valor explícito (`customSize`), e a cor vem de uma `variant` semântica ou de `inherit`, que faz o ícone assumir a cor do texto ao redor — é o modo usado dentro de botões e campos.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Icon } from '@1doc/1ds-vue';`
## Quando usar
Qualquer ícone. Receba o ícone como objeto importado do Font Awesome. Ícone decorativo precisa de `aria-hidden`; ícone que carrega significado precisa de rótulo.
## Quando NÃO usar
Nunca use `` inline nem webfont direto — quebra o tamanho, a cor herdada e o tema.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `icon` | `IconProp` | — |
| `transform` | `string \| Transform` | — |
| `symbol` | `FaSymbol` | — |
| `mask` | `IconProp` | — |
| `maskId` | `string` | — |
| `title` | `string` | Rótulo acessível para ícone SEMÂNTICO (que transmite informação sozinho). Gera + aria-labelledby no <svg> via svg-core — nesse caso o svg NÃO recebe aria-hidden (e o consumidor não deve aplicá-lo no wrapper). Sem title, o svg-core marca o svg com aria-hidden="true" (decorativo). |
| `size` | `"sm" \| "md" \| "lg"` | — |
| `customSize` | `string` | — |
| `variant` | `"primary" \| "secondary" \| "neutral" \| "inherit"` | — |
| `children` | `any` | — |
## Slots
- `default`
## API de eventos
`Icon` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Icon variant="primary" size="sm" >Exemplo Icon</Icon>
</template>
<script setup>
import { Icon } from '@1doc/1ds-vue';
</script>
```
---
# Input
> Componente Input — campo de texto de linha única com rótulo, ícone à esquerda, botões de ação à direita, estados de erro/desabilitado/somente leitura e alternância de visibilidade para senhas.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Input } from '@1doc/1ds-vue';`
## Quando usar
Entrada de texto de UMA linha: nome, e-mail, número, busca. É o campo padrão quando o dado é curto e livre.
## Quando NÃO usar
Para texto longo de várias linhas — use `Textarea`. Para telefone com DDI e bandeira, use `PhoneInput`. Para data use `DatePicker`, para hora `TimePicker`, para arquivo `FileInput`. Para escolher de uma lista fechada, use `Select`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `id` | `string` | ID do input nativo (gerado automaticamente se omitido) |
| `label` | `any` | Rótulo do campo (texto ou nó customizado) |
| `type` | `"text" \| "password" \| "email" \| "number" \| "tel" \| "url" \| "search"` | Tipo do input: 'text' \| 'password' \| 'email' \| 'number' \| 'tel' \| 'url' \| 'search' |
| `name` | `string` | Atributo name do input nativo |
| `value` | `string` | Valor controlado |
| `defaultValue` | `string` | Valor inicial (não controlado) |
| `placeholder` | `string` | Texto exibido quando o campo está vazio |
| `helperText` | `any` | Texto de ajuda exibido abaixo do campo |
| `invalid` | `boolean` | Marca o campo como invalido sem exigir mensagem. Soma-se a presenca de `errorMessage`: qualquer um dos dois liga o estado de erro. |
| `errorMessage` | `any` | Mensagem de erro (ativa o estado de erro) |
| `disabled` | `boolean` | Desabilita o campo |
| `readOnly` | `boolean` | Torna o campo somente leitura |
| `required` | `boolean` | Marca o campo como obrigatório (*) |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | Tamanho: 'xs' \| 'sm' \| 'md' \| 'lg' |
| `fullWidth` | `boolean` | Expande o campo para 100% da largura |
| `className` | `string` | Classes CSS adicionais |
| `ariaLabel` | `string` | Nome acessível quando não há label visível |
| `iconLeft` | `IconProp` | Ícone Font Awesome à esquerda |
| `iconsRight` | `InputAction[]` | Botões de ação com ícone à direita |
| `onChange` | `(value: string) => void` | Callback acionado ao digitar (recebe o novo valor string) |
| `onFocus` | `(event?: any) => void` | Callback de foco (recebe o evento nativo) |
| `onBlur` | `(event?: any) => void` | Callback de blur (recebe o evento nativo) |
## Slots
- `error-message`
- `helper-text`
- `label`
## API de eventos
`Input` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface InputAction {
icon: IconProp;
onClick?: (event?: any) => void;
label?: string;
tooltip?: string;
}
```
## Exemplo
```vue
<template>
<Input size="xs" />
</template>
<script setup>
import { Input } from '@1doc/1ds-vue';
</script>
```
---
# Link
> Link — âncora estilizada; renderiza <a> quando há href e <button> caso contrário (ou quando desabilitado).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Link } from '@1doc/1ds-vue';`
## Quando usar
NAVEGAR para outra página, âncora ou recurso externo. Gera `<a>` de verdade.
## Quando NÃO usar
Para ação que muda estado sem sair da página — use `Button`. Link que não leva a lugar nenhum quebra o comportamento esperado (nova aba, copiar endereço).
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `href` | `string` | URL de destino; sem href o componente renderiza como <button> |
| `target` | `string` | Target da âncora (ex.: '_blank') |
| `rel` | `string` | Rel da âncora; quando omitido com target='_blank', aplica 'noopener noreferrer' automaticamente (segurança contra reverse tabnabbing) |
| `size` | `"default" \| "small"` | Tamanho do texto: 'default' \| 'small' |
| `variant` | `"neutral" \| "primary"` | Variante de cor: 'neutral' \| 'primary' |
| `outlined` | `boolean` | Remove o sublinhado e aplica borda inferior colorida |
| `disabled` | `boolean` | Desabilita o link (sem navegação/clique) |
| `className` | `string` | Classes CSS adicionais |
| `children` | `any` | — |
| `onClick` | `(event?: any) => void` | Callback disparado no clique |
| `iconLeft` | `any` | Conteúdo (ícone) antes do texto (slot nomeado no Vue: icon-left) |
| `iconRight` | `any` | Conteúdo (ícone) após o texto (slot nomeado no Vue: icon-right) |
## Slots
- `default`
- `icon-left`
- `icon-right`
## API de eventos
`Link` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Link variant="neutral" size="default" >Exemplo Link</Link>
</template>
<script setup>
import { Link } from '@1doc/1ds-vue';
</script>
```
---
# Logo
> Marca da 1Doc.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Logo } from '@1doc/1ds-vue';`
## Quando usar
Exibir a marca do produto: cabeçalho, tela de login, rodapé. A cor acompanha o texto por `currentColor`.
## Quando NÃO usar
Para logo de parceiro ou cliente — use `<img>` da aplicação; este componente é a marca da 1Doc.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `size` | `"regular" \| "small"` | — |
| `variant` | `"default" \| "dark" \| "light"` | — |
| `className` | `string` | — |
| `style` | `any` | Atributos HTML repassados ao elemento raiz (style, data-*, aria-*…). |
| `id` | `string` | — |
## API de eventos
`Logo` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Logo variant="default" size="regular" />
</template>
<script setup>
import { Logo } from '@1doc/1ds-vue';
</script>
```
---
# Modal
> Componente Modal do 1DS — diálogo centralizado sobre um overlay escurecido, que bloqueia a página até ser fechado. Tem cabeçalho com título e botão de fechar, corpo rolável e rodapé de ações. Participa da pilha de overlays: com vários abertos, só o do topo reage ao Esc e ao clique no overlay. O foco é preso dentro do diálogo enquanto ele está aberto e volta para o elemento que o abriu ao fechar.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Modal } from '@1doc/1ds-vue';`
## Quando usar
Diálogo centralizado para uma tarefa que interrompe o fluxo e tem conteúdo próprio: formulário, detalhe de registro, wizard. Desktop-first.
## Quando NÃO usar
Para apenas confirmar ou cancelar uma ação, sem conteúdo próprio — use `ConfirmDialog`. Em mobile, ou quando o painel deve subir pela borda inferior com gesto de arraste, use `BottomSheet`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `normalModeLabel` | `string` | Rótulo acessível do controle de modo normal. @default 'Modo normal' |
| `expandLabel` | `string` | Rótulo acessível do controle de expandir. @default 'Expandir' |
| `fullscreenLabel` | `string` | Rótulo acessível do controle de tela cheia. @default 'Tela cheia' |
| `minimizeLabel` | `string` | Rótulo acessível do controle de minimizar. @default 'Minimizar' |
| `closeLabel` | `string` | Rótulo acessível do botão de fechar. @default 'Fechar' |
| `open` | `boolean` | Controla se o modal está visível |
| `variant` | `"default" \| "positive" \| "negative" \| "info"` | Variante semântica, altera o ícone e o esquema de cores. - "positive": sucesso (verde, ícone circle-check). - "negative": erro/falha (vermelho, ícone circle-exclamation). - "info": atenção (laranja, ícone triangle-exclamation). |
| `title` | `string` | Título em destaque |
| `description` | `string` | Texto de descrição/apoio |
| `confirmLabel` | `string` | Texto do botão de confirmação/ação primária |
| `cancelLabel` | `string` | Texto do botão de cancelamento/ação secundária |
| `onConfirm` | `(event?: any) => void` | Callback disparado ao clicar no botão primário |
| `onCancel` | `(event?: any) => void` | Callback disparado ao clicar no botão de cancelar ou no X |
| `onClose` | `(event?: any) => void` | Callback disparado para fechar o modal (X, overlay ou tecla Esc) |
| `hideCloseButton` | `boolean` | Oculta o botão de fechar (X) no topo direito |
| `closeOnOverlayClick` | `boolean` | Permite fechar ao clicar no overlay escuro |
| `closeOnEsc` | `boolean` | Permite fechar com a tecla Esc (apenas o overlay do topo da pilha reage) @default true |
| `size` | `"sm" \| "md" \| "lg" \| "fullscreen"` | Largura do modal. 'md' é o padrão atual (498px); 'lg' (800px) serve formulários/wizards; 'fullscreen' ocupa a tela toda. |
| `layout` | `"dialog" \| "content"` | Layout do conteúdo: - "dialog": centralizado (padrão histórico — mensagens/confirmações); - "content": alinhado à esquerda, footer à direita — formulários e wizards. |
| `className` | `string` | Classes CSS adicionais para o container do modal |
| `inline` | `boolean` | Se verdadeiro, renderiza o modal inline (sem fixed/overlay), útil para documentação |
| `windowControls` | `boolean` | Controles de janela no cabeçalho: restaurar, expandir, tela cheia e minimizar, antes do ×. É tudo ou nada — ou o modal tem só o ×, ou tem o conjunto inteiro. Ligado, o modal passa a mudar de tamanho sozinho. |
| `onMinimize` | `(event?: any) => void` | Acionado no botão minimizar. Só existe com `windowControls`. |
| `footerStart` | `any` | Região esquerda do rodapé — conteúdo de apoio que não é botão: a caixa "Urgente", um "Selecionado: 0". Os botões continuam à direita. |
| `footerSlot` | `any` | Conteúdo customizado no rodapé (região direita) |
| `children` | `any` | Conteúdo customizado no corpo |
## Slots
- `default`
- `footer-slot`
- `footer-start`
## API de eventos
`Modal` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Modal variant="default" size="sm" >Exemplo Modal</Modal>
</template>
<script setup>
import { Modal } from '@1doc/1ds-vue';
</script>
```
---
# MultiSelect
> Componente MultiSelect do 1DS — campo de seleção múltipla com busca. Os valores escolhidos aparecem como chips removíveis dentro do próprio campo, e a lista abre num painel filtrável. Implementa o padrão ARIA de combobox: o teclado fica no campo de busca e a opção ativa é apontada por `aria-activedescendant`, de modo que as opções não viram paradas de Tab.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { MultiSelect } from '@1doc/1ds-vue';`
## Quando usar
Escolher VÁRIOS valores de uma lista fechada. Os selecionados viram `Chips` removíveis dentro do campo.
## Quando NÃO usar
Para um único valor — use `Select`. Para poucas opções independentes sempre visíveis, use vários `Checkbox`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `label` | `string` | Texto do rótulo do campo |
| `description` | `string` | Texto de descrição auxiliar exibido abaixo do campo |
| `helperText` | `string` | Texto de apoio abaixo do campo. É o nome canônico na família de campos (Input, Textarea, DatePicker, TimePicker, PhoneInput, FileInput já usam). `description` continua funcionando como apelido, para não quebrar quem já escreveu — mas o nome novo é este. |
| `placeholder` | `string` | Texto exibido quando nenhuma opção está selecionada |
| `options` | `MultiSelectOption[]` | Lista de opções disponíveis |
| `value` | `Array<string \| number>` | Valores selecionados (uso controlado) |
| `defaultValue` | `Array<string \| number>` | Valores iniciais (modo não-controlado). Ignorado quando value é fornecido |
| `name` | `string` | Nome do campo no submit de form nativo — emite um input hidden por valor selecionado (padrão select multiple) |
| `searchPlaceholder` | `string` | Placeholder do campo de busca. Padrão: "Buscar..." |
| `searchAriaLabel` | `string` | Nome acessível do campo de busca (aria-label). Padrão: "Buscar". |
| `emptyLabel` | `string` | Texto exibido quando nenhuma opção está disponível/encontrada. Padrão: "Nenhum item encontrado" |
| `clearAllLabel` | `string` | Texto da ação de limpar todas as seleções no rodapé do dropdown. Padrão: "Limpar tudo" |
| `clearSelectionAriaLabel` | `string` | Nome acessível (e title) do botão de limpar seleção no campo. Padrão: "Limpar seleção" |
| `clearSearchAriaLabel` | `string` | Nome acessível do botão de limpar o texto da busca. Padrão: "Limpar busca" |
| `removeAriaLabel` | `string` | Prefixo do nome acessível do botão de remover uma tag (recebe o label da opção). Padrão: "Remover" |
| `selectedCountLabel` | `string` | Sufixo do contador de selecionados no rodapé ("N selecionado(s)"). Padrão: "selecionado(s)" |
| `disabled` | `boolean` | Desabilita o campo |
| `readOnly` | `boolean` | Somente leitura: mantém o valor visível e focável, mas impede alteração. |
| `invalid` | `boolean` | Estado de erro/inválido |
| `required` | `boolean` | Marca o campo como obrigatório (adiciona *) |
| `fullWidth` | `boolean` | Expande para a largura total do container |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho do componente |
| `errorMessage` | `string` | Mensagem de erro exibida abaixo do campo |
| `className` | `string` | Classes CSS adicionais |
| `id` | `string` | ID base dos elementos internos. Gerado automaticamente se omitido |
| `onChange` | `(value: Array<string \| number>) => void` | Disparado quando a seleção muda |
## API de eventos
`MultiSelect` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface MultiSelectOption {
/** Rótulo exibido para a opção */
label: string;
/** Valor associado à opção */
value: string | number;
[key: string]: any;
}
```
## Exemplo
```vue
<template>
<MultiSelect size="sm" />
</template>
<script setup>
import { MultiSelect } from '@1doc/1ds-vue';
</script>
```
---
# PageHeader
> PageHeader component — cabeçalho padrão de páginas com breadcrumb, título, descrição e slot de ações.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { PageHeader } from '@1doc/1ds-vue';`
## Quando usar
Cabeçalho de página: título, breadcrumb opcional e ações à direita. É a moldura padrão do topo de uma tela.
## Quando NÃO usar
Como cabeçalho de um card ou seção interna — ali use `Text` com a variante de título.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `breadcrumbLabel` | `string` | Rótulo acessível do trilha. @default 'Trilha de navegação' |
| `title` | `string` | Título da página (renderizado como <h1>) |
| `description` | `string` | Descrição opcional exibida abaixo do título |
| `breadcrumb` | `PageHeaderBreadcrumbItem[]` | Trilha de navegação; o último item é a página atual |
| `size` | `"sm" \| "md"` | Densidade do header: 'sm' reduz o título (24px → 18px) para headers mobile/compactos (achado mobile na simulação de adoção). @default 'md' |
| `className` | `string` | Classes CSS adicionais |
| `actions` | `any` | Slot de ações (botões no lado direito) |
| `onBreadcrumbClick` | `(item: PageHeaderBreadcrumbItem, index: number) => void` | Callback acionado ao clicar em item do breadcrumb |
## Slots
- `actions`
## API de eventos
`PageHeader` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface PageHeaderBreadcrumbItem {
label: string;
href?: string;
}
```
## Exemplo
```vue
<template>
<PageHeader size="sm" />
</template>
<script setup>
import { PageHeader } from '@1doc/1ds-vue';
</script>
```
---
# Pagination
> Pagination component — navegação entre páginas em 5 variantes (spec Figma): - "default": links Anterior/Próxima + campo para digitar a página + "de N". - "alternative": chevrons + campo para digitar a página + "de N". - "resumed": intervalo de itens ("1-20 de 1000") + chevrons. - "full-width": botões Anterior/Próxima outlined + lista numerada com reticências. - "bordered": mesma lista numerada dentro de um container com divisórias.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Pagination } from '@1doc/1ds-vue';`
## Quando usar
Navegar entre PÁGINAS de uma lista longa, com controle de página atual e total.
## Quando NÃO usar
Para etapas de um formulário — use `Stepper`. Para rolagem infinita, este componente não se aplica.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `ariaLabel` | `string` | Rótulo acessível do navegação de páginas. @default 'Paginação' |
| `currentPageLabel` | `string` | Rótulo acessível do página atual. @default 'Página atual' |
| `previousPageLabel` | `string` | Rótulo acessível do botão de página anterior. @default 'Página anterior' |
| `nextPageLabel` | `string` | Rótulo acessível do botão de próxima página. @default 'Próxima página' |
| `page` | `number` | Página atual (1-indexed) |
| `totalPages` | `number` | Total de páginas disponíveis |
| `variant` | `"default" \| "alternative" \| "resumed" \| "full-width" \| "bordered"` | Variante visual (default \| alternative \| resumed \| full-width \| bordered) |
| `siblingCount` | `number` | Páginas exibidas de cada lado da atual (full-width/bordered) |
| `showPrevNext` | `boolean` | Exibe os botões de página anterior/próxima |
| `pageSize` | `number` | Itens por página (variante resumed) |
| `totalItems` | `number` | Total de itens (variante resumed; default totalPages × pageSize) |
| `prevLabel` | `string` | Rótulo do botão anterior |
| `nextLabel` | `string` | Rótulo do botão próxima |
| `disabled` | `boolean` | Desabilita toda a navegação (visual esmaecido e sem interação) |
| `className` | `string` | Classes CSS adicionais |
| `onChange` | `(page: number) => void` | Callback acionado ao selecionar uma página (recebe o número da página) |
| `onPageChange` | `(page: number) => void` | Alias depreciado de onChange |
## API de eventos
`Pagination` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Pagination variant="default" />
</template>
<script setup>
import { Pagination } from '@1doc/1ds-vue';
</script>
```
---
# PhoneInput
> PhoneInput component — campo de telefone com seletor de país (bandeira + DDI) e botão de cópia do número completo.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { PhoneInput } from '@1doc/1ds-vue';`
## Quando usar
Telefone com seletor de país (bandeira + DDI) e máscara por país. Use sempre que o número puder ser internacional.
## Quando NÃO usar
Para telefone puramente nacional sem DDI, um `Input` com máscara basta e evita o seletor.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `countryLabel` | `string` | Rótulo acessível do seletor de país. @default 'Selecionar país' |
| `value` | `string` | Valor controlado (número digitado, sem DDI). |
| `defaultValue` | `string` | Valor inicial não-controlado. |
| `placeholder` | `string` | Texto exibido quando o campo está vazio. |
| `disabled` | `boolean` | Desabilita o campo. |
| `readOnly` | `boolean` | Torna o campo somente leitura. |
| `invalid` | `boolean` | Aplica o estado de erro (borda vermelha). |
| `errorMessage` | `any` | Mensagem de erro exibida abaixo do campo (ativa o estado de erro, como no Input) |
| `helperText` | `any` | Texto de ajuda exibido abaixo do campo (suprimido enquanto houver errorMessage) |
| `country` | `string` | Código ISO do país selecionado (ex.: "BR"). |
| `id` | `string` | ID do input nativo (gerado automaticamente se omitido). |
| `name` | `string` | Nome do campo no submit de form nativo — aplicado ao input tel. |
| `label` | `string` | Rótulo visível acima do campo. |
| `className` | `string` | Classes CSS adicionais. |
| `onChange` | `(value: string, country: PhoneInputCountry) => void` | Callback ao mudar o valor ou o país. |
| `onCopy` | `(value: string) => void` | Callback ao copiar o número completo. |
## Slots
- `error-message`
- `helper-text`
## API de eventos
`PhoneInput` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface PhoneInputCountry {
code: string;
flag: string;
flagUrl: string;
ddi: string;
name: string;
}
```
## Exemplo
```vue
<template>
<PhoneInput />
</template>
<script setup>
import { PhoneInput } from '@1doc/1ds-vue';
</script>
```
---
# Portal
> Utilitário que move o conteúdo para outro ponto do DOM.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Portal } from '@1doc/1ds-vue';`
## Quando usar
Renderizar conteúdo fora da hierarquia do pai, escapando de `overflow: hidden` e de contexto de empilhamento. É a base de Modal, Dropdown e dos pickers.
## Quando NÃO usar
Não é componente visual: não tem aparência própria. Se você quer um painel pronto, use `Modal`, `BottomSheet` ou `Dropdown`, que já usam Portal por dentro.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `children` | `any` | — |
| `container` | `any` | Elemento de destino do portal. Padrão: `document.body`. Útil em apps com shadow DOM, dialogs nativos ou containers de scroll próprios, onde o body não é o host adequado. |
## Slots
- `default`
## API de eventos
`Portal` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Portal >Exemplo Portal</Portal>
</template>
<script setup>
import { Portal } from '@1doc/1ds-vue';
</script>
```
---
# ProgressBar
> ProgressBar component — barra de progresso com variantes de cor e tamanhos.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { ProgressBar } from '@1doc/1ds-vue';`
## Quando usar
Progresso MENSURÁVEL, com percentual real: upload de arquivo, etapa X de Y, processamento com total conhecido.
## Quando NÃO usar
Quando não se sabe quanto falta — use `Spinner` (pontual) ou `Skeleton` (conteúdo). Para etapas nomeadas de um fluxo, use `Stepper`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `value` | `number` | Percentual de progresso (0 a 100; valores fora do intervalo são limitados) |
| `variant` | `"primary" \| "positive" \| "info" \| "negative"` | Variante de cor: 'primary' \| 'positive' \| 'info' \| 'negative' |
| `size` | `"sm" \| "md" \| "lg"` | Altura da barra: 'sm' (4px) \| 'md' (8px) \| 'lg' (12px) |
| `label` | `string` | Rótulo exibido acima da barra (também usado como aria-label) |
| `showValue` | `boolean` | Exibe o percentual à direita do rótulo |
| `animated` | `boolean` | Listras animadas enquanto o valor for menor que 100 (ativo por padrão) |
| `className` | `string` | Classes CSS adicionais |
## API de eventos
`ProgressBar` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<ProgressBar variant="primary" size="sm" />
</template>
<script setup>
import { ProgressBar } from '@1doc/1ds-vue';
</script>
```
---
# Radio
> Componente Radio — botão de opção para seleção única dentro de um grupo. Suporta estados inválido, sucesso e desabilitado, além da variante com fundo destacado (background). ⚠️ Em GRUPOS, use o modo controlado (`checked` + `onChange`) para sincronizar a seleção: no modo não controlado (`defaultChecked`), o navegador desmarca o input nativo do irmão com o mesmo `name`, mas o estado interno do componente irmão não é notificado e o indicador visual dele permanece marcado.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Radio } from '@1doc/1ds-vue';`
## Quando usar
Escolher UMA opção entre poucas (2 a 5) mutuamente exclusivas, todas visíveis ao mesmo tempo.
## Quando NÃO usar
Com mais de 5 opções, ou quando não precisam ficar visíveis — use `Select`. Para opções que se acumulam, use `Checkbox`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `checked` | `boolean` | Estado marcado controlado (recomendado em grupos) |
| `defaultChecked` | `boolean` | Estado marcado inicial (não controlado; ver aviso sobre grupos acima) |
| `disabled` | `boolean` | Desabilita o botão de opção |
| `required` | `boolean` | Marca o campo como obrigatório |
| `invalid` | `boolean` | Estado de erro/inválido |
| `errorMessage` | `any` | Mensagem de erro abaixo do rótulo (ativa o estado inválido) |
| `success` | `boolean` | Estado de sucesso |
| `background` | `boolean` | Variante com fundo destacado no label |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho: 'sm' \| 'md' \| 'lg' (nomenclatura padrão do 1DS) |
| `name` | `string` | Atributo name do input nativo (agrupa os radios) |
| `value` | `string` | Atributo value do input nativo |
| `id` | `string` | ID do input nativo |
| `label` | `string` | Texto do rótulo |
| `description` | `string` | Texto de descrição abaixo do rótulo |
| `helperText` | `string` | Texto de apoio abaixo do campo. É o nome canônico na família de campos (Input, Textarea, DatePicker, TimePicker, PhoneInput, FileInput já usam). `description` continua funcionando como apelido, para não quebrar quem já escreveu — mas o nome novo é este. |
| `ariaLabel` | `string` | Nome acessível quando não há label visível |
| `className` | `string` | Classes CSS adicionais |
| `onChange` | `(checked: boolean) => void` | Callback acionado ao alternar o estado (recebe o novo boolean) |
## Slots
- `error-message`
## API de eventos
`Radio` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Radio size="sm" />
</template>
<script setup>
import { Radio } from '@1doc/1ds-vue';
</script>
```
---
# Select
> Componente Select — campo de seleção com dropdown, busca, seleção múltipla e paginação. Abre por clique ou teclado (Enter/Espaço/Setas); fecha por Esc, clique fora ou seleção (modo simples).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Select } from '@1doc/1ds-vue';`
## Quando usar
Escolher UM valor de uma lista fechada. O valor selecionado fica visível no campo.
## Quando NÃO usar
Para escolher VÁRIOS valores — use `MultiSelect`. Para um menu de AÇÕES (editar, excluir, duplicar) em vez de valores, use `Dropdown`. Para 2 a 4 opções mutuamente exclusivas sempre visíveis, use `Radio`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `label` | `string` | Texto do rótulo do campo. |
| `description` | `string` | Texto de descrição auxiliar abaixo do campo. |
| `helperText` | `string` | Texto de apoio abaixo do campo. É o nome canônico na família de campos (Input, Textarea, DatePicker, TimePicker, PhoneInput, FileInput já usam). `description` continua funcionando como apelido, para não quebrar quem já escreveu — mas o nome novo é este. |
| `placeholder` | `string` | Texto exibido sem seleção. |
| `options` | `SelectOption[]` | Opções disponíveis. |
| `value` | `string \| number \| Array<string \| number>` | Valor selecionado (controlado). |
| `defaultValue` | `string \| number \| Array<string \| number>` | Valor inicial (não-controlado). Ignorado quando value é fornecido. |
| `name` | `string` | Nome do campo no submit de form nativo — emite um input hidden com o valor selecionado (múltiplos separados por vírgula). |
| `multiple` | `boolean` | Permite selecionar múltiplas opções. |
| `searchable` | `boolean` | Habilita campo de busca nas opções. |
| `searchPlaceholder` | `string` | Placeholder do campo de busca. Padrão: "Buscar...". |
| `searchAriaLabel` | `string` | Nome acessível do campo de busca. Padrão: "Buscar". |
| `closeSearchAriaLabel` | `string` | Nome acessível do botão de fechar a busca inline. Padrão: "Fechar busca". |
| `emptyLabel` | `string` | Texto exibido quando nenhuma opção está disponível/encontrada. Padrão: "Nenhum item encontrado". |
| `loadingLabel` | `string` | Texto exibido ao carregar mais opções na paginação. Padrão: "Carregando mais...". |
| `selectedCountLabel` | `string` | Sufixo do contador de seleção múltipla ("N selecionado(s)"). Padrão: "selecionado(s)". |
| `removeAriaLabel` | `string` | Prefixo do nome acessível do botão de remover item selecionado (recebe o label da opção). Padrão: "Remover". |
| `autoFocusSearch` | `boolean` | Foca a busca automaticamente ao abrir. |
| `disabled` | `boolean` | Desabilita o campo. |
| `readOnly` | `boolean` | Somente leitura: mantém o valor visível e focável, mas impede alteração. |
| `invalid` | `boolean` | Estado de erro/inválido. |
| `required` | `boolean` | Marca o campo como obrigatório. |
| `loading` | `boolean` | Exibe indicador de carregamento. |
| `errorMessage` | `string` | Mensagem de erro exibida abaixo do campo. |
| `fullWidth` | `boolean` | Expande para a largura total do container. |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho: 'sm' \| 'md' \| 'lg'. |
| `pagination` | `boolean` | — |
| `hasMore` | `boolean` | — |
| `onLoadMore` | `() => void` | — |
| `onSearchChange` | `(query: string) => void` | — |
| `searchVariant` | `"default" \| "inline"` | — |
| `searchDebounce` | `number` | — |
| `cache` | `boolean` | — |
| `cacheKey` | `string` | — |
| `cacheTime` | `number` | — |
| `selectionDisplay` | `"text" \| "tags" \| "list"` | — |
| `onChange` | `(value: string \| number \| Array<string \| number>) => void` | Callback com o(s) valor(es) selecionado(s). |
| `item` | `any` | — |
| `id` | `string` | ID base dos elementos internos. Gerado automaticamente se omitido. |
| `ariaLabel` | `string` | Nome acessível quando não há label visível. |
| `className` | `string` | — |
## Slots
- `item`
## API de eventos
`Select` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface SelectOption {
label: string;
value: string | number;
[key: string]: any;
}
```
## Exemplo
```vue
<template>
<Select size="sm" />
</template>
<script setup>
import { Select } from '@1doc/1ds-vue';
</script>
```
---
# SidePanel
> Painel lateral da tela, com trilho de abas. Extraído do painel da emissão e do da fila de tarefas da 1Doc, medidos no produto rodando. Os dois são a MESMA moldura: trilho de 49px sempre visível, painel de 254px que anima a largura até zero, e o conteúdo trocando por aba. Comportamento: clicar num ícone do trilho troca o conteúdo; clicar no × contrai o painel deixando só o trilho; clicar num ícone com o painel contraído expande de volta naquela aba.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { SidePanel } from '@1doc/1ds-vue';`
## Quando usar
Conteúdo de apoio da tela atual — histórico, assinaturas, pasta, fila de trabalho.
## Quando NÃO usar
Para a navegação do APLICATIVO — use `AppSidebar`. Para conteúdo que interrompe a tarefa, use `Modal` ou `BottomSheet`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `title` | `string` | Título no topo do painel. |
| `tabs` | `SidePanelTab[]` | Abas do trilho. Sem elas o trilho não é desenhado, e o painel vira um bloco simples. |
| `activeTab` | `string` | Id da aba aberta. |
| `open` | `any` | Painel expandido. @default true Tipada `any`, e não `boolean`, de propósito: o Vue aplica *boolean casting* e entrega `false` quando a prop não é passada, então `props.open !== false` nascia falso e o painel abria fechado — só no Vue. Ver `.agent/troubleshooting/vue-boolean-prop-default.md`. |
| `closable` | `any` | Mostra o botão de fechar. @default true — `any` pelo mesmo motivo de `open`. |
| `width` | `string` | Largura quando expandido. @default '254px' |
| `closeLabel` | `string` | Nome acessível do botão de fechar. @default 'Fechar o painel' |
| `railLabel` | `string` | Nome acessível do trilho. @default 'Painéis' |
| `className` | `string` | Classes CSS adicionais. |
| `onTabChange` | `(id: string) => void` | Acionado ao escolher uma aba. Recebe o id. Com o painel contraído, também é o gesto que expande. |
| `onClose` | `() => void` | Acionado no botão de fechar. |
| `header` | `any` | Conteúdo fixo abaixo do título — busca, ordenação. Não rola com o corpo. |
| `children` | `any` | Conteúdo do painel. Rola. |
## Slots
- `default`
- `header`
## API de eventos
`SidePanel` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface SidePanelTab {
/** Identificador da aba — é o que volta em `onTabChange`. */
id: string;
/** Ícone no trilho. */
icon?: IconProp;
/** Nome acessível da aba. O trilho é só ícone, então isto não é opcional na prática. */
label: string;
}
```
## Exemplo
```vue
<template>
<SidePanel >Exemplo SidePanel</SidePanel>
</template>
<script setup>
import { SidePanel } from '@1doc/1ds-vue';
</script>
```
---
# SidePanelItem
> Linha contada dentro de um `SidePanel` — ícone, nome e número. Extraído de `.trf-rail__item` da fila de tarefas da 1Doc: "Todas 31", "Atribuídas 9", "Não atribuídas 22", e as pastas abaixo.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { SidePanelItem } from '@1doc/1ds-vue';`
## Quando usar
Filtros e pastas dentro de um painel lateral, quando cada linha tem uma contagem.
## Quando NÃO usar
Para a navegação do aplicativo — use `AppNavItem` ou `AppSidebar`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `label` | `string` | Nome da linha. |
| `icon` | `IconProp` | Ícone à esquerda. |
| `count` | `string \| number` | Contagem à direita. `0` e vazio não desenham nada. |
| `countLabel` | `string` | O que a contagem significa (ex.: "tarefas"). Entra no nome acessível. |
| `active` | `boolean` | Linha selecionada. |
| `iconColor` | `string` | Cor do ícone — para pastas com cor própria. Aceita qualquer valor CSS; o produto é dono dela. |
| `disabled` | `boolean` | Desabilita a linha. |
| `onClick` | `() => void` | Acionado no clique. |
| `className` | `string` | Classes CSS adicionais. |
## API de eventos
`SidePanelItem` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<SidePanelItem />
</template>
<script setup>
import { SidePanelItem } from '@1doc/1ds-vue';
</script>
```
---
# SidePanelSearch
> Campo de busca de um `SidePanel`. Extraído da 1Doc: 30px de altura, raio 6px, fundo cinza-azulado, lupa de 12px embutida à esquerda. É menor e mais discreto que o `Input` do DS de propósito — filtra uma lista curta ao lado, não é campo de formulário.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { SidePanelSearch } from '@1doc/1ds-vue';`
## Quando usar
Filtrar o conteúdo de um painel lateral.
## Quando NÃO usar
Em formulário — use `Input`. Na barra superior — o `AppHeader` tem a busca dele.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `placeholder` | `string` | Texto de apoio. Vira também o nome acessível do campo. |
| `value` | `string` | Valor (controlado). |
| `onValueChange` | `(valor: string) => void` | Acionado a cada tecla. |
| `className` | `string` | Classes CSS adicionais. |
## API de eventos
`SidePanelSearch` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<SidePanelSearch />
</template>
<script setup>
import { SidePanelSearch } from '@1doc/1ds-vue';
</script>
```
---
# SidePanelSection
> Rótulo de grupo dentro de um `SidePanel`, com ação opcional à direita. Extraído de `.trf-rail__grupo-rot` da 1Doc: "MEUS FILTROS" com o `+` ao lado.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { SidePanelSection } from '@1doc/1ds-vue';`
## Quando usar
Separar blocos de linhas dentro de um painel lateral.
## Quando NÃO usar
Como título de seção numa página — use `Text` com a variante de título.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `label` | `string` | Texto do rótulo. É renderizado em maiúsculas pelo CSS; escreva normal. |
| `actionIcon` | `IconProp` | Ícone do botão de ação à direita (ex.: `plus`). Sem ele, não há botão. |
| `actionLabel` | `string` | Nome acessível da ação. Obrigatório quando há `actionIcon`: o botão não tem texto. |
| `onAction` | `() => void` | Acionado no botão de ação. |
| `className` | `string` | Classes CSS adicionais. |
| `children` | `any` | Conteúdo do grupo — normalmente uma lista de `SidePanelItem`. |
## Slots
- `default`
## API de eventos
`SidePanelSection` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<SidePanelSection >Exemplo SidePanelSection</SidePanelSection>
</template>
<script setup>
import { SidePanelSection } from '@1doc/1ds-vue';
</script>
```
---
# Skeleton
> Skeleton é um placeholder exibido no lugar do conteúdo real durante o carregamento. Espelha a API do `Skeleton` do PrimeVue (shape, size, width, height, borderRadius, animation).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Skeleton } from '@1doc/1ds-vue';`
## Quando usar
Espera em que já se conhece o FORMATO do conteúdo: lista de cards, linhas de tabela, bloco de texto. Desenha a silhueta do que vai chegar.
## Quando NÃO usar
Quando não há formato previsível ou a espera é curta e pontual (um botão processando) — use `Spinner`. Quando existe percentual real de progresso, use `ProgressBar`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `shape` | `"rectangle" \| "circle"` | Formato do elemento: 'rectangle' ou 'circle'. @default 'rectangle' |
| `size` | `string` | Tamanho do círculo/quadrado (sobrescreve width/height quando definido). |
| `width` | `string` | Largura do elemento. @default '100%' |
| `height` | `string` | Altura do elemento. @default '1rem' |
| `borderRadius` | `string` | Border radius do elemento. Quando não informado, usa o valor do tema. |
| `animation` | `"wave" \| "none"` | Tipo de animação: 'wave' ou 'none'. @default 'wave' |
| `className` | `string` | — |
## API de eventos
`Skeleton` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Skeleton />
</template>
<script setup>
import { Skeleton } from '@1doc/1ds-vue';
</script>
```
---
# Spinner
> Spinner component for loading states
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Spinner } from '@1doc/1ds-vue';`
## Quando usar
Espera INDETERMINADA e localizada, sem formato conhecido: botão processando, painel carregando, área pequena.
## Quando NÃO usar
Para carregamento de conteúdo com formato conhecido — use `Skeleton`, que comunica melhor o que vem. Quando há percentual, use `ProgressBar`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho do spinner: 'sm' (16px), 'md' (24px), 'lg' (32px) |
| `variant` | `"primary" \| "secondary" \| "neutral"` | Variante de cor: 'primary', 'secondary', 'neutral' |
| `label` | `string` | Label acessível para leitores de tela |
| `className` | `string` | — |
| `id` | `string` | — |
## API de eventos
`Spinner` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Spinner variant="primary" size="sm" />
</template>
<script setup>
import { Spinner } from '@1doc/1ds-vue';
</script>
```
---
# Stack
> Stack — empilha os filhos com espaçamento da escala do DS. Existe para eliminar o `style={{ display: "flex", gap: 16 }}` escrito à mão, que é por onde o design system vaza: o 16 sai da cabeça de quem escreve, não do token. Aqui o `gap` só aceita degraus da escala oficial.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Stack } from '@1doc/1ds-vue';`
## Quando usar
Empilhar elementos com espaçamento consistente: campos de um formulário, botões de uma barra de ações, itens de uma lista. É o jeito certo de dar respiro sem escrever CSS.
## Quando NÃO usar
Para layout em COLUNAS que se alinham entre si — use `Grid`. Para uma caixa com padding e fundo, use `Box`. Stack só distribui no eixo, não desenha nada.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `direction` | `"vertical" \| "horizontal"` | Eixo do empilhamento: 'vertical' (padrão) \| 'horizontal' |
| `gap` | `StackSpacing` | Espaço entre os filhos, na escala do DS |
| `align` | `"start" \| "center" \| "end" \| "stretch" \| "baseline"` | Alinhamento no eixo transversal |
| `justify` | `"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"` | Distribuição no eixo principal |
| `wrap` | `boolean` | Permite quebrar em várias linhas |
| `inline` | `boolean` | Usa display inline-flex em vez de flex |
| `className` | `string` | Classes CSS adicionais |
| `children` | `any` | Conteúdo empilhado. |
## Slots
- `default`
## API de eventos
`Stack` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Stack >Exemplo Stack</Stack>
</template>
<script setup>
import { Stack } from '@1doc/1ds-vue';
</script>
```
---
# StatCard
> StatCard — cartão de indicador: um número grande, o que ele significa, e opcionalmente a variação. É o bloco de painel: "12 processos parados", "86% no prazo", "3 aguardando assinatura". No protótipo da 1Doc aparece em 10 telas — caixa de entrada, processos, visão geral, fila de assinaturas — sempre remontado à mão, com nome de classe diferente em cada módulo. Duas decisões que valem saber: - **O número vem antes do rótulo no HTML**, e é assim que o leitor de tela anuncia. Ler "12, processos parados" é a ordem certa; o inverso obriga a pessoa a segurar o rótulo na cabeça esperando o valor. - **A variação não depende só da cor.** Sobe e desce vêm com seta, porque verde e vermelho sozinhos não comunicam para quem não distingue cores.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { StatCard } from '@1doc/1ds-vue';`
## Quando usar
Painel e visão geral: destacar UMA medida por cartão, em linha com outras. O número é o protagonista da leitura.
## Quando NÃO usar
Para listar dados comparáveis — use `DataTable`. Para um bloco com título e conteúdo livre, `Card`. Para um rótulo curto de estado, `Tag` ou `Badge`. Não empilhe vários números num StatCard só: um cartão, uma medida.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `value` | `string \| number` | O número ou medida em destaque |
| `label` | `string` | O que o número significa |
| `icon` | `IconProp` | Ícone Font Awesome como objeto importado |
| `variant` | `"neutral" \| "primary" \| "positive" \| "negative" \| "info"` | Cor de apoio do ícone e da variação |
| `trend` | `"up" \| "down" \| "flat"` | Direção da variação: 'up' \| 'down' \| 'flat' |
| `trendLabel` | `string` | Texto da variação (ex.: '12% em relação ao mês anterior') |
| `description` | `string` | Texto auxiliar abaixo do rótulo |
| `align` | `"start" \| "center"` | Alinhamento do conteúdo |
| `className` | `string` | Classes CSS adicionais |
| `onClick` | `() => void` | Torna o cartão acionável (vira botão) |
## API de eventos
`StatCard` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<StatCard variant="neutral" />
</template>
<script setup>
import { StatCard } from '@1doc/1ds-vue';
</script>
```
---
# Stepper
> Stepper component — indicador de progresso em etapas (horizontal ou vertical).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Stepper } from '@1doc/1ds-vue';`
## Quando usar
Progresso em etapas NOMEADAS de um fluxo: cadastro em 3 passos, wizard. Mostra concluído, atual e pendente.
## Quando NÃO usar
Para progresso percentual sem etapas nomeadas — use `ProgressBar`. Para páginas de lista, use `Pagination`. Para localização na hierarquia, use `Breadcrumb`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `steps` | `StepperStep[]` | Lista de passos exibidos na trilha |
| `currentStep` | `number` | Índice (base 0) do passo atual; usado quando o passo não define status próprio |
| `orientation` | `"horizontal" \| "vertical"` | Direção da trilha: 'horizontal' \| 'vertical' |
| `className` | `string` | Classes CSS adicionais |
## API de eventos
`Stepper` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface StepperStep {
title: string;
description?: string;
status?: "pending" | "active" | "completed" | "error";
[key: string]: any;
}
```
## Exemplo
```vue
<template>
<Stepper />
</template>
<script setup>
import { Stepper } from '@1doc/1ds-vue';
</script>
```
---
# Switch
> Interruptor de ligar/desligar, com efeito imediato.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Switch } from '@1doc/1ds-vue';`
## Quando usar
Ligar/desligar uma configuração que tem efeito IMEDIATO, sem botão de salvar: notificações, modo escuro, visibilidade.
## Quando NÃO usar
Quando a escolha só vale após submeter um formulário — use `Checkbox`. Para escolher entre duas alternativas nomeadas (não ligado/desligado), use `Radio`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `checked` | `boolean` | Estado controlado do switch (ligado/desligado). |
| `defaultChecked` | `boolean` | Estado inicial quando não controlado. |
| `disabled` | `boolean` | Desabilita o switch (tem precedência sobre success/invalid). |
| `success` | `boolean` | Aplica o estilo de feedback positivo (verde) ao switch ligado. Mutuamente exclusivo com `invalid` — se ambos forem verdadeiros, `invalid` prevalece. |
| `invalid` | `boolean` | Aplica o estilo de feedback negativo (vermelho) ao switch ligado e define `aria-invalid`. Tem precedência sobre `success`. |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho do switch. |
| `iconChecked` | `any` | Slot: conteúdo custom do thumb quando LIGADO (padrão: ícone check) |
| `iconNotChecked` | `any` | Slot: conteúdo custom do thumb quando DESLIGADO (padrão: ícone xmark) |
| `name` | `string` | Nome do campo no submit de form nativo. Quando definido, o Switch emite um `<input type="hidden">` irmão do botão enquanto estiver ligado (semântica de checkbox nativo: só submete quando marcado). |
| `value` | `string` | Valor submetido no form nativo quando o switch está ligado (requer `name`). Padrão: `"on"`, como num checkbox nativo. |
| `id` | `string` | — |
| `ariaLabel` | `string` | Nome acessível do switch quando não há `label` visível. |
| `label` | `string` | Texto do label exibido ao lado do switch. |
| `description` | `string` | Texto de descrição auxiliar exibido abaixo do label. |
| `background` | `boolean` | Exibe o switch dentro de um container com fundo. |
| `className` | `string` | — |
| `onChange` | `(checked: boolean) => void` | Callback disparado quando o estado do switch muda. |
## Slots
- `icon-checked`
- `icon-not-checked`
## API de eventos
`Switch` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Switch size="sm" />
</template>
<script setup>
import { Switch } from '@1doc/1ds-vue';
</script>
```
---
# Tabs
> Propriedades do componente Tabs.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Tabs } from '@1doc/1ds-vue';`
## Quando usar
Alternar entre seções de conteúdo DENTRO da mesma página, sem navegar: abas de um processo, visões de um relatório. Desktop e mobile.
## Quando NÃO usar
Para navegação entre ÁREAS do aplicativo em mobile (barra fixa no rodapé) — use `BottomNavigation`. Para menu de ações, use `Dropdown`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `value` | `string` | Valor da tab ativa (controlado) |
| `onChange` | `(index: string) => void` | Callback chamado quando uma tab é selecionada |
| `ariaLabel` | `string` | Label de acessibilidade para o tablist |
| `id` | `string` | Identificador estável usado como base dos ids acessíveis (`{id}-tab-{index}` / `{id}-panel-{index}`). Passe o MESMO id no `Tabs` e no `TabsContent` correspondente para vincular cada tab ao seu painel via `aria-controls`/`aria-labelledby`. Sem id, o vínculo não é renderizado (Tabs e TabsContent são árvores irmãs — não há como gerar um id compartilhado automaticamente). |
| `className` | `string` | Classes CSS adicionais |
| `children` | `any` | Subcomponentes Tab |
## Slots
- `default`
## API de eventos
`Tabs` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Tabs >Exemplo Tabs</Tabs>
</template>
<script setup>
import { Tabs } from '@1doc/1ds-vue';
</script>
```
---
# Tag
> Componente Tag para exibir rótulos, categorias e seleções. Suporta aparências outlined/solid, 3 tamanhos e ícones opcionais. Ideal para uso em multi-select, filtros e categorização.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Tag } from '@1doc/1ds-vue';`
## Quando usar
Rótulo ESTÁTICO que classifica ou dá status a um item: categoria de um processo, estado ("Em andamento"), prioridade. É leitura, não controle.
## Quando NÃO usar
Quando o usuário pode remover o item ou alternar a seleção — use `Chips`. Para contagem numérica sobreposta a um ícone, use `Badge`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `id` | `string` | ID HTML do elemento raiz. |
| `label` | `string` | Texto exibido dentro da tag. |
| `appearance` | `"outlined" \| "solid"` | Estilo visual da tag. |
| `variant` | `"neutral" \| "primary" \| "positive" \| "negative" \| "info"` | Variante semântica de cor (paridade com o Badge) — para tag de STATUS (achado mobile/prefeitura: sem isso, status exigia trocar para Badge). 'neutral' mantém o visual atual. |
| `size` | `"sm" \| "md" \| "lg"` | Tamanho da tag. |
| `iconStart` | `IconProp` | Ícone Font Awesome exibido à esquerda do label. |
| `iconEnd` | `IconProp` | Ícone Font Awesome exibido à direita do label (antes do close). |
| `closable` | `boolean` | Se true, exibe o botão de fechar (ícone xmark). |
| `closeAriaLabel` | `string` | Rótulo acessível do botão de fechar. Sem isto, "Remover". Serve para dar contexto ("Remover Curitiba") e para i18n. |
| `onClose` | `(event: any) => void` | Callback disparado ao clicar no botão de fechar. |
| `onIconStartClick` | `(event: any) => void` | Callback disparado ao clicar no ícone à esquerda. |
| `onIconEndClick` | `(event: any) => void` | Callback disparado ao clicar no ícone à direita. |
| `disabled` | `boolean` | Se a tag está desabilitada. |
| `className` | `string` | Classes CSS adicionais. |
| `children` | `any` | Conteúdo filho (alternativa ao label). |
## Slots
- `default`
## API de eventos
`Tag` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Tag variant="neutral" size="sm" >Exemplo Tag</Tag>
</template>
<script setup>
import { Tag } from '@1doc/1ds-vue';
</script>
```
---
# Text
> Componente tipográfico do 1DS — renderiza qualquer texto dentro da escala oficial. A `variant` escolhe o papel (título, corpo, legenda, rótulo) e já traz tamanho, peso e altura de linha correspondentes; a tag HTML é escolhida separadamente, para que o nível semântico do documento não fique preso à aparência. Aceita variantes por breakpoint (sm/md/lg/xl/xxl) para o texto mudar de escala em telas diferentes, e cores apenas via tokens semânticos.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Text } from '@1doc/1ds-vue';`
## Quando usar
Todo texto do produto: títulos, corpo, legenda, rótulo. Garante a escala tipográfica e as cores semânticas do DS.
## Quando NÃO usar
Não use `<p>`, `<h1>` ou `<span>` crus com estilo próprio — é assim que surgem tamanhos e cores fora da escala.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `id` | `string` | ID HTML do elemento raiz |
| `variant` | `TextVariant` | Variante tipográfica padrão |
| `visual` | `TextVariant \| ResponsiveVariant` | Sobrescreve o visual independente do elemento semântico |
| `xs` | `TextVariant` | Variante responsive para xs (também define o elemento semântico) |
| `sm` | `TextVariant` | Variante responsive para sm (também define o elemento semântico) |
| `md` | `TextVariant` | Variante responsive para md (também define o elemento semântico) |
| `lg` | `TextVariant` | Variante responsive para lg (também define o elemento semântico) |
| `xl` | `TextVariant` | Variante responsive para xl (também define o elemento semântico) |
| `xxl` | `TextVariant` | Variante responsive para xxl (também define o elemento semântico) |
| `as` | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "p" \| "span" \| "div" \| "label"` | Elemento HTML a ser renderizado (sobrescreve o padrão da variante) |
| `align` | `"left" \| "center" \| "right" \| "justify"` | Alinhamento do texto |
| `color` | `"primary" \| "secondary" \| "disabled" \| "negative" \| "inherit" \| "error"` | Cor do texto usando tokens semânticos |
| `weight` | `"thin" \| "light" \| "regular" \| "medium" \| "semibold" \| "bold" \| "extrabold" \| "black"` | Peso da fonte |
| `noWrap` | `boolean` | Truncar texto com ellipsis |
| `maxLines` | `number` | Número máximo de linhas antes de truncar |
| `transform` | `"none" \| "capitalize" \| "uppercase" \| "lowercase"` | Transforma o texto |
| `gutterBottom` | `boolean` | Adiciona margem inferior baseada no espaçamento do design system |
| `className` | `string` | Classes CSS adicionais |
| `style` | `any` | Atributos HTML repassados ao elemento raiz (style, data-*, aria-*…). |
| `forId` | `string` | Id para o htmlFor (label) |
| `children` | `any` | Conteúdo do texto |
## Slots
- `default`
## API de eventos
`Text` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface ResponsiveVariant {
xs?: TextVariant;
sm?: TextVariant;
md?: TextVariant;
lg?: TextVariant;
xl?: TextVariant;
xxl?: TextVariant;
}
```
## Exemplo
```vue
<template>
<Text variant="TextVariant" >Exemplo Text</Text>
</template>
<script setup>
import { Text } from '@1doc/1ds-vue';
</script>
```
---
# Textarea
> Componente Textarea — campo de texto multilinha com rótulo, contador de caracteres, redimensionamento automático e estados de erro/desabilitado/ somente leitura.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Textarea } from '@1doc/1ds-vue';`
## Quando usar
Texto LONGO de várias linhas: descrição, justificativa, observação. Tem contador de caracteres e altura ajustável.
## Quando NÃO usar
Para texto curto de uma linha — use `Input`. Para texto com formatação (negrito, listas), este componente não serve: o editor rico é da aplicação, não do DS.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `id` | `string` | ID do textarea nativo (gerado automaticamente se omitido) |
| `label` | `any` | Rótulo do campo (texto ou nó customizado) |
| `name` | `string` | Atributo name do textarea nativo |
| `value` | `string` | Valor controlado |
| `defaultValue` | `string` | Valor inicial (não controlado) |
| `placeholder` | `string` | Texto exibido quando o campo está vazio |
| `helperText` | `any` | Texto de ajuda exibido abaixo do campo |
| `invalid` | `boolean` | Marca o campo como invalido sem exigir mensagem. Soma-se a presenca de `errorMessage`: qualquer um dos dois liga o estado de erro. |
| `errorMessage` | `any` | Mensagem de erro (ativa o estado de erro) |
| `disabled` | `boolean` | Desabilita o campo |
| `readOnly` | `boolean` | Torna o campo somente leitura |
| `required` | `boolean` | Marca o campo como obrigatório (*) |
| `rows` | `number` | Número de linhas visíveis (sem autoSize) |
| `minRows` | `number` | Mínimo de linhas quando autoSize está ativo |
| `maxRows` | `number` | Máximo de linhas quando autoSize está ativo |
| `maxLength` | `number` | Quantidade máxima de caracteres |
| `showCounter` | `boolean` | Exibe o contador de caracteres |
| `autoSize` | `boolean` | Redimensiona a altura conforme o conteúdo |
| `fullWidth` | `boolean` | Expande o campo para 100% da largura |
| `className` | `string` | Classes CSS adicionais |
| `ariaLabel` | `string` | Nome acessível quando não há label visível |
| `onChange` | `(value: string) => void` | Callback acionado ao digitar (recebe o novo valor string) |
| `onInput` | `(event?: any) => void` | Callback de input (recebe o evento nativo) |
| `onFocus` | `(event?: any) => void` | Callback de foco (recebe o evento nativo) |
| `onBlur` | `(event?: any) => void` | Callback de blur (recebe o evento nativo) |
## Slots
- `error-message`
- `helper-text`
- `label`
## API de eventos
`Textarea` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Textarea />
</template>
<script setup>
import { Textarea } from '@1doc/1ds-vue';
</script>
```
---
# TimePicker
> TimePicker component — campo de horário com spinner de horas/minutos/segundos. Abre por clique; incrementa/decrementa cada coluna por botões ou teclado. Fecha ao pressionar Esc, clicar em OK ou navegar para fora. O dropdown é renderizado num Portal e posicionado via @floating-ui/dom (não é clipado por containers com overflow; acompanha o scroll via autoUpdate).
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { TimePicker } from '@1doc/1ds-vue';`
## Quando usar
Escolher HORA em colunas de hora/minuto/segundo, ou intervalo início-fim.
## Quando NÃO usar
Para data — use `DatePicker`. Para duração livre digitada, um `Input` com máscara é mais simples.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `increaseHourLabel` | `string` | Rótulo acessível do botão de aumentar hora. @default 'Aumentar hora' |
| `decreaseHourLabel` | `string` | Rótulo acessível do botão de diminuir hora. @default 'Diminuir hora' |
| `increaseMinuteLabel` | `string` | Rótulo acessível do botão de aumentar minuto. @default 'Aumentar minuto' |
| `decreaseMinuteLabel` | `string` | Rótulo acessível do botão de diminuir minuto. @default 'Diminuir minuto' |
| `increaseSecondLabel` | `string` | Rótulo acessível do botão de aumentar segundo. @default 'Aumentar segundo' |
| `decreaseSecondLabel` | `string` | Rótulo acessível do botão de diminuir segundo. @default 'Diminuir segundo' |
| `hourLabel` | `string` | Rótulo acessível do campo de hora. @default 'Hora' |
| `minuteLabel` | `string` | Rótulo acessível do campo de minuto. @default 'Minuto' |
| `secondLabel` | `string` | Rótulo acessível do campo de segundo. @default 'Segundo' |
| `value` | `string` | Valor no formato HH:mm ou HH:mm:ss. |
| `defaultValue` | `string` | Valor inicial não-controlado (HH:mm ou HH:mm:ss). |
| `name` | `string` | Nome do campo no submit do form — emite um input hidden com o valor atual. |
| `placeholder` | `string` | Texto exibido quando não há valor. |
| `disabled` | `boolean` | Desabilita o campo. |
| `readOnly` | `boolean` | Somente leitura: mantém o valor visível e focável, mas impede alteração. |
| `min` | `string` | Hora mínima permitida (HH:mm). |
| `max` | `string` | Hora máxima permitida (HH:mm). |
| `format` | `"HH:mm" \| "HH:mm:ss"` | Formato de exibição (inclui segundos em HH:mm:ss). |
| `step` | `number` | Intervalo de minutos: 1 \| 5 \| 10 \| 15 \| 30. |
| `label` | `string` | Rótulo visível acima do campo. |
| `ariaLabel` | `string` | Nome acessível quando não há label visível (vira aria-label no combobox). |
| `invalid` | `boolean` | Marca o campo como invalido. Nome canonico da familia de campos. |
| `error` | `boolean` | Ativa o estado de erro. |
| `errorMessage` | `string` | Mensagem exibida abaixo do campo no estado de erro. |
| `helperText` | `string` | Texto de ajuda exibido abaixo do campo. |
| `nowLabel` | `string` | Texto do botão "Agora" no rodapé do dropdown (i18n). |
| `okLabel` | `string` | Texto do botão "OK" no rodapé do dropdown (i18n). |
| `className` | `string` | Classes CSS adicionais. |
| `onChange` | `(value: string) => void` | Callback disparado ao mudar o valor. |
## API de eventos
`TimePicker` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<TimePicker />
</template>
<script setup>
import { TimePicker } from '@1doc/1ds-vue';
</script>
```
---
# Toast
> Componente Toast — notificação temporária flutuante, renderizada via Portal na raiz do documento (não fica presa ao overflow do elemento pai). Comunica o resultado de uma ação (sucesso, erro, aviso ou informação) e pode fechar automaticamente após um tempo.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Toast } from '@1doc/1ds-vue';`
## Quando usar
Retorno TRANSITÓRIO e não-bloqueante de uma ação recém-executada: "Processo salvo", "Link copiado". Aparece sobreposto e some sozinho.
## Quando NÃO usar
Para mensagem que precisa continuar visível ou ser relida — use `Alert`. Para erro que impede o usuário de prosseguir, use `Alert` junto ao campo.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `closeLabel` | `string` | Rótulo acessível do botão de fechar. @default 'Fechar notificação' |
| `open` | `boolean` | Controla a visibilidade do toast. |
| `variant` | `"positive" \| "negative" \| "info" \| "neutral"` | Variante semântica (cor/finalidade) da notificação. |
| `message` | `string` | Mensagem principal exibida em destaque. |
| `description` | `string` | Descrição adicional exibida abaixo da mensagem. |
| `position` | `"top-right" \| "top-center" \| "bottom-right" \| "bottom-center"` | Posição na tela onde o toast é fixado. |
| `duration` | `number` | Duração em milissegundos até o fechamento automático. Se 0, ou não definido, o toast não fecha sozinho. |
| `closable` | `boolean` | Exibe o botão de fechar. |
| `className` | `string` | Classes CSS adicionais aplicadas na raiz do toast. |
| `portalContainer` | `any` | Container de destino do Portal interno (padrão: document.body). Usado pelo ToastStack para empilhar toasts no próprio container fixo. |
| `onClose` | `(event?: any) => void` | Callback acionado ao fechar (clique no botão ou expiração da duração). |
## API de eventos
`Toast` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Toast variant="positive" />
</template>
<script setup>
import { Toast } from '@1doc/1ds-vue';
</script>
```
---
# Tooltip
> Rótulo flutuante de apoio, acionado por hover ou foco.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Tooltip } from '@1doc/1ds-vue';`
## Quando usar
Explicação CURTA que aparece no hover ou no foco: o que faz um botão de ícone, o formato esperado de um campo.
## Quando NÃO usar
Para conteúdo essencial — tooltip não aparece em toque e é fácil de perder; coloque como texto auxiliar do campo. Para menu de ações, use `Dropdown`.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `content` | `any` | Conteúdo do tooltip — aceita ReactNode no React (no Vue, prefira string) |
| `title` | `string` | — |
| `icon` | `IconProp` | — |
| `side` | `"top" \| "bottom" \| "left" \| "right"` | Lado do trigger onde o tooltip abre. Compõe com `align` (4×3 = 12 posições). |
| `align` | `"start" \| "center" \| "end"` | Alinhamento no eixo cruzado: "center" usa só o `side`; "start"/"end" viram placements compostos (`top-start`, `right-end`…). |
| `sideOffset` | `number` | — |
| `delayDuration` | `number` | — |
| `disabled` | `boolean` | — |
| `className` | `string` | — |
| `children` | `any` | — |
## Slots
- `content`
- `default`
## API de eventos
`Tooltip` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Exemplo
```vue
<template>
<Tooltip >Exemplo Tooltip</Tooltip>
</template>
<script setup>
import { Tooltip } from '@1doc/1ds-vue';
</script>
```
---
# Tree
> Árvore hierárquica com expansão, seleção e teclado APG.
- Framework: Vue 3
- Pacote: `@1doc/1ds-vue` (v2.5.0)
- Import: `import { Tree } from '@1doc/1ds-vue';`
## Quando usar
Hierarquia PAI-FILHO navegável: setores, pastas, categorias aninhadas. O conteúdo da linha é livre via `renderItem`.
## Quando NÃO usar
Para lista plana comparável — use `DataTable`. Para menu de navegação, use `Tabs` ou a sidebar da aplicação.
## Props
| Prop | Tipo | Descrição |
| --- | --- | --- |
| `items` | `TreeNode[]` | — |
| `expandedIds` | `Array<string>` | Ids expandidos (controlado). Sem a prop, a árvore controla sozinha. |
| `defaultExpandedIds` | `Array<string>` | — |
| `onExpandedChange` | `(ids: Array<string>) => void` | — |
| `selectionMode` | `"none" \| "single" \| "multiple"` | — |
| `selectedIds` | `Array<string>` | — |
| `defaultSelectedIds` | `Array<string>` | — |
| `onSelectionChange` | `(ids: Array<string>) => void` | — |
| `selectionCascade` | `boolean` | Marcar um nó marca toda a descendência, e o pai fica indeterminado quando só parte dos filhos está marcada. Opcional e desligado por padrão: ligado, `onSelectionChange` passa a emitir ids que o usuário não clicou, e nem toda árvore quer esse contrato. Só faz sentido com `selectionMode="multiple"`. |
| `renderItem` | `(node: TreeNode, meta: { level: number; expanded: boolean }) => any` | Conteúdo da linha. Recebe o nó e o contexto (nível, expandido). Sem isto, a árvore renderiza `node.label`. É o que mantém o componente genérico: a tela de setores monta colunas e ações por aqui, sem que a árvore precise conhecer "sigla" ou "contagem". |
| `caret` | `"plus-minus" \| "chevron" \| "none"` | Desenho do controle de expansão. **O padrão é `none`.** `none` não desenha controle: a hierarquia já está dita pela indentação, pelas guias e pelo ícone. A linha continua expandindo no clique e pelas setas, então nada se perde de função. `plus-minus` é o do component set do Figma (4967:4407). `chevron` gira 90 graus ao abrir, como o Accordion. |
| `size` | `"sm" \| "md" \| "lg"` | — |
| `disabled` | `boolean` | — |
| `ariaLabel` | `string` | Rótulo acessível da árvore. Um dos dois é obrigatório. |
| `ariaLabelledby` | `string` | — |
| `className` | `string` | — |
| `id` | `string` | — |
| `style` | `any` | Atributos HTML repassados ao elemento raiz. |
## API de eventos
`Tree` não declara `defineEmits`: não há `v-model` nem eventos emitidos.
Callbacks são **props** (ver a tabela acima) e recebem o valor já extraído.
## Tipos auxiliares
Exportados pelo mesmo pacote e necessários para montar as props de coleção.
```ts
export interface TreeNode {
id: string;
/** Rótulo padrão. Ignorado quando o consumidor usa o slot de linha. */
label?: string;
children?: TreeNode[];
/**
* Marca que o nó TEM filhos ainda não carregados. Serve para o caret
* aparecer antes de `children` existir (carregamento sob demanda).
*/
hasChildren?: boolean;
/** Nó em carregamento: o caret vira indicador de espera. */
loading?: boolean;
disabled?: boolean;
icon?: any;
/**
* Cor do ícone da linha. Sem isto todo ícone sai no cinza do rótulo, e uma
* árvore de pastas fica sem hierarquia visual. Os valores são os do `Icon` —
* não aceita cor livre, para não abrir porta a hex fora do token.
*/
iconVariant?: "primary" | "secondary" | "neutral" | "inherit";
}
```
```ts
export interface TreeVisibleRow {
node: TreeNode;
level: number;
expanded: boolean;
hasToggle: boolean;
parentId: string | null;
/** Última entre os irmãos: define cotovelo em "L" em vez de "T". */
isLast: boolean;
/** Posição entre os irmãos (1-based) — vira aria-posinset. */
posInSet: number;
/** Total de irmãos no mesmo nível — vira aria-setsize. */
setSize: number;
}
```
## Exemplo
```vue
<template>
<Tree size="sm" />
</template>
<script setup>
import { Tree } from '@1doc/1ds-vue';
</script>
```
---
# Tokens primitivos
> Escalas cruas: cor, espaçamento, tipografia, raio, sombra, opacidade e breakpoints.
Valores extraídos de `primitives.css`, gerado pelo Style Dictionary a partir de
`packages/tokens/src/`. Use sempre a variável CSS, nunca o valor literal.
## border
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-border-width-none)` | `0px` | — |
| `var(--umds-primitive-border-width-hairline)` | `1px` | — |
| `var(--umds-primitive-border-width-thin)` | `2px` | — |
| `var(--umds-primitive-border-width-thick)` | `4px` | — |
| `var(--umds-primitive-border-width-heavy)` | `8px` | — |
| `var(--umds-primitive-border-radius-none)` | `0px` | — |
| `var(--umds-primitive-border-radius-xxs)` | `2px` | — |
| `var(--umds-primitive-border-radius-xs)` | `4px` | — |
| `var(--umds-primitive-border-radius-sm)` | `8px` | — |
| `var(--umds-primitive-border-radius-md)` | `16px` | — |
| `var(--umds-primitive-border-radius-lg)` | `24px` | — |
| `var(--umds-primitive-border-radius-pill)` | `500px` | — |
| `var(--umds-primitive-border-radius-circular)` | `50%` | — |
## breakpoint
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-breakpoint-xs)` | `0px` | — |
| `var(--umds-primitive-breakpoint-sm)` | `640px` | — |
| `var(--umds-primitive-breakpoint-md)` | `768px` | — |
| `var(--umds-primitive-breakpoint-lg)` | `1024px` | — |
| `var(--umds-primitive-breakpoint-xl)` | `1280px` | — |
| `var(--umds-primitive-breakpoint-xxl)` | `1536px` | — |
## blue
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-blue-dark)` | `#194280` | — |
| `var(--umds-primitive-blue-pure)` | `#0058DB` | — |
| `var(--umds-primitive-blue-medium)` | `#6393DB` | — |
| `var(--umds-primitive-blue-light)` | `#DCE6F5` | — |
## red
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-red-dark)` | `#80211A` | — |
| `var(--umds-primitive-red-pure)` | `#CC2F22` | — |
| `var(--umds-primitive-red-medium)` | `#D9685F` | — |
| `var(--umds-primitive-red-light)` | `#FFE7E5` | — |
## green
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-green-dark)` | `#0F4C30` | — |
| `var(--umds-primitive-green-pure)` | `#0D804A` | — |
| `var(--umds-primitive-green-medium)` | `#4C9975` | — |
| `var(--umds-primitive-green-light)` | `#D0F5E4` | — |
## orange
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-orange-dark)` | `#99541F` | — |
| `var(--umds-primitive-orange-pure)` | `#DF701A` | — |
| `var(--umds-primitive-orange-medium)` | `#E58A45` | — |
| `var(--umds-primitive-orange-light)` | `#FFF1E5` | — |
## yellow
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-yellow-dark)` | `#806200` | — |
| `var(--umds-primitive-yellow-pure)` | `#B88F0B` | — |
| `var(--umds-primitive-yellow-medium)` | `#FAD14B` | — |
| `var(--umds-primitive-yellow-light)` | `#194280` | — |
## gray
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-gray-darkest)` | `#333333` | — |
| `var(--umds-primitive-gray-darker)` | `#565656` | — |
| `var(--umds-primitive-gray-dark)` | `#7D7D7D` | — |
| `var(--umds-primitive-gray-medium)` | `#A3A3A3` | — |
| `var(--umds-primitive-gray-light)` | `#D5D5D5` | — |
| `var(--umds-primitive-gray-lighter)` | `#EBEBEB` | — |
| `var(--umds-primitive-gray-lightest)` | `#F6F6F6` | — |
## background
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-background-dark)` | `#212E41` | — |
| `var(--umds-primitive-background-light)` | `#F4F6F9` | — |
## feedback
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-feedback-positive-pure)` | `#0F4C30` | — |
| `var(--umds-primitive-feedback-positive-dark)` | `#0F4C30` | — |
| `var(--umds-primitive-feedback-positive-light)` | `#CEF2E1` | — |
| `var(--umds-primitive-feedback-negative-pure)` | `#B2132E` | — |
| `var(--umds-primitive-feedback-negative-dark)` | `#801224` | — |
| `var(--umds-primitive-feedback-negative-light)` | `#FFE6EA` | — |
| `var(--umds-primitive-feedback-info-pure)` | `#D86816` | — |
| `var(--umds-primitive-feedback-info-dark)` | `#99470C` | — |
| `var(--umds-primitive-feedback-info-light)` | `#FFE9D9` | — |
## purple
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-purple-dark)` | `#560599` | — |
| `var(--umds-primitive-purple-pure)` | `#1B04E6` | — |
| `var(--umds-primitive-purple-light)` | `#E6DCF5` | — |
## white
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-white)` | `#FFFFFF` | — |
## opacity
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-opacity-level-semiopaque)` | `0.8` | — |
| `var(--umds-primitive-opacity-level-intense)` | `0.64` | — |
| `var(--umds-primitive-opacity-level-medium)` | `0.32` | — |
| `var(--umds-primitive-opacity-level-light)` | `0.16` | — |
| `var(--umds-primitive-opacity-level-semitransparent)` | `0.08` | — |
## shadow
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-shadow-level-1)` | `0 4px 8px 0 rgba(0, 0, 0, 0.08)` | — |
| `var(--umds-primitive-shadow-level-2)` | `0 8px 24px 0 rgba(0, 0, 0, 0.16)` | — |
| `var(--umds-primitive-shadow-level-3)` | `0 16px 32px 0 rgba(0, 0, 0, 0.16)` | — |
| `var(--umds-primitive-shadow-level-4)` | `0 16px 48px 0 rgba(0, 0, 0, 0.24)` | — |
## spacing
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-spacing-micro)` | `2px` | Respiro micro, abaixo do quarck. Gaps de ícone/rótulo — 25 usos na varredura de agosto/2026. |
| `var(--umds-primitive-spacing-quarck)` | `4px` | — |
| `var(--umds-primitive-spacing-nano)` | `8px` | — |
| `var(--umds-primitive-spacing-mini)` | `12px` | Degrau que faltava entre nano (8) e xxxs (16). Padding de célula de tabela e de Card. |
| `var(--umds-primitive-spacing-xxxs)` | `16px` | — |
| `var(--umds-primitive-spacing-xxs)` | `24px` | — |
| `var(--umds-primitive-spacing-xs)` | `32px` | — |
| `var(--umds-primitive-spacing-sm)` | `40px` | — |
| `var(--umds-primitive-spacing-md)` | `48px` | — |
| `var(--umds-primitive-spacing-lg)` | `56px` | — |
| `var(--umds-primitive-spacing-xl)` | `64px` | — |
| `var(--umds-primitive-spacing-xxl)` | `80px` | — |
| `var(--umds-primitive-spacing-xxxl)` | `120px` | — |
| `var(--umds-primitive-spacing-huge)` | `160px` | — |
| `var(--umds-primitive-spacing-giant)` | `200px` | — |
## font
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-primitive-font-family-base)` | `'Open Sans', sans-serif` | — |
| `var(--umds-primitive-font-url-google)` | `'https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300..800` | — |
| `var(--umds-primitive-font-size-xxxs)` | `12px` | — |
| `var(--umds-primitive-font-size-xxs)` | `14px` | — |
| `var(--umds-primitive-font-size-xs)` | `16px` | — |
| `var(--umds-primitive-font-size-sm)` | `20px` | — |
| `var(--umds-primitive-font-size-md)` | `24px` | — |
| `var(--umds-primitive-font-size-lg)` | `32px` | — |
| `var(--umds-primitive-font-size-xl)` | `40px` | — |
| `var(--umds-primitive-font-size-xxl)` | `48px` | — |
| `var(--umds-primitive-font-size-xxxl)` | `64px` | — |
| `var(--umds-primitive-font-size-display)` | `80px` | — |
| `var(--umds-primitive-font-size-giant)` | `96px` | — |
| `var(--umds-primitive-font-weight-thin)` | `100` | — |
| `var(--umds-primitive-font-weight-extralight)` | `200` | — |
| `var(--umds-primitive-font-weight-light)` | `300` | — |
| `var(--umds-primitive-font-weight-regular)` | `400` | — |
| `var(--umds-primitive-font-weight-medium)` | `500` | — |
| `var(--umds-primitive-font-weight-semibold)` | `600` | — |
| `var(--umds-primitive-font-weight-bold)` | `700` | — |
| `var(--umds-primitive-font-weight-extrabold)` | `800` | — |
| `var(--umds-primitive-font-weight-black)` | `900` | — |
| `var(--umds-primitive-font-line-height-default)` | `100%` | — |
| `var(--umds-primitive-font-line-height-xs)` | `115%` | — |
| `var(--umds-primitive-font-line-height-sm)` | `120%` | — |
| `var(--umds-primitive-font-line-height-md)` | `133%` | — |
| `var(--umds-primitive-font-line-height-lg)` | `150%` | — |
| `var(--umds-primitive-font-line-height-xl)` | `170%` | — |
| `var(--umds-primitive-font-line-height-xxl)` | `200%` | — |
| `var(--umds-primitive-font-letter-spacing-tight)` | `-0.02em` | — |
| `var(--umds-primitive-font-letter-spacing-snug)` | `-0.01em` | — |
| `var(--umds-primitive-font-letter-spacing-default)` | `0` | — |
| `var(--umds-primitive-font-letter-spacing-wide)` | `0.02em` | — |
| `var(--umds-primitive-font-letter-spacing-wider)` | `0.04em` | — |
---
# Tokens semânticos
> Tokens com significado de uso. É o nível que o CSS de componente pode citar.
Valores extraídos de `semantic.css`, gerado pelo Style Dictionary a partir de
`packages/tokens/src/`. Use sempre a variável CSS, nunca o valor literal.
## field
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-field-height)` | `44px` | Altura de repouso de todo campo no tamanho padrão. Figma: Input/Select/MultiSelect Size=Default = 44px. Também é o alvo de toque mínimo (WCAG 2.5.5). |
| `var(--umds-semantic-field-ring-focus)` | `0 0 0 3px color-mix(in srgb, var(--umds-semantic-color-primary-pure) 12%, transparent)` | Anel de foco de campo. Não-campos usam outline 2px primary-pure. |
| `var(--umds-semantic-field-ring-error)` | `0 0 0 3px color-mix(in srgb, var(--umds-semantic-color-feedback-negative-pure) 12%, transparent)` | Mesma anatomia do foco, na cor de erro |
| `var(--umds-semantic-field-disabled-opacity)` | `0.5` | Opacidade única de campo desabilitado |
| `var(--umds-semantic-field-height-sm)` | `var(--umds-primitive-spacing-xs)` | 32px — Figma: Size=Small. Único tamanho reduzido desenhado. |
| `var(--umds-semantic-field-height-lg)` | `var(--umds-primitive-spacing-md)` | 48px — sem contrapartida no Figma (que só desenha Default e Small); mantido para não quebrar quem já usa size="lg". |
| `var(--umds-semantic-field-text-size)` | `var(--umds-primitive-font-size-xxs)` | 14px — tamanho do texto digitado (Figma node 5510-854) |
| `var(--umds-semantic-field-placeholder-color)` | `var(--umds-theme-field-placeholder)` | Claro #767676 (4,54:1 sobre branco) · escuro #8C8C8C (5,22:1). Apontava para neutral-dark-medium = #7D7D7D, que dá 4,12:1 e reprova o WCAG AA — o comentário antigo dizia 4,6:1 e estava errado. #767676 é o cinza mais claro que ainda passa; a diferença para #7D7D7D é de 7 pontos e o placeholder segue bem distinto do texto digitado (#333333, 12,63:1). |
| `var(--umds-semantic-field-label-size)` | `var(--umds-primitive-font-size-xxs)` | 14px, sem uppercase (Figma node 5510-854) |
| `var(--umds-semantic-field-label-weight)` | `var(--umds-primitive-font-weight-regular)` | 400 — o Figma não usa semibold em label de campo |
| `var(--umds-semantic-field-border-default)` | `var(--umds-semantic-color-neutral-light-down)` | Borda em repouso |
| `var(--umds-semantic-field-border-hover)` | `var(--umds-semantic-color-primary-dark)` | Borda no hover (decisão da reunião: medium -> dark) |
| `var(--umds-semantic-field-border-focus)` | `var(--umds-semantic-color-primary-pure)` | Borda no foco |
| `var(--umds-semantic-field-border-error)` | `var(--umds-semantic-color-feedback-negative-pure)` | Borda em erro, com ou sem foco |
| `var(--umds-semantic-field-text-color)` | `var(--umds-semantic-color-neutral-dark-pure)` | #333333 — cor do texto digitado |
| `var(--umds-semantic-field-label-color)` | `var(--umds-semantic-color-neutral-dark-pure)` | #333333 |
| `var(--umds-semantic-field-readonly-background)` | `var(--umds-semantic-color-background-light)` | Fundo de campo somente-leitura. Diferente de disabled: continua focável e o anel de foco permanece. |
| `var(--umds-semantic-field-disabled-background)` | `var(--umds-semantic-color-neutral-light-medium)` | Fundo de campo desabilitado |
## layer
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-layer-modal)` | `1300` | Overlays de bloqueio: Modal, ConfirmDialog |
| `var(--umds-semantic-layer-popover)` | `1400` | Painéis flutuantes: DatePicker, TimePicker, Select, MultiSelect, Dropdown, PhoneInput — acima de modal para funcionar dentro de diálogos |
| `var(--umds-semantic-layer-toast)` | `1500` | Notificações: Toast, Alert fixo |
| `var(--umds-semantic-layer-tooltip)` | `1600` | Tooltip — sempre a camada mais alta |
## motion
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-motion-duration-fast)` | `150ms` | Micro-interações: hover, foco, cor (protótipo --transition-fast) |
| `var(--umds-semantic-motion-duration-base)` | `250ms` | Entradas/saídas de painéis e diálogos (protótipo --transition-base) |
| `var(--umds-semantic-motion-easing-standard)` | `cubic-bezier(0.4, 0, 0.2, 1)` | Curva padrão de transições |
| `var(--umds-semantic-motion-easing-bounce)` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Curva com overshoot para entradas de diálogos (protótipo --transition-bounce) |
## shadow
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-shadow-xs)` | `0 1px 2px rgba(0, 0, 0, 0.03)` | — |
| `var(--umds-semantic-shadow-sm)` | `0 2px 4px rgba(0, 0, 0, 0.04), 0 1px 2px rgba(0, 0, 0, 0.02)` | — |
| `var(--umds-semantic-shadow-md)` | `0 8px 16px -2px rgba(0, 0, 0, 0.06), 0 4px 8px -2px rgba(0, 0, 0, 0.04)` | — |
| `var(--umds-semantic-shadow-lg)` | `0 16px 24px -4px rgba(0, 0, 0, 0.08), 0 8px 12px -4px rgba(0, 0, 0, 0.04)` | — |
## shell
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-shell-header-height)` | `56px` | Altura do cabeçalho da aplicação. É a medida do padrão 1Doc, escrita no CLAUDE.md do time e reconstruída à mão em cada produto até agora. Não sai da escala de espaçamento: é geometria de layout, como field.height. |
| `var(--umds-semantic-shell-subheader-height)` | `42px` | Altura da barra de contexto, logo abaixo do cabeçalho. Mais baixa que os 56px do header de propósito: é informação de apoio. Padrão 1Doc. |
| `var(--umds-semantic-shell-sidebar-width)` | `248px` | Largura da barra lateral aberta (ícone + rótulo). Padrão 1Doc. |
| `var(--umds-semantic-shell-panel-width)` | `254px` | Largura do painel lateral de tela (SidePanel). E o numero do prototipo da 1Doc, o mesmo na Emissao e nas Tarefas, medido no CSS de la. |
| `var(--umds-semantic-shell-sidebar-collapsed-width)` | `var(--umds-primitive-spacing-md)` | 48px — largura da barra lateral fechada, só ícones. Coincide com spacing.md e com o alvo de toque mínimo de 48px, então o ícone continua clicável fechado. |
| `var(--umds-semantic-shell-item-height)` | `var(--umds-primitive-spacing-md)` | 48px — altura de cada item de navegação. Igual à largura fechada, então o item é um quadrado quando a barra está fechada. |
## color
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-color-primary-dark)` | `var(--umds-theme-primary-dark)` | — |
| `var(--umds-semantic-color-primary-pure)` | `var(--umds-theme-primary-pure)` | — |
| `var(--umds-semantic-color-primary-medium)` | `var(--umds-theme-primary-medium)` | — |
| `var(--umds-semantic-color-primary-light)` | `var(--umds-theme-primary-light)` | — |
| `var(--umds-semantic-color-background-dark)` | `var(--umds-theme-background-dark)` | — |
| `var(--umds-semantic-color-background-light)` | `var(--umds-theme-background-light)` | — |
| `var(--umds-semantic-color-background-white)` | `var(--umds-theme-background-white)` | — |
| `var(--umds-semantic-color-background-elevated)` | `var(--umds-theme-background-elevated)` | — |
| `var(--umds-semantic-color-feedback-positive-pure)` | `var(--umds-theme-feedback-positive-pure)` | — |
| `var(--umds-semantic-color-feedback-positive-dark)` | `var(--umds-theme-feedback-positive-dark)` | — |
| `var(--umds-semantic-color-feedback-positive-light)` | `var(--umds-theme-feedback-positive-light)` | — |
| `var(--umds-semantic-color-feedback-negative-pure)` | `var(--umds-theme-feedback-negative-pure)` | — |
| `var(--umds-semantic-color-feedback-negative-dark)` | `var(--umds-theme-feedback-negative-dark)` | — |
| `var(--umds-semantic-color-feedback-negative-light)` | `var(--umds-theme-feedback-negative-light)` | — |
| `var(--umds-semantic-color-feedback-info-pure)` | `var(--umds-theme-feedback-info-pure)` | — |
| `var(--umds-semantic-color-feedback-info-dark)` | `var(--umds-theme-feedback-info-dark)` | — |
| `var(--umds-semantic-color-feedback-info-light)` | `var(--umds-theme-feedback-info-light)` | — |
| `var(--umds-semantic-color-ai-pure)` | `var(--umds-theme-ai-pure)` | — |
| `var(--umds-semantic-color-ai-dark)` | `var(--umds-theme-ai-dark)` | — |
| `var(--umds-semantic-color-ai-light)` | `var(--umds-theme-ai-light)` | — |
| `var(--umds-semantic-color-neutral-dark-pure)` | `var(--umds-theme-neutral-dark-pure)` | — |
| `var(--umds-semantic-color-neutral-dark-down)` | `var(--umds-theme-neutral-dark-down)` | — |
| `var(--umds-semantic-color-neutral-dark-medium)` | `var(--umds-theme-neutral-dark-medium)` | — |
| `var(--umds-semantic-color-neutral-dark-up)` | `var(--umds-theme-neutral-dark-up)` | — |
| `var(--umds-semantic-color-neutral-light-down)` | `var(--umds-theme-neutral-light-down)` | — |
| `var(--umds-semantic-color-neutral-light-medium)` | `var(--umds-theme-neutral-light-medium)` | — |
| `var(--umds-semantic-color-neutral-light-up)` | `var(--umds-theme-neutral-light-up)` | — |
| `var(--umds-semantic-color-neutral-light-pure)` | `var(--umds-theme-neutral-light-pure)` | — |
## typography
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-typography-display-giant-font-size)` | `var(--umds-primitive-font-size-giant)` | — |
| `var(--umds-semantic-typography-display-giant-font-weight)` | `var(--umds-primitive-font-weight-black)` | — |
| `var(--umds-semantic-typography-display-giant-line-height)` | `var(--umds-primitive-font-line-height-default)` | — |
| `var(--umds-semantic-typography-display-giant-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-tight)` | — |
| `var(--umds-semantic-typography-display-lg-font-size)` | `var(--umds-primitive-font-size-display)` | — |
| `var(--umds-semantic-typography-display-lg-font-weight)` | `var(--umds-primitive-font-weight-extrabold)` | — |
| `var(--umds-semantic-typography-display-lg-line-height)` | `var(--umds-primitive-font-line-height-default)` | — |
| `var(--umds-semantic-typography-display-lg-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-tight)` | — |
| `var(--umds-semantic-typography-heading-h1-font-size)` | `var(--umds-primitive-font-size-xxxl)` | — |
| `var(--umds-semantic-typography-heading-h1-font-weight)` | `var(--umds-primitive-font-weight-bold)` | — |
| `var(--umds-semantic-typography-heading-h1-line-height)` | `var(--umds-primitive-font-line-height-sm)` | — |
| `var(--umds-semantic-typography-heading-h1-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-snug)` | — |
| `var(--umds-semantic-typography-heading-h2-font-size)` | `var(--umds-primitive-font-size-xxl)` | — |
| `var(--umds-semantic-typography-heading-h2-font-weight)` | `var(--umds-primitive-font-weight-bold)` | — |
| `var(--umds-semantic-typography-heading-h2-line-height)` | `var(--umds-primitive-font-line-height-sm)` | — |
| `var(--umds-semantic-typography-heading-h2-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-snug)` | — |
| `var(--umds-semantic-typography-heading-h3-font-size)` | `var(--umds-primitive-font-size-xl)` | — |
| `var(--umds-semantic-typography-heading-h3-font-weight)` | `var(--umds-primitive-font-weight-semibold)` | — |
| `var(--umds-semantic-typography-heading-h3-line-height)` | `var(--umds-primitive-font-line-height-md)` | — |
| `var(--umds-semantic-typography-heading-h3-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-snug)` | — |
| `var(--umds-semantic-typography-heading-h4-font-size)` | `var(--umds-primitive-font-size-lg)` | — |
| `var(--umds-semantic-typography-heading-h4-font-weight)` | `var(--umds-primitive-font-weight-semibold)` | — |
| `var(--umds-semantic-typography-heading-h4-line-height)` | `var(--umds-primitive-font-line-height-md)` | — |
| `var(--umds-semantic-typography-heading-h4-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-heading-h5-font-size)` | `var(--umds-primitive-font-size-md)` | — |
| `var(--umds-semantic-typography-heading-h5-font-weight)` | `var(--umds-primitive-font-weight-medium)` | — |
| `var(--umds-semantic-typography-heading-h5-line-height)` | `var(--umds-primitive-font-line-height-md)` | — |
| `var(--umds-semantic-typography-heading-h5-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-heading-h6-font-size)` | `var(--umds-primitive-font-size-sm)` | — |
| `var(--umds-semantic-typography-heading-h6-font-weight)` | `var(--umds-primitive-font-weight-medium)` | — |
| `var(--umds-semantic-typography-heading-h6-line-height)` | `var(--umds-primitive-font-line-height-lg)` | — |
| `var(--umds-semantic-typography-heading-h6-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-body-lg-font-size)` | `var(--umds-primitive-font-size-sm)` | — |
| `var(--umds-semantic-typography-body-lg-font-weight)` | `var(--umds-primitive-font-weight-regular)` | — |
| `var(--umds-semantic-typography-body-lg-line-height)` | `var(--umds-primitive-font-line-height-lg)` | — |
| `var(--umds-semantic-typography-body-lg-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-body-md-font-size)` | `var(--umds-primitive-font-size-xs)` | — |
| `var(--umds-semantic-typography-body-md-font-weight)` | `var(--umds-primitive-font-weight-regular)` | — |
| `var(--umds-semantic-typography-body-md-line-height)` | `var(--umds-primitive-font-line-height-lg)` | — |
| `var(--umds-semantic-typography-body-md-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-body-sm-font-size)` | `var(--umds-primitive-font-size-xxs)` | — |
| `var(--umds-semantic-typography-body-sm-font-weight)` | `var(--umds-primitive-font-weight-regular)` | — |
| `var(--umds-semantic-typography-body-sm-line-height)` | `var(--umds-primitive-font-line-height-xl)` | — |
| `var(--umds-semantic-typography-body-sm-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
| `var(--umds-semantic-typography-label-lg-font-size)` | `var(--umds-primitive-font-size-xs)` | — |
| `var(--umds-semantic-typography-label-lg-font-weight)` | `var(--umds-primitive-font-weight-medium)` | — |
| `var(--umds-semantic-typography-label-lg-line-height)` | `var(--umds-primitive-font-line-height-md)` | — |
| `var(--umds-semantic-typography-label-lg-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-wide)` | — |
| `var(--umds-semantic-typography-label-md-font-size)` | `var(--umds-primitive-font-size-xxs)` | — |
| `var(--umds-semantic-typography-label-md-font-weight)` | `var(--umds-primitive-font-weight-medium)` | — |
| `var(--umds-semantic-typography-label-md-line-height)` | `var(--umds-primitive-font-line-height-md)` | — |
| `var(--umds-semantic-typography-label-md-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-wide)` | — |
| `var(--umds-semantic-typography-label-sm-font-size)` | `var(--umds-primitive-font-size-xxxs)` | — |
| `var(--umds-semantic-typography-label-sm-font-weight)` | `var(--umds-primitive-font-weight-medium)` | — |
| `var(--umds-semantic-typography-label-sm-line-height)` | `var(--umds-primitive-font-line-height-sm)` | — |
| `var(--umds-semantic-typography-label-sm-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-wider)` | — |
| `var(--umds-semantic-typography-caption-font-size)` | `var(--umds-primitive-font-size-xxxs)` | — |
| `var(--umds-semantic-typography-caption-font-weight)` | `var(--umds-primitive-font-weight-regular)` | — |
| `var(--umds-semantic-typography-caption-line-height)` | `var(--umds-primitive-font-line-height-xl)` | — |
| `var(--umds-semantic-typography-caption-letter-spacing)` | `var(--umds-primitive-font-letter-spacing-default)` | — |
## font
| Token | Valor | Nota |
| --- | --- | --- |
| `var(--umds-semantic-font-family-base)` | `var(--umds-primitive-font-family-base)` | — |
---
# Temas
> 12 temas. Cada um redefine as variáveis `--umds-theme-*`; os componentes nunca leem o tema direto.
O tema é aplicado com `data-theme` no elemento raiz:
```html
<html data-theme="1doc">
```
## 1doc
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#194280` |
| `var(--umds-theme-primary-pure)` | `#0058DB` |
| `var(--umds-theme-primary-medium)` | `#6393DB` |
| `var(--umds-theme-primary-light)` | `#DCE6F5` |
| `var(--umds-theme-background-dark)` | `#212E41` |
| `var(--umds-theme-background-light)` | `#F4F6F9` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#0F874E` |
| `var(--umds-theme-feedback-positive-dark)` | `#0F4C30` |
| `var(--umds-theme-feedback-positive-light)` | `#CEF2E1` |
| `var(--umds-theme-feedback-negative-pure)` | `#B2132E` |
| `var(--umds-theme-feedback-negative-dark)` | `#801224` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EA` |
| `var(--umds-theme-feedback-info-pure)` | `#DB6816` |
| `var(--umds-theme-feedback-info-dark)` | `#99470C` |
| `var(--umds-theme-feedback-info-light)` | `#FFE9D9` |
| `var(--umds-theme-ai-pure)` | `#6B0780` |
| `var(--umds-theme-ai-dark)` | `#560666` |
| `var(--umds-theme-ai-light)` | `#FBE6FF` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1doc-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#C7DDFF` |
| `var(--umds-theme-primary-pure)` | `#80B6FF` |
| `var(--umds-theme-primary-medium)` | `#4371B1` |
| `var(--umds-theme-primary-light)` | `#0C1527` |
| `var(--umds-theme-background-dark)` | `#D6E1F2` |
| `var(--umds-theme-background-light)` | `#1F1F21` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#4CDA93` |
| `var(--umds-theme-feedback-positive-dark)` | `#2BA56E` |
| `var(--umds-theme-feedback-positive-light)` | `#12261B` |
| `var(--umds-theme-feedback-negative-pure)` | `#F3495F` |
| `var(--umds-theme-feedback-negative-dark)` | `#F28D9D` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A0F` |
| `var(--umds-theme-feedback-info-pure)` | `#FF8000` |
| `var(--umds-theme-feedback-info-dark)` | `#FFD9B2` |
| `var(--umds-theme-feedback-info-light)` | `#331A00` |
| `var(--umds-theme-ai-pure)` | `#D39FDF` |
| `var(--umds-theme-ai-dark)` | `#DAB8E0` |
| `var(--umds-theme-ai-light)` | `#180D1C` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
## 1ds-green
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#0F4D24` |
| `var(--umds-theme-primary-pure)` | `#0C7B31` |
| `var(--umds-theme-primary-medium)` | `#4D9966` |
| `var(--umds-theme-primary-light)` | `#D0F5DC` |
| `var(--umds-theme-background-dark)` | `#1C3B26` |
| `var(--umds-theme-background-light)` | `#F4F9F7` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#1EA695` |
| `var(--umds-theme-feedback-positive-dark)` | `#1F665D` |
| `var(--umds-theme-feedback-positive-light)` | `#D0F5DF` |
| `var(--umds-theme-feedback-negative-pure)` | `#B2132E` |
| `var(--umds-theme-feedback-negative-dark)` | `#801224` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EA` |
| `var(--umds-theme-feedback-info-pure)` | `#DB6816` |
| `var(--umds-theme-feedback-info-dark)` | `#8F430B` |
| `var(--umds-theme-feedback-info-light)` | `#FFE9D9` |
| `var(--umds-theme-ai-pure)` | `#6B0780` |
| `var(--umds-theme-ai-dark)` | `#560666` |
| `var(--umds-theme-ai-light)` | `#FBE6FF` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1ds-green-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#C8EAD3` |
| `var(--umds-theme-primary-pure)` | `#8DCEA3` |
| `var(--umds-theme-primary-medium)` | `#3D7052` |
| `var(--umds-theme-primary-light)` | `#082011` |
| `var(--umds-theme-background-dark)` | `#396A47` |
| `var(--umds-theme-background-light)` | `#0B130D` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#00EED1` |
| `var(--umds-theme-feedback-positive-dark)` | `#89DCCF` |
| `var(--umds-theme-feedback-positive-light)` | `#032620` |
| `var(--umds-theme-feedback-negative-pure)` | `#F3495F` |
| `var(--umds-theme-feedback-negative-dark)` | `#F28D9D` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A0F` |
| `var(--umds-theme-feedback-info-pure)` | `#FF8000` |
| `var(--umds-theme-feedback-info-dark)` | `#FFD9B2` |
| `var(--umds-theme-feedback-info-light)` | `#331A00` |
| `var(--umds-theme-ai-pure)` | `#D39FDF` |
| `var(--umds-theme-ai-dark)` | `#DAB8E0` |
| `var(--umds-theme-ai-light)` | `#180D1C` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
## 1ds-orange
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#94511E` |
| `var(--umds-theme-primary-pure)` | `#AD5714` |
| `var(--umds-theme-primary-medium)` | `#E58A45` |
| `var(--umds-theme-primary-light)` | `#FFF1E6` |
| `var(--umds-theme-background-dark)` | `#412F21` |
| `var(--umds-theme-background-light)` | `#F9F6F4` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#0F874E` |
| `var(--umds-theme-feedback-positive-dark)` | `#0F4C30` |
| `var(--umds-theme-feedback-positive-light)` | `#CEF2E1` |
| `var(--umds-theme-feedback-negative-pure)` | `#B2132E` |
| `var(--umds-theme-feedback-negative-dark)` | `#801224` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EA` |
| `var(--umds-theme-feedback-info-pure)` | `#560999` |
| `var(--umds-theme-feedback-info-dark)` | `#3B0A66` |
| `var(--umds-theme-feedback-info-light)` | `#F3E9FB` |
| `var(--umds-theme-ai-pure)` | `#6B0780` |
| `var(--umds-theme-ai-dark)` | `#560666` |
| `var(--umds-theme-ai-light)` | `#FBE6FF` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1ds-orange-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#F8D4B9` |
| `var(--umds-theme-primary-pure)` | `#DDA678` |
| `var(--umds-theme-primary-medium)` | `#A25820` |
| `var(--umds-theme-primary-light)` | `#271407` |
| `var(--umds-theme-background-dark)` | `#49331D` |
| `var(--umds-theme-background-light)` | `#261F17` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#4CDA93` |
| `var(--umds-theme-feedback-positive-dark)` | `#2BA56E` |
| `var(--umds-theme-feedback-positive-light)` | `#12261B` |
| `var(--umds-theme-feedback-negative-pure)` | `#F3495F` |
| `var(--umds-theme-feedback-negative-dark)` | `#F28D9D` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A0F` |
| `var(--umds-theme-feedback-info-pure)` | `#A64DFF` |
| `var(--umds-theme-feedback-info-dark)` | `#E4D1F7` |
| `var(--umds-theme-feedback-info-light)` | `#1F0733` |
| `var(--umds-theme-ai-pure)` | `#D39FDF` |
| `var(--umds-theme-ai-dark)` | `#DAB8E0` |
| `var(--umds-theme-ai-light)` | `#180D1C` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
## 1ds-purple
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#560666` |
| `var(--umds-theme-primary-pure)` | `#6B0780` |
| `var(--umds-theme-primary-medium)` | `#8C4D89` |
| `var(--umds-theme-primary-light)` | `#FBE6FF` |
| `var(--umds-theme-background-dark)` | `#360640` |
| `var(--umds-theme-background-light)` | `#F9F5FA` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#0F874E` |
| `var(--umds-theme-feedback-positive-dark)` | `#0F4C30` |
| `var(--umds-theme-feedback-positive-light)` | `#CEF2E1` |
| `var(--umds-theme-feedback-negative-pure)` | `#B2132E` |
| `var(--umds-theme-feedback-negative-dark)` | `#801224` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EA` |
| `var(--umds-theme-feedback-info-pure)` | `#DB6816` |
| `var(--umds-theme-feedback-info-dark)` | `#99470C` |
| `var(--umds-theme-feedback-info-light)` | `#FFE9D9` |
| `var(--umds-theme-ai-pure)` | `#0058DB` |
| `var(--umds-theme-ai-dark)` | `#194280` |
| `var(--umds-theme-ai-light)` | `#DCE6F5` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1ds-purple-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#DAB8E0` |
| `var(--umds-theme-primary-pure)` | `#D39FDF` |
| `var(--umds-theme-primary-medium)` | `#7A3088` |
| `var(--umds-theme-primary-light)` | `#180D1C` |
| `var(--umds-theme-background-dark)` | `#530B6F` |
| `var(--umds-theme-background-light)` | `#120817` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#4CDA93` |
| `var(--umds-theme-feedback-positive-dark)` | `#2BA56E` |
| `var(--umds-theme-feedback-positive-light)` | `#12261B` |
| `var(--umds-theme-feedback-negative-pure)` | `#F3495F` |
| `var(--umds-theme-feedback-negative-dark)` | `#F28D9D` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A0F` |
| `var(--umds-theme-feedback-info-pure)` | `#FF8000` |
| `var(--umds-theme-feedback-info-dark)` | `#FFD9B2` |
| `var(--umds-theme-feedback-info-light)` | `#331A00` |
| `var(--umds-theme-ai-pure)` | `#80B6FF` |
| `var(--umds-theme-ai-dark)` | `#C7DDFF` |
| `var(--umds-theme-ai-light)` | `#0C1527` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
## 1ds-red
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#80211A` |
| `var(--umds-theme-primary-pure)` | `#C92E21` |
| `var(--umds-theme-primary-medium)` | `#D9685F` |
| `var(--umds-theme-primary-light)` | `#FFE7E5` |
| `var(--umds-theme-background-dark)` | `#412421` |
| `var(--umds-theme-background-light)` | `#FAF5F5` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#0F874E` |
| `var(--umds-theme-feedback-positive-dark)` | `#0F4C30` |
| `var(--umds-theme-feedback-positive-light)` | `#CEF2E1` |
| `var(--umds-theme-feedback-negative-pure)` | `#DD185A` |
| `var(--umds-theme-feedback-negative-dark)` | `#800E34` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EE` |
| `var(--umds-theme-feedback-info-pure)` | `#E56A2E` |
| `var(--umds-theme-feedback-info-dark)` | `#B25224` |
| `var(--umds-theme-feedback-info-light)` | `#FFE9D9` |
| `var(--umds-theme-ai-pure)` | `#6B0780` |
| `var(--umds-theme-ai-dark)` | `#560666` |
| `var(--umds-theme-ai-light)` | `#FBE6FF` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1ds-red-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#F0AEA8` |
| `var(--umds-theme-primary-pure)` | `#FF7B70` |
| `var(--umds-theme-primary-medium)` | `#A9362D` |
| `var(--umds-theme-primary-light)` | `#200F0E` |
| `var(--umds-theme-background-dark)` | `#723631` |
| `var(--umds-theme-background-light)` | `#191010` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#1EA695` |
| `var(--umds-theme-feedback-positive-dark)` | `#2BA56E` |
| `var(--umds-theme-feedback-positive-light)` | `#DCF5F2` |
| `var(--umds-theme-feedback-negative-pure)` | `#F4578D` |
| `var(--umds-theme-feedback-negative-dark)` | `#F5ADC5` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A14` |
| `var(--umds-theme-feedback-info-pure)` | `#FF8000` |
| `var(--umds-theme-feedback-info-dark)` | `#FFD9B2` |
| `var(--umds-theme-feedback-info-light)` | `#331A00` |
| `var(--umds-theme-ai-pure)` | `#D39FDF` |
| `var(--umds-theme-ai-dark)` | `#DAB8E0` |
| `var(--umds-theme-ai-light)` | `#180D1C` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
## 1ds-yellow
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#7C5F00` |
| `var(--umds-theme-primary-pure)` | `#8B6C08` |
| `var(--umds-theme-primary-medium)` | `#FAD14B` |
| `var(--umds-theme-primary-light)` | `#FFF6D9` |
| `var(--umds-theme-background-dark)` | `#403821` |
| `var(--umds-theme-background-light)` | `#FAF9F5` |
| `var(--umds-theme-background-white)` | `#FFFFFF` |
| `var(--umds-theme-background-elevated)` | `#FFFFFF` |
| `var(--umds-theme-feedback-positive-pure)` | `#0F874E` |
| `var(--umds-theme-feedback-positive-dark)` | `#0F4C30` |
| `var(--umds-theme-feedback-positive-light)` | `#CEF2E1` |
| `var(--umds-theme-feedback-negative-pure)` | `#B2132E` |
| `var(--umds-theme-feedback-negative-dark)` | `#801224` |
| `var(--umds-theme-feedback-negative-light)` | `#FFE6EA` |
| `var(--umds-theme-feedback-info-pure)` | `#E56A2E` |
| `var(--umds-theme-feedback-info-dark)` | `#B25224` |
| `var(--umds-theme-feedback-info-light)` | `#FFE9D9` |
| `var(--umds-theme-ai-pure)` | `#6B0780` |
| `var(--umds-theme-ai-dark)` | `#560666` |
| `var(--umds-theme-ai-light)` | `#FBE6FF` |
| `var(--umds-theme-neutral-dark-pure)` | `#333333` |
| `var(--umds-theme-neutral-dark-down)` | `#565656` |
| `var(--umds-theme-neutral-dark-medium)` | `#7D7D7D` |
| `var(--umds-theme-neutral-dark-up)` | `#A3A3A3` |
| `var(--umds-theme-neutral-light-down)` | `#D5D5D5` |
| `var(--umds-theme-neutral-light-medium)` | `#EBEBEB` |
| `var(--umds-theme-neutral-light-up)` | `#F6F6F6` |
| `var(--umds-theme-neutral-light-pure)` | `#FFFFFF` |
| `var(--umds-theme-field-placeholder)` | `#767676` |
## 1ds-yellow-dark
| Token | Valor |
| --- | --- |
| `var(--umds-theme-primary-dark)` | `#F5E1A3` |
| `var(--umds-theme-primary-pure)` | `#D7C075` |
| `var(--umds-theme-primary-medium)` | `#5C460A` |
| `var(--umds-theme-primary-light)` | `#1C1503` |
| `var(--umds-theme-background-dark)` | `#705700` |
| `var(--umds-theme-background-light)` | `#1A1800` |
| `var(--umds-theme-background-white)` | `#171717` |
| `var(--umds-theme-background-elevated)` | `#262626` |
| `var(--umds-theme-feedback-positive-pure)` | `#4CDA93` |
| `var(--umds-theme-feedback-positive-dark)` | `#2BA56E` |
| `var(--umds-theme-feedback-positive-light)` | `#12261B` |
| `var(--umds-theme-feedback-negative-pure)` | `#F3495F` |
| `var(--umds-theme-feedback-negative-dark)` | `#F28D9D` |
| `var(--umds-theme-feedback-negative-light)` | `#2A0A0F` |
| `var(--umds-theme-feedback-info-pure)` | `#FF8000` |
| `var(--umds-theme-feedback-info-dark)` | `#FFD9B2` |
| `var(--umds-theme-feedback-info-light)` | `#331A00` |
| `var(--umds-theme-ai-pure)` | `#D39FDF` |
| `var(--umds-theme-ai-dark)` | `#DAB8E0` |
| `var(--umds-theme-ai-light)` | `#180D1C` |
| `var(--umds-theme-neutral-dark-pure)` | `#E8E8E8` |
| `var(--umds-theme-neutral-dark-down)` | `#C9C9C9` |
| `var(--umds-theme-neutral-dark-medium)` | `#8C8C8C` |
| `var(--umds-theme-neutral-dark-up)` | `#717171` |
| `var(--umds-theme-neutral-light-down)` | `#545454` |
| `var(--umds-theme-neutral-light-medium)` | `#383838` |
| `var(--umds-theme-neutral-light-up)` | `#303030` |
| `var(--umds-theme-neutral-light-pure)` | `#1A1919` |
| `var(--umds-theme-field-placeholder)` | `#8C8C8C` |
---
# Formulários
Regras de composição de formulários com os componentes 1DS: Input, Textarea, Select,
MultiSelect, Radio, Checkbox, Switch, DatePicker, TimePicker, FileInput.
> **Antes de escrever qualquer campo:** a API Vue do 1DS não é idiomática.
> **Não existe `v-model` em componente nenhum** — nenhum declara `defineEmits`.
> Campo controlado é `:value` + `:onChange`, e o `onChange` recebe **o valor já
> extraído**, não o evento. Veja a skill `1berto` (Vue) para as quatro
> armadilhas completas.
## Labels — sempre visíveis
Todo campo tem `label` visível. Placeholder **não substitui** label: some ao digitar,
não é lido de forma confiável por leitores de tela e tem contraste reduzido.
```vue
<!-- Certo: label + placeholder como exemplo de formato -->
<Input label="CPF" placeholder="000.000.000-00" name="cpf" />
<!-- Errado: placeholder fazendo papel de label -->
<Input placeholder="CPF" name="cpf" />
```
Se por restrição de layout o label não puder aparecer (ex.: busca com ícone), use
`ariaLabel` — mas trate como exceção, não padrão. No template é `:ariaLabel`,
camelCase; `:aria-label` com hífen não chega ao componente.
| Faça | Não faça |
|---|---|
| Label curto e substantivo ("E-mail institucional") | Label como frase-instrução ("Digite aqui o seu e-mail") |
| `required` no campo obrigatório (marcador visual + validação nativa) | Asterisco manual no texto do label |
| `helperText` para instrução de formato | Instrução dentro do placeholder |
## Erro — abaixo do campo, no próprio campo
A mensagem de erro aparece **abaixo do campo** que a causou, via `errorMessage`.
Nos campos de seleção, combine com `invalid` para o estado visual.
```vue
<Input label="E-mail" name="email" errorMessage="Informe um e-mail válido." />
<Select
label="Setor"
:options="setores"
:invalid="true"
errorMessage="Selecione um setor."
:onChange="(valor) => (setor = valor)"
/>
```
Escreva booleana como `:invalid="true"`, não como atributo solto. O gerador Vue
trata prop booleana sem valor de forma diferente do JSX, e `invalid` sozinho nem
sempre chega como `true`.
| Faça | Não faça |
|---|---|
| Erro específico e acionável ("Data não pode ser anterior a hoje") | "Campo inválido" genérico |
| Manter o valor digitado para correção | Limpar o campo ao errar |
| Erro global do formulário em `Alert` no topo + erros por campo | Toast para erro de validação |
## Qual componente de seleção?
| Componente | Use quando | Não use |
|---|---|---|
| **Radio** | Escolha única entre 2–5 opções que valem a pena ficar todas visíveis | Mais de ~6 opções (vira scroll) — use `Select` |
| **Select** | Escolha única em lista média/longa; suporta `searchable`, paginação (`pagination` + `onLoadMore`) | 2–3 opções simples — `Radio` mostra tudo sem clique |
| **Checkbox** | Escolha múltipla com poucas opções visíveis, ou opt-in único ("Aceito os termos") | Listas longas de múltipla escolha — `MultiSelect` |
| **MultiSelect** | Escolha múltipla em lista longa, com tags das seleções | Quando só 1 valor é permitido — `Select` |
| **Switch** | Ligar/desligar com **efeito imediato** (aplica na hora, sem submit) | Estado que só vale após enviar o formulário — `Checkbox` |
### Switch × Checkbox — a distinção que mais erra
- **Switch = efeito imediato.** Ao alternar, o sistema já muda (ativar notificações,
tema escuro). Não existe botão "Salvar" envolvido na expectativa do usuário.
- **Checkbox = estado submetido.** O valor só vale quando o formulário for enviado
(aceitar termos, marcar opções de um cadastro).
Se o toggle está dentro de um formulário com botão de envio, é `Checkbox`.
```vue
<!-- Efeito imediato — dispara a mudança no onChange -->
<Switch
label="Receber notificações"
:checked="ativo"
:onChange="(valor) => (ativo = valor)"
/>
<!-- Estado submetido junto com o form -->
<Checkbox label="Aceito os termos de uso" name="termos" :required="true" />
```
## Integração com formulário nativo
Os componentes de seleção participam de `<form>` nativo: ao receber a prop `name`,
emitem um `<input type="hidden">` com o valor atual — o dado entra no `FormData`
e no submit sem JavaScript adicional. Isso vale para `Select`, `MultiSelect`
(um hidden por valor selecionado), `Switch`, `DatePicker` e `TimePicker`;
`Input`, `Textarea`, `Checkbox` e `Radio` usam o controle nativo diretamente.
```vue
<!-- O <form> é elemento nativo: aqui @submit é evento de verdade.
Dentro dele, os componentes do 1DS continuam recebendo callbacks por prop. -->
<form @submit.prevent="aoEnviar">
<Select
label="Setor"
name="setor"
:options="setores"
:onChange="(valor) => (setor = valor)"
/>
<Switch label="Urgente" name="urgente" value="sim" :defaultChecked="false" />
<Button type="submit">Enviar</Button>
</form>
<!-- FormData terá "setor" e, se o switch estiver ligado, "urgente=sim" -->
```
Sem `name`, o componente funciona normalmente mas fica invisível para o form nativo —
só o estado controlado via `onChange` enxerga o valor.
## Controlado × não-controlado
| Modo | Props | Use quando |
|---|---|---|
| **Controlado** | `:value` + `:onChange` (`:checked` + `:onChange` nos toggles) | O valor participa da lógica da tela: validação em tempo real, campos dependentes, máscara custom |
| **Não-controlado** | `defaultValue` (`defaultChecked` nos toggles) | Formulário simples que só lê os valores no submit (via `name` + FormData) |
```vue
<!-- Controlado — a fonte da verdade é o ref -->
<Input label="Título" :value="titulo" :onChange="(valor) => (titulo = valor)" />
<!-- Não-controlado — a fonte da verdade é o DOM; leia no submit -->
<Input label="Título" name="titulo" defaultValue="Sem título" />
```
Não misture os dois no mesmo campo: `value` sem `onChange` congela o campo;
`defaultValue` junto com `value` é ignorado. Escolha um modo por campo e mantenha.
**E não tente `v-model` em nenhum dos dois.** `v-model="titulo"` compila para
`:modelValue` + `@update:modelValue`; o componente não declara nenhum dos dois,
ignora em silêncio, e o campo nunca recebe nem devolve valor. Sem erro, sem
aviso — só não funciona.
## Estados: um sistema, não uma regra por componente
Os estados de campo vivem em tokens `--umds-semantic-field-*`. Nenhum componente
declara os valores por conta própria — foi assim que o DS chegou a ter quatro
linguagens de foco diferentes convivendo. Mudar o anel de foco de todos os campos
é editar um token.
| estado | token |
|---|---|
| borda em repouso | `--umds-semantic-field-border-default` |
| hover | `--umds-semantic-field-border-hover` |
| foco | `--umds-semantic-field-border-focus` + `--umds-semantic-field-ring-focus` |
| erro | `--umds-semantic-field-border-error` + `--umds-semantic-field-ring-error` |
| altura | `--umds-semantic-field-height` (44px, alvo de toque) |
| texto digitado | `--umds-semantic-field-text-size` / `-text-color` |
| placeholder | `--umds-semantic-field-placeholder-color` |
| label | `--umds-semantic-field-label-size` / `-weight` / `-color` |
| desabilitado | `--umds-semantic-field-disabled-opacity` / `-background` |
| somente leitura | `--umds-semantic-field-readonly-background` |
**Foco de campo e foco de não-campo são diferentes, de propósito.** Campo usa
borda mais anel de 3px; botão, aba, item de menu, dia de calendário e afins usam
`outline: 2px solid primary-pure` com offset. Se você está escrevendo um foco
novo, ele cai num desses dois — não invente um terceiro.
**Erro tem a mesma anatomia do foco**, trocando a cor. Isso não é economia de
código: é o que faz o campo em erro e o campo em foco parecerem parentes.
**Somente leitura não é desabilitado.** O campo readonly continua focável e o
anel de foco permanece — quem navega por teclado precisa saber onde está, mesmo
num campo que não aceita edição. Desabilitado é inerte; readonly é legível.
## Checklist do formulário
1. Todo campo com `label` visível (ou `ariaLabel` justificado).
2. `required` nos obrigatórios; nada de asterisco manual.
3. `errorMessage` abaixo do campo, texto acionável; erro global em `Alert`.
4. Seleção: Radio ≤ 5 opções · Select para listas · MultiSelect para múltipla longa.
5. Switch só para efeito imediato; dentro de form com submit, Checkbox.
6. `name` em tudo que precisa chegar ao submit nativo.
7. Um modo por campo: controlado (`:value`+`:onChange`) ou não-controlado (`defaultValue`).
8. Nenhum `v-model`, nenhuma prop em kebab-case, `className` em vez de `class`.
9. Estado novo? Ele já existe em `--umds-semantic-field-*` — consuma o token.
---
# IA no produto
Regras para telas onde parte do conteúdo ou parte da decisão vem de um modelo.
Valem para qualquer produto da 1Doc — 1Doc, Solar, Unique, Nexus, portais do
cidadão.
O risco que estas regras endereçam não é o modelo errar. É o usuário **não
saber** que foi o modelo, descobrir tarde, e não conseguir voltar atrás. Num
produto de processo administrativo, o texto que a IA escreveu pode virar
despacho assinado — e aí o custo do engano não é refazer uma tela, é um ato
oficial.
## 1. Sinalize saída generativa, e só ela
**Sinalize** quando o conteúdo na tela foi **gerado** por um modelo: texto
escrito, resumo produzido, sugestão redigida, classificação inferida.
**Não sinalize** o que sempre foi automático e ninguém chamava de IA: busca,
ordenação, autocompletar, validação de formato, cálculo, filtro. Marcar isso
de IA não informa — dilui o selo até ele virar decoração.
| Sinalize | Não sinalize |
| --- | --- |
| Resumo de um processo escrito pelo modelo | Resultado de busca |
| Sugestão de despacho | Ordenação por relevância |
| Classificação automática de assunto | Máscara de CPF |
| Resposta de um assistente | Autocompletar de endereço |
| Tradução automática | Cálculo de prazo |
A regra em uma frase: **se um humano pudesse ter escrito aquilo, e não
escreveu, sinalize.**
## 2. O ícone de IA é reservado
Um único tratamento visual, em todo o produto, só para saída generativa. Use
`AILabel`. Não crie sparkle próprio, não reaproveite o ícone para "novidade",
"destaque" ou "automático".
O selo é um contrato com o usuário: onde ele aparece, houve modelo. Se aparecer
onde não houve, o usuário deixa de confiar nele — e passa a ignorá-lo onde
importa.
```vue
<AILabel explanation="Resumo gerado a partir dos 12 despachos deste processo." />
```
Um selo por bloco de conteúdo, no começo do bloco. Não repita em cada
parágrafo de um texto que é todo gerado.
## 3. Sinalizar não basta: explique
Selo sem explicação informa que houve IA e esconde o que importa — com base em
quê. `AILabel` abre um painel de explicabilidade no clique, e ele deve
responder três coisas:
1. **De onde veio** — quais documentos, campos ou histórico alimentaram a saída.
2. **O que não entrou** — se o modelo só leu os últimos 12 meses, diga.
3. **O que fazer se estiver errado** — o caminho concreto de correção.
Não escreva "gerado por inteligência artificial" e pare. Isso é rótulo, não
explicação.
## 4. Edição do usuário vence, e é visível
Quando o usuário edita conteúdo gerado, o trecho editado **deixa de ser saída
de IA** e o tratamento visual sai daquele trecho. Use `AIContent`, que faz
isso e mantém a ação **reverter para a sugestão da IA**.
Duas regras que decorrem disso:
- **Nunca sobrescreva edição do usuário com nova geração.** Se o modelo rodar
de novo, ofereça a nova versão ao lado; não troque o que a pessoa escreveu.
- **Reverter é sempre possível enquanto o conteúdo não foi confirmado.** Depois
de assinado ou despachado, a versão vale por si — aí não há mais "reverter",
há emitir um novo ato.
## 5. Ação irreversível exige autorização explícita
Nenhuma ação que o usuário não possa desfazer sozinho acontece por sugestão de
modelo sem confirmação humana. Use `ConfirmAIAction`, que escalona a
confirmação pelo risco:
| Risco | O que caracteriza | Confirmação |
| --- | --- | --- |
| `baixo` | reversível em um clique, efeito só na tela | nenhuma — mas mantenha "desfazer" |
| `medio` | reversível, mas com trabalho; muda dado de outros | diálogo com resumo do que muda |
| `alto` | irreversível, ou em cascata, ou sai da organização | diálogo + digitar a confirmação, com a lista do que será afetado |
Na 1Doc, `alto` é o caso comum e não a exceção: assinar, despachar, tramitar,
arquivar, notificar o cidadão. Todos irreversíveis ou visíveis fora da
organização.
**Cascata conta como alto risco mesmo quando cada passo é reversível.** Uma
ação que dispara cinco tarefas em quatro setores é irreversível na prática: o
usuário não consegue percorrer os cinco pontos para desfazer.
E a lista do que será afetado não é enfeite do diálogo — é ela que permite ao
usuário perceber que a sugestão pegou o processo errado.
## 6. Erro e incerteza
- **Não invente confiança.** Se o modelo não achou base para responder, o
produto diz isso. Resposta vazia honesta é melhor que resposta plausível.
- **Não exponha porcentagem de confiança** para o usuário final. "87% de
certeza" não é acionável para quem vai despachar; o que é acionável é a
fonte.
- **Falha do modelo é falha do sistema**, com a mesma linguagem dos outros
erros. Não peça desculpas em nome da IA, não personifique.
## 7. O que nunca é da IA
Três decisões não são delegáveis, por mais confiável que o modelo esteja:
1. **Assinar.** A assinatura é do servidor público, não do assistente.
2. **Classificar sigilo.** O nível de sigilo tem consequência legal.
3. **Concluir prazo legal.** Contagem de prazo é ato vinculado.
O modelo pode sugerir as três. Nenhuma se efetiva sem ato humano explícito.
## Componentes
| Componente | Para quê |
| --- | --- |
| `AILabel` | selo de saída generativa, com painel de explicabilidade |
| `AIContent` | envolve o conteúdo gerado, some ao ser editado, oferece reverter |
| `ConfirmAIAction` | confirmação escalonada por nível de risco |
Os três estão em **Preview** — a API pode mudar sem aviso. Leia
`Preview/Sobre o Preview` antes de usar em produção.
---
# Modal × ConfirmDialog × Toast × Alert
Quatro componentes de sobreposição, quatro trabalhos diferentes. Escolher errado gera fricção:
modal para feedback trivial interrompe o usuário; toast para decisão destrutiva a esconde.
> **API Vue:** `onConfirm`, `onClose`, `onCancel` são **props**, não eventos.
> Escreva `:onConfirm="salvar"`, não `@confirm="salvar"`. `@confirm` não existe —
> nenhum componente do 1DS declara `defineEmits`.
## Decisão rápida
| Situação | Componente |
|---|---|
| Fluxo ou conteúdo que exige atenção total (formulário, detalhe, wizard) | **Modal** |
| Decisão binária de risco — excluir, cancelar, sair sem salvar | **ConfirmDialog** |
| Feedback transitório após uma ação ("Registro salvo") | **Toast** |
| Aviso persistente de contexto da página ("Ambiente de homologação") | **Alert** |
## Modal — fluxo e conteúdo
O Modal bloqueia a página para carregar **conteúdo**: formulários, detalhes, confirmações ricas
com corpo customizado. Suporta variantes semânticas, rodapé customizado (`footerSlot`) e corpo
livre (slot padrão).
```vue
<Modal
:open="aberto"
variant="default"
title="Editar setor"
confirmLabel="Salvar"
cancelLabel="Cancelar"
:onConfirm="salvar"
:onClose="() => (aberto = false)"
>
<!-- formulário, conteúdo rico -->
</Modal>
```
O corpo vai no **slot padrão**. `footerSlot` é slot nomeado — confira a seção *Slots* da
página do componente antes de usar: se o nome não estiver listado lá, ele não existe e o
conteúdo precisa ir por prop.
| Use quando | Não use |
|---|---|
| O usuário precisa concluir uma tarefa antes de voltar à página | Para confirmar exclusão simples — use `ConfirmDialog` |
| O conteúdo não cabe num tooltip/popover e exige foco | Para avisar que algo deu certo — use `Toast` |
| Há mais de dois desfechos possíveis ou corpo com inputs | Modal dentro de modal — repense o fluxo |
## ConfirmDialog — decisão binária
Versão especializada para **uma pergunta, duas saídas**. Só tem duas variantes, de propósito:
`negative` (destrutivo/irreversível) e `info` (atenção). Não existe variante "positiva" — confirmação
de sucesso não é pergunta.
```vue
<ConfirmDialog
:open="aberto"
variant="negative"
title="Excluir documento?"
description="Esta ação não pode ser desfeita."
confirmLabel="Excluir"
cancelLabel="Cancelar"
:confirmLoading="excluindo"
:onConfirm="excluir"
:onCancel="() => (aberto = false)"
/>
```
| Use quando | Não use |
|---|---|
| Ação destrutiva ou irreversível (`variant="negative"`) | Quando a ação é reversível com undo — prefira `Toast` + desfazer |
| Ponto de atenção antes de prosseguir (`variant="info"`) | Quando precisa de inputs no corpo — use `Modal` |
| A resposta é literalmente sim/não | Para informar sem perguntar — use `Alert` |
Use `confirmLoading` durante a chamada assíncrona — desabilita o botão e evita duplo submit.
A prop `inline` existe só para documentação/Storybook (overlay relativo em vez de `fixed`).
## Toast — feedback transitório
Notificação **pós-ação**, autodescartável, que não bloqueia nada. Variantes: `positive`,
`negative`, `info`.
```vue
<Toast
:open="aberto"
variant="positive"
message="Documento enviado"
description="Protocolo 2026/0001 gerado."
position="top-right"
:duration="5000"
:closable="true"
:onClose="() => (aberto = false)"
/>
```
Repare em `:duration="5000"` e `:closable="true"`: número e booleana precisam do
`:`. `duration="5000"` sem os dois-pontos passa a **string** `"5000"`, e `closable`
como atributo solto não chega de forma confiável como `true`.
| Use quando | Não use |
|---|---|
| Confirmar resultado de uma ação que o usuário acabou de fazer | Para erro que exige correção do usuário — mostre erro no campo ou `Alert` |
| A informação perde valor em segundos | Para conteúdo que o usuário precisa reler — `Alert` persistente |
| Não é necessária nenhuma resposta | Para pedir decisão — `ConfirmDialog` |
Com `:duration="0"` (padrão) o toast não fecha sozinho — só use isso para erros; sucesso
deve expirar (4–6s).
**Em story ou demo, use o Toast inline.** Um toast `fixed` numa página de
documentação cobre o conteúdo que a pessoa está tentando ler.
## Alert — aviso persistente de contexto
Aviso que **pertence à página**, não a uma ação. Fica visível até ser dispensado
(`dismissable`) ou até o contexto mudar. Variantes: `neutral`, `positive`, `info`, `negative`,
com `appearance="soft" | "solid"`.
```vue
<Alert
variant="info"
appearance="soft"
title="Manutenção programada"
:dismissable="true"
>
O sistema ficará indisponível no sábado das 22h às 23h.
</Alert>
```
| Use quando | Não use |
|---|---|
| Estado do sistema/página que o usuário precisa saber ao chegar | Para reagir a um clique — `Toast` |
| Erro de validação global de um formulário | Para bloquear a navegação — `Modal`/`ConfirmDialog` |
| Aviso que deve sobreviver a re-render e scroll | Empilhar vários alerts — consolide a mensagem |
## Escala de camadas (z-index)
A ordem de empilhamento é fixa e vem de tokens semânticos — **nunca** hardcode `z-index`
em código de aplicação:
| Token | Valor | Componentes |
|---|---|---|
| `--umds-semantic-layer-modal` | 1300 | Modal, ConfirmDialog |
| `--umds-semantic-layer-popover` | 1400 | Select, MultiSelect, Dropdown, DatePicker, TimePicker, PhoneInput |
| `--umds-semantic-layer-toast` | 1500 | Toast, Alert fixo |
| `--umds-semantic-layer-tooltip` | 1600 | Tooltip |
**Por que popover fica acima de modal?** Porque pickers vivem dentro de diálogos: um
`Select` ou `DatePicker` aberto dentro de um `Modal` precisa renderizar o painel flutuante
por cima do próprio modal (1400 > 1300). Se modal fosse a camada mais alta, todo dropdown
dentro de formulário modal ficaria cortado. Toast fica acima de ambos (feedback nunca deve
ser escondido por um diálogo aberto) e tooltip é sempre a camada mais alta — ele segue o
cursor/foco e some sozinho.
---
# Paginação
O `Pagination` tem cinco variantes. Todas compartilham a mesma API de navegação
(`page`, `totalPages`, `onPageChange`) — o que muda é a densidade e o contexto de uso.
```ts
variant?: "default" | "alternative" | "resumed" | "full-width" | "bordered";
```
> **API Vue:** `onPageChange` é **prop**, não evento — `:onPageChange="irPara"`,
> nunca `@page-change`. E `page` e `totalPages` são números: precisam do `:`,
> senão chegam como string e a navegação não anda.
## Decisão rápida
| Contexto | Variante |
|---|---|
| Lista longa onde o usuário salta para uma página específica | `default` |
| Pouco espaço horizontal (painéis, colunas estreitas) | `alternative` |
| Rodapé de tabela com contagem de itens ("1–20 de 240") | `resumed` |
| Navegação exploratória de página em página, largura total | `full-width` |
| Toolbar ou card com paginação embutida | `bordered` |
## default — campo de página para listas longas
Setas + campo numérico para digitar a página de destino. É a escolha para listas
longas (centenas de páginas) onde clicar seta a seta é inviável e o usuário sabe
aonde quer ir.
```vue
<Pagination
:page="pagina"
:totalPages="480"
:onPageChange="(n) => (pagina = n)"
/>
```
| Use quando | Não use |
|---|---|
| `totalPages` grande e salto direto é útil (resultados de busca, protocolos) | Meia dúzia de páginas — o campo é overhead |
| O número da página tem significado para o usuário | Navegação puramente sequencial — `full-width` |
## alternative — compacto
Mesma mecânica do `default` (setas + campo), em apresentação compacta. Para onde
o `default` não cabe.
```vue
<Pagination
variant="alternative"
:page="pagina"
:totalPages="480"
:onPageChange="(n) => (pagina = n)"
/>
```
| Use quando | Não use |
|---|---|
| Sidebars, painéis, modais e colunas estreitas | Há espaço de sobra — `default` é mais confortável de acionar |
## resumed — tabelas com contagem de itens
Exibe o intervalo de itens visível a partir de `pageSize` e `totalItems`
("1–20 de 240"). É a variante de rodapé de `DataTable`.
```vue
<Pagination
variant="resumed"
:page="pagina"
:totalPages="12"
:pageSize="20"
:totalItems="240"
:onPageChange="(n) => (pagina = n)"
/>
```
| Use quando | Não use |
|---|---|
| Rodapé de tabela/listagem onde saber "quantos no total" importa | Quando não há `totalItems` confiável (scroll infinito, busca aproximada) |
| Relatórios e telas administrativas | Navegação exploratória sem noção de item |
## full-width — navegação exploratória
Botões numerados com reticências (`siblingCount` controla os vizinhos da página atual),
ocupando a largura disponível, com rótulos anterior/próximo (`prevLabel`/`nextLabel`).
Para conteúdo que se folheia: o usuário avança e recua mais do que salta.
```vue
<Pagination
variant="full-width"
:page="pagina"
:totalPages="32"
:siblingCount="1"
prevLabel="Anterior"
nextLabel="Próxima"
:onPageChange="(n) => (pagina = n)"
/>
```
| Use quando | Não use |
|---|---|
| Listas de artigos, galerias, resultados que se percorrem em sequência | Dentro de cards e toolbars — `bordered` |
| A paginação é o elemento de navegação principal da área | Milhares de páginas com salto direto frequente — `default` |
## bordered — toolbars e cards
Mesma numeração do `full-width`, mas contida em botões com borda — visual de controle,
não de navegação de página inteira. Encaixa em toolbars, cabeçalhos de card e regiões
com outros controles ao redor.
```vue
<Pagination
variant="bordered"
:page="pagina"
:totalPages="8"
:onPageChange="(n) => (pagina = n)"
/>
```
| Use quando | Não use |
|---|---|
| Toolbar de uma seção, card com lista interna paginada | Rodapé de página inteira — `full-width` |
| Vários controles lado a lado (filtros, ordenação, paginação) | Quando precisa da contagem de itens — `resumed` |
## Regras gerais
- **Uma variante por tela.** Tabela com `resumed` no rodapé não ganha outra paginação no topo.
- `page` é controlado: atualize o `ref` dentro de `onPageChange`, senão a navegação não anda.
**Não existe `v-model:page`** — nenhum componente do 1DS emite eventos.
- `:disabled="true"` durante o carregamento da nova página evita cliques duplicados.
- Persistir a página atual (querystring ou `sessionStorage`) ao navegar para detalhe
e voltar — perder a página é a reclamação nº 1 de listagens paginadas.
---
# Design Tokens
Como o `@1doc/1ds-tokens` está organizado e as regras para consumi-lo sem quebrar
tematização, dark mode e acessibilidade. Os tokens são CSS puro: **valem igual em
React e em Vue**, e não há nada de framework nesta página.
## Hierarquia: primitivo → semântico → tema
| Camada | Prefixo | O que é | Exemplo |
|---|---|---|---|
| **Primitivo** | `--umds-primitive-*` | Valor bruto, sem significado de uso | `--umds-primitive-spacing-xxxs: 16px` |
| **Semântico** | `--umds-semantic-*` | Papel na interface; aponta para primitivos | `--umds-semantic-color-primary-pure` |
| **Tema** | `data-theme` no `<html>` | Reatribui os semânticos de cor por marca/modo | `[data-theme="1doc-dark"]` |
O componente consome a camada semântica; o tema decide o valor final. É isso que permite
trocar a marca inteira sem tocar em CSS de componente.
```css
/* Componente: papel, não valor */
.umds-button--primary {
background: var(--umds-semantic-color-primary-pure);
padding: var(--umds-primitive-spacing-nano); /* espaçamento usa primitivo */
}
```
## A escala não é a convenção de camiseta
É o erro mais caro desta página, porque **não dá erro nenhum**: o build passa, o
typecheck passa, o auditor de token aprova. O componente só sai grande demais.
Quase todo design system usa `xxs=2 · xs=4 · sm=8 · md=16`. **A do 1DS é outra** —
os nomes pequenos são valores grandes:
```
micro 2 · quarck 4 · nano 8 · mini 12 · xxxs 16 · xxs 24 · xs 32 · sm 40 · md 48
lg 56 · xl 64 · xxl 80 · xxxl 120 · huge 160 · giant 200
```
`--umds-primitive-spacing-xs` é **32px**, não 8. `spacing-sm` é **40px**, não 16.
Vale também para tipografia, com deslocamento menor:
```
font-size: xxxs 12 · xxs 14 · xs 16 · sm 20 · md 24 · lg 32 · xl 40
```
O corpo de texto do DS é `font-size-xxs` (14px). `font-size-sm` é **20px**, tamanho
de título de diálogo.
| Quero | Token |
|---|---|
| 4px | `spacing-quarck` |
| 8px | `spacing-nano` |
| 12px | `spacing-mini` |
| 16px | `spacing-xxxs` |
| 14px de texto (corpo) | `font-size-xxs` |
**Na dúvida, copie a geometria de um componente que já existe** em vez de escolher
o token pelo nome: `Tag`/`Badge` para pílula, `Input` para campo, `ConfirmDialog`
para conteúdo de diálogo.
## Regra de ouro: cor SÓ via token semântico
Em CSS de componente é **proibido**: hex de cor, `rgb()`/`hsl()` de marca, tokens do
protótipo (`--bg-white`, `--primary-pure`, `--space-4`…) e primitivos de **cor**
(`--umds-primitive-colors-*`). Cor hardcoded ignora os 12 temas — fica azul 1Doc
no tema vermelho e clara no dark.
| Faça | Não faça |
|---|---|
| `color: var(--umds-semantic-color-neutral-dark-pure)` | `color: #333333` |
| `background: var(--umds-semantic-color-feedback-negative-light)` | `background: rgb(255, 230, 234)` |
| Espaçamento/raio/fonte via `--umds-primitive-*` | `--space-4`, `--radius-xl` (tokens do protótipo) |
Exceção única: sombras (`rgba(0,0,0,…)`) e valores sem equivalente 1DS — sempre com
comentário `/* candidato a novo token */` justificando.
### As famílias semânticas de cor
| Família | Para quê |
|---|---|
| `primary` | **Ação.** Botão, link, foco, seleção. |
| `background` | Superfícies da página. |
| `feedback-positive` / `-negative` / `-info` | Resultado e risco. `info` é o **laranja** de atenção, não azul. |
| `ai` | **Conteúdo gerado por IA.** Selo, marcação de bloco. |
| `neutral` | Texto, borda, separador. |
`primary` e `ai` existem separadas de propósito: primary é ação, `ai` é origem do
conteúdo. Um selo de IA na cor de ação, ao lado de um botão, não comunica nada.
`ai` tem `pure`/`dark`/`light`, como `feedback` — não existe `ai-medium`.
O que **não** vira `ai`, mesmo dentro de um bloco de IA: o anel de foco (é
`primary-pure` em todo o DS, porque foco é indicador de sistema) e os botões (são
ação do usuário).
## Temas: 12 combinações via `data-theme`
São 6 marcas × light/dark, ativadas com um atributo no `<html>`:
```
1doc 1ds-red 1ds-green 1ds-orange 1ds-yellow 1ds-purple
1doc-dark 1ds-red-dark 1ds-green-dark 1ds-orange-dark 1ds-yellow-dark 1ds-purple-dark
```
```js
document.documentElement.setAttribute("data-theme", "1doc");
```
Ordem de import na aplicação: `primitives.css` → `semantic.css` → tema (ex.: `theme-1doc.css`)
→ CSS dos componentes. Cada tema só reatribui os tokens semânticos de **cor** — espaçamento,
tipografia e motion são globais.
Dark mode é um tema como outro qualquer (`*-dark`), não um filtro: cada token de cor tem
valor próprio calibrado para contraste AA. Nunca simule dark com `filter: invert()`.
**Uma família pode trocar de matiz entre temas para não colidir com o primary.**
`feedback-info` é laranja nos temas azul e roxo, e vira roxo no tema laranja. `ai` é
roxo em quase todos, e vira azul nos temas roxos. É regra da casa, não inconsistência.
## Motion
Tokens semânticos de movimento, usados em toda transição/animação de componente:
| Token | Valor | Uso |
|---|---|---|
| `--umds-semantic-motion-duration-fast` | 150ms | Micro-interações: hover, foco, cor |
| `--umds-semantic-motion-duration-base` | 250ms | Entrada/saída de painéis e diálogos |
| `--umds-semantic-motion-easing-standard` | `cubic-bezier(0.4, 0, 0.2, 1)` | Curva padrão |
| `--umds-semantic-motion-easing-bounce` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Overshoot em entrada de diálogos |
```css
.umds-dropdown-menu {
animation: umds-dropdown-in
var(--umds-semantic-motion-duration-fast)
var(--umds-semantic-motion-easing-standard) both;
}
```
### `prefers-reduced-motion` é global
O build dos tokens injeta em `semantic.css` um bloco `@media (prefers-reduced-motion: reduce)`
que zera as durações de motion para o sistema inteiro (WCAG 2.3.3). Consequência prática:
**quem usa os tokens de motion ganha reduced-motion de graça** — não escreva media query
por componente, nem duração literal (`transition: 0.2s`) que escaparia da redução global.
## Camadas (z-index)
Empilhamento também é token — ver a página **Guidelines/Overlays** para a escala completa
(`--umds-semantic-layer-modal` 1300 → `tooltip` 1600). Nunca hardcode `z-index`.
## Como propor um token novo
1. **Confirme que não existe.** A página **Foundation/Tokens** lista todos os tokens
publicados, com o valor resolvido em cada tema.
2. **No CSS**, use o valor literal com o comentário-marcador:
```css
font-size: 18px; /* candidato a novo token */
```
O `token-auditor` reconhece o marcador e não acusa a linha como violação cega.
3. **Não invente o token por conta própria**: nome, camada (primitivo × semântico) e valor
são decisão de design system.
4. Aprovado, o token entra em `packages/tokens/src/` (primitivo, semântico ou tema),
o build regenera os CSS e os literais marcados são substituídos pela variável.
**Família de cor nova precisa entrar nos 12 temas** e na lista escrita à mão da
página Foundation/Colors — senão não aparece na documentação.
| Faça | Não faça |
|---|---|
| Literal + `/* candidato a novo token */` quando não há equivalente | Criar `--umds-*` novo direto no CSS do componente |
| Escolher o token semântico pelo **papel** (texto, borda, feedback) | Escolher pelo valor visual ("esse cinza parece igual") |
| Resolver o token para px e olhar a tela antes do commit | Confiar que o nome do token corresponde ao valor que você quis |
---
# Tooltips
Tooltip **esclarece** um elemento visível — nunca carrega conteúdo essencial.
Ele só aparece em hover/foco: usuários de touch, quem navega rápido e quem nunca
pousa o mouse ali simplesmente não veem o que está dentro dele. Se a informação for
necessária para completar a tarefa, ela precisa estar na tela.
```vue
<Tooltip content="Baixar em PDF">
<Button ariaLabel="Baixar">
<Icon :icon="faDownload" />
</Button>
</Tooltip>
```
O trigger vai no **slot padrão**. `:icon="faDownload"` com os dois-pontos: o ícone
é um objeto importado do Font Awesome, não uma string.
## Use quando / Não use
| Use quando | Não use |
|---|---|
| Nomear um botão só-ícone | Explicar o fluxo inteiro da tela — reescreva a UI |
| Expandir uma sigla ou termo técnico | Mensagem de erro de campo — use `errorMessage` do próprio campo |
| Dar contexto curto a um valor ("Atualizado há 2 min") | Conteúdo que o usuário precisa comparar com o resto da tela |
| Antecipar consequência de uma ação ("Remove sem excluir o arquivo") | Avisos importantes — `Alert` é persistente, tooltip é efêmero |
## Conteúdo: máximo 1–2 linhas
Texto curto, sem pontuação decorativa, sem markdown. Se passar de duas linhas, o conteúdo
não cabe em tooltip — mova para `helperText`, `description`, um `Alert` ou a própria página.
O componente aceita `title` + `content`, mas o total continua tendo que caber no bater de olhos:
o tooltip fecha quando o cursor sai.
```vue
<!-- Certo: uma linha, direto -->
<Tooltip content="Sigla do setor de origem">…</Tooltip>
<!-- Errado: parágrafo — ninguém termina de ler -->
<Tooltip content="Este campo representa a sigla do setor de origem do documento, que é definida no cadastro de setores e utilizada em relatórios…">…</Tooltip>
```
## Posicionamento: 12 posições, seta estática
A posição é `side` × `align` — 4 lados (`top`, `bottom`, `left`, `right`) × 3 alinhamentos
(`start`, `center`, `end`) = 12 posições. A **seta é estática** em relação ao placement
escolhido: ela marca o lado/alinhamento configurado, não persegue o trigger. Escolha o
placement que aponte para o elemento certo em vez de confiar em reposicionamento.
```vue
<Tooltip
content="Filtrar resultados"
side="bottom"
align="start"
:sideOffset="8"
>
<Button>Filtros</Button>
</Tooltip>
```
Props numéricas (`:sideOffset`, `:delayDuration`) precisam do `:`; e são camelCase —
`:side-offset` com hífen não chega ao componente.
- Padrão: `side="top"` + `align="center"` — mantenha, salvo colisão com a borda da tela.
- `sideOffset` ajusta a distância do trigger; não use para "empurrar" o tooltip para outro elemento.
- `delayDuration` controla o atraso de abertura — não zere em barras com muitos ícones,
ou vira um efeito estroboscópico ao passar o mouse.
## Nunca controles interativos dentro
Tooltip fecha ao perder hover/foco — botões, links e inputs dentro dele são inalcançáveis
por teclado e instáveis por mouse. O `content` é `string` de propósito.
| Precisa de… | Use |
|---|---|
| Ações (botões, links) junto do texto flutuante | `Dropdown` |
| Conteúdo rico que permanece aberto para interação | `Modal` ou painel inline |
| Confirmação antes de agir | `ConfirmDialog` |
## Alternativas antes do tooltip
1. **Rótulo visível** — se há espaço para texto, mostre o texto; tooltip em botão com label é redundância.
2. **`helperText`/`description`** — instrução de preenchimento pertence ao campo, sempre visível.
3. **Texto na página** — se todo usuário precisa da informação, ela não pode ser opcional.
4. **`disabled`** — para explicar por que um botão está desabilitado, prefira mostrar o motivo
ao lado; tooltip em elemento desabilitado não recebe hover/foco de forma confiável.
## Acessibilidade
- O trigger precisa ser focável: o tooltip abre também no foco de teclado, não só no hover.
- Tooltip **complementa**, não substitui, o nome acessível: botão só-ícone continua precisando
de `ariaLabel` mesmo com tooltip.
- Esc fecha o tooltip — não intercepte a tecla no trigger.
---