@aspprev/versi-ds 0.1.0 → 0.2.0

package/README.md

@@ -1,463 +1,183 @@
-# @aspprev/versi-ds
+# Versi Design System
 
-Biblioteca de componentes React e fundamentos visuais da VERSI para construir interfaces consistentes. Reúne controles de formulário, navegação, tabelas, gráficos, diálogos, feedback, tipografia, tokens, temas e recursos de acessibilidade.
+Biblioteca React de componentes, tokens, temas e utilitários para padronizar as interfaces dos produtos ASPPrev.
 
-Use o DS para compor a interface; a aplicação continua responsável por dados, validação de negócio, requisições, navegação e persistência das preferências do usuário.
+O [Storybook](#storybook) é a documentação visual oficial: nele você pode explorar componentes, foundations, temas, padrões de composição e estados acessíveis.
 
-## Por onde começar
-
-1. Instale o pacote e as dependências das camadas que vai usar.
-2. Importe os estilos uma vez na entrada da aplicação.
-3. Configure fonte, tema e preferências no elemento `html`.
-4. Comece pelos exemplos de componentes e formulários abaixo.
-5. Consulte o Storybook para explorar variantes, estados e propriedades.
-
-## Instalação e consumo
-
-Depois da publicação:
+## Instalação
 
 ```bash
 npm install @aspprev/versi-ds react react-dom
 ```
 
-Durante a preparação, instale o `.tgz` produzido por `npm pack` em um consumidor piloto. O pacote fornece ESM e declarações TypeScript; não fornece uma distribuição CommonJS. Suporta React/React DOM 18.2 ou 19. Node >=20.19 é necessário para desenvolvimento/build.
-
-```tsx
-import { Button } from "@aspprev/versi-ds/core";
-import "@aspprev/versi-ds/styles.css";
-import "@aspprev/versi-ds/themes.css"; // paletas opcionais, depois dos estilos
-
-export function Example() {
-  return <Button>Continuar</Button>;
-}
-```
-
-O CSS já está compilado: consumidores não precisam instalar Tailwind nem escanear o pacote. Importe-o uma vez na entrada da aplicação. Ele inclui estilos base/reset do Tailwind; carregue as personalizações da aplicação depois dos estilos do DS.
-
-Os componentes básicos não exigem um provider global. Alguns controles precisam de contexto específico, como Formik nos formulários. Se a aplicação já usa React, preserve a versão compatível instalada em vez de adicionar uma segunda cópia.
-
-## Entrypoints públicos
-
-Todos os sufixos abaixo pertencem a `@aspprev/versi-ds`.
-
-| Entrada       | Conteúdo                                                                                                                         | Peers adicionais                            |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| raiz          | API completa de compatibilidade                                                                                                  | Instale todos os peers opcionais            |
-| `/core`       | Botões, tipografia, superfícies, avisos, avatares, imagens, tooltips, paginação, tabelas, status, layout e primitivas acessíveis | Nenhum                                      |
-| `/forms`      | Input/InputStandalone, InputSelect, TextArea, InputPhone, SelectCountry, SelectMulti, DatePicker, RadioGroup, RadioCardGroup     | `formik`, `date-fns`, `react-number-format` |
-| `/charts`     | LazyApexChart, TimeSeriesChart, InteractiveDonutChart, TimeRangeSelector e utilitários                                           | `apexcharts`, `react-apexcharts`            |
-| `/overlays`   | Modal, InputSwitch, AccessibilityPreferencesPanel, HighContrastToggle                                                            | `@headlessui/react`                         |
-| `/documents`  | BoletoBarCode e DocumentItem                                                                                                     | `jsbarcode`                                 |
-| `/countries`  | COUNTRY_OPTIONS, PHONE_COUNTRY_OPTIONS, getCountryOptions, getCountryFlagUrl, filterCountryOptions e tipos                       | Nenhum                                      |
-| `/styles.css` | Tokens, modos, componentes e utilitários compilados                                                                              | —                                           |
-| `/themes.css` | Presets de paletas                                                                                                               | —                                           |
+Requisitos do pacote:
 
-Use as versões compatíveis declaradas em `peerDependencies`. Os peers opcionais permitem instalar somente `/core` e `/countries`; uma entrada de camada resolve todas as suas dependências estáticas, mesmo quando apenas um componente é importado. A raiz reexporta as camadas e não isola esses peers. ApexCharts é carregado dinamicamente no navegador.
+- Node.js `>=20.19.0`;
+- React `>=18.2.0 <20`;
+- React DOM `>=18.2.0 <20`.
 
-Os controles integrados com Formik, incluindo SelectCountry e InputPhone, devem ficar dentro de `<Formik>`. `InputStandalone` dispensa contexto Formik, mas a entrada `/forms` ainda requer seus peers.
+As integrações abaixo são opcionais e só precisam ser instaladas pelas entradas que as utilizam: `@headlessui/react`, `apexcharts`, `date-fns`, `formik`, `jsbarcode`, `react-apexcharts` e `react-number-format`.
 
-Instale apenas as integrações utilizadas, respeitando as faixas do manifesto:
+## Uso
 
-```bash
-# Formulários
-npm install formik@^2.4.9 date-fns@^4.1.0 react-number-format@^5.4.4
-
-# Gráficos
-npm install apexcharts@5.3.6 react-apexcharts@^1.9.0
+Importe o CSS global uma vez na entrada da aplicação:
 
-# Diálogos e preferências
-npm install @headlessui/react@^2.2.9
-
-# Código de barras
-npm install jsbarcode@^3.12.3
+```tsx
+import "@aspprev/versi-ds/styles.css";
+import "@aspprev/versi-ds/themes.css";
 ```
 
-Para gráficos, mantenha a versão de ApexCharts indicada: ela faz parte do contrato de dependências validado pelo pacote.
-
-`CountrySelect`, `MultiSelect`, `PhoneInput`, `Datepicker` e `CheckBox` permanecem aliases depreciados. Prefira `SelectCountry`, `SelectMulti`, `InputPhone`, `DatePicker` e `Checkbox`. Não use deep imports de componentes em `dist` ou `src`.
-
-## Escolhendo os componentes
-
-| Necessidade                   | Componentes                                                                                           |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
-| Ações e navegação             | Button, Pagination, PageTabsHeader                                                                    |
-| Texto e hierarquia            | Typography, PageHeading, TextGroup, Divider                                                           |
-| Estrutura                     | Surface, ModalCard, FormGrid, FormActions, InfoGrid, InfoItem, FilterBar                              |
-| Avisos, status e carregamento | Notice, StatusBadge, DomainStatusBadge, PageState, LoadingDots, CircularLoading                       |
-| Identidade e apoio visual     | Avatar, ThemedImage, IconProvider, Tooltip                                                            |
-| Texto, seleção e datas        | Input, InputStandalone, InputSelect, TextArea, SelectMulti, DatePicker                                |
-| Países e telefones            | SelectCountry, InputPhone                                                                             |
-| Opções e valores graduais     | Checkbox, RadioGroup, RadioCardGroup, InputSwitch, Slider, InputSlider                                |
-| Dados tabulares               | Table, MobileCardTable                                                                                |
-| Visualizações                 | TimeSeriesChart, InteractiveDonutChart, TimeRangeSelector, LazyApexChart                              |
-| Diálogos e documentos         | Modal, DocumentItem, BoletoBarCode                                                                    |
-| Acessibilidade                | SkipLink, FocusNavigationMode, FormErrorNavigation, AccessibilityPreferencesPanel, HighContrastToggle |
-
-Essa tabela organiza os componentes por finalidade. Consulte os entrypoints para escolher o import: Checkbox está em `/core`, RadioGroup em `/forms` e InputSwitch em `/overlays`, por exemplo.
-
-## Componentes básicos na prática
+Use componentes pela raiz ou por um entrypoint público:
 
 ```tsx
-import {
-  Button,
-  Notice,
-  StatusBadge,
-  Surface,
-  Typography,
-} from "@aspprev/versi-ds/core";
+import { Button, Surface, Typography } from "@aspprev/versi-ds";
+import { Input, OtpCodeInput } from "@aspprev/versi-ds/forms";
+import { FileDropzone, QRCode } from "@aspprev/versi-ds/documents";
 
 export function Resumo() {
   return (
-    <Surface tone="card" padding="default" elevation="sm">
-      <Typography element="h2" semanticRole="section-title">
-        Dados do cadastro
-      </Typography>
-      <Typography semanticRole="body">
-        Confira as informações antes de continuar.
+    <Surface tone="card" padding="default">
+      <Typography element="h1" semanticRole="section-title">
+        Meu cadastro
       </Typography>
-      <StatusBadge tone="success" appearance="soft">
-        Atualizado
-      </StatusBadge>
-      <Notice type="info">
-        Você pode revisar os dados a qualquer momento.
-      </Notice>
-      <Button type="button" variant="outline" color="primary">
-        Revisar
-      </Button>
+      <Button type="button">Continuar</Button>
     </Surface>
   );
 }
 ```
 
-| Componente  | Propriedades frequentes                                                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Button      | `variant`: flat/outline/plain; `color`: primary/secondary/tertiary/danger/warning; `size`: small/medium/large; `width`: auto/full; `loading`, `loadingLabel`, `disabled` |
-| Typography  | `element`: elemento HTML; `semanticRole`: page-title/section-title/body/label/caption/helper; `size`, `weight`, `variant`                                                |
-| Surface     | `tone`: card/subtle/muted/disabled/info/success/warning/danger/transparent; `padding`: none/compact/default; `elevation`: none/sm/md; `radius`: none/sm/md               |
-| Notice      | `type`: info/primary/secondary/tertiary/gray/success/warning/danger; `onDismiss`, `icon`, `rounded`                                                                      |
-| StatusBadge | `tone`: neutral/info/success/warning/danger; `appearance`: outline/soft/solid; `size`: sm/md                                                                             |
-
-Em Typography, `semanticRole` define a apresentação; `element` define a semântica HTML. Use `element="h1"` para o título principal e níveis coerentes para as seções. Uma etiqueta de status precisa de texto compreensível, além da cor.
-
-Para uma ação em andamento, use `loading` e um `loadingLabel` descritivo no Button. Dentro de formulários, declare `type="submit"` para enviar e `type="button"` para as demais ações.
-
-## Formulários
-
-Use Input quando o estado pertence ao Formik e InputStandalone quando a aplicação fornece `value` e `onChange` diretamente. A aplicação define a validação e o envio; o DS apresenta os controles e seus estados.
-
-### Formulário com Formik
-
-```tsx
-import { Form, Formik } from "formik";
-import { Button, FormActions, FormGrid } from "@aspprev/versi-ds/core";
-import { Input, InputSelect } from "@aspprev/versi-ds/forms";
-
-type Valores = { nome: string; categoria: string };
-
-export function Cadastro({
-  salvar,
-}: {
-  salvar: (values: Valores) => Promise<void>;
-}) {
-  return (
-    <Formik<Valores>
-      initialValues={{ nome: "", categoria: "" }}
-      validate={(values) => {
-        const errors: Partial<Record<keyof Valores, string>> = {};
-        if (!values.nome.trim()) errors.nome = "Informe seu nome.";
-        if (!values.categoria) errors.categoria = "Selecione uma categoria.";
-        return errors;
-      }}
-      onSubmit={salvar}
-    >
-      {({ isSubmitting }) => (
-        <Form>
-          <FormGrid columns={2}>
-            <Input name="nome" label="Nome completo" autoComplete="name" />
-            <InputSelect
-              name="categoria"
-              label="Categoria"
-              options={[
-                { label: "Pessoa física", value: "pessoa-fisica" },
-                { label: "Pessoa jurídica", value: "pessoa-juridica" },
-              ]}
-            />
-          </FormGrid>
-          <FormActions align="end">
-            <Button
-              type="submit"
-              loading={isSubmitting}
-              loadingLabel="Salvando cadastro"
-            >
-              Salvar
-            </Button>
-          </FormActions>
-        </Form>
-      )}
-    </Formik>
-  );
-}
-```
-
-O `name` deve corresponder à chave em `initialValues`. Os erros integrados aparecem quando o campo está marcado como tocado (`touched`). Forneça `label`; o placeholder é um exemplo de preenchimento, não substitui o rótulo.
-
-FormGrid usa uma coluna em telas menores e aplica `columns` a partir do breakpoint `tablet` (1024 px). FormActions organiza as ações em coluna no mobile e em linha nas telas maiores.
-
-### Campo controlado sem contexto Formik
-
-```tsx
-import { useState } from "react";
-import { InputStandalone } from "@aspprev/versi-ds/forms";
-
-export function Busca() {
-  const [termo, setTermo] = useState("");
-  return (
-    <InputStandalone
-      name="busca"
-      label="Buscar por nome"
-      value={termo}
-      onChange={(event) => setTermo(event.target.value)}
-    />
-  );
-}
-```
-
-Input e InputStandalone oferecem máscaras como `cpf`, `cnpj`, `cep`, `phone`, `date` e `currency`. A máscara auxilia a digitação; a aplicação ainda deve validar e normalizar o valor exigido pela sua API. Use InputPhone para seleção internacional de país e DDI.
-
-## Diálogos controlados
-
-```tsx
-import { useState } from "react";
-import { Button } from "@aspprev/versi-ds/core";
-import { Modal } from "@aspprev/versi-ds/overlays";
-
-export function Detalhes() {
-  const [aberto, setAberto] = useState(false);
-  return (
-    <>
-      <Button type="button" onClick={() => setAberto(true)}>
-        Ver detalhes
-      </Button>
-      <Modal
-        isOpen={aberto}
-        onClose={() => setAberto(false)}
-        title="Detalhes do cadastro"
-        showIcon={false}
-      >
-        <p>Informações complementares do cadastro.</p>
-        <Button type="button" onClick={() => setAberto(false)}>
-          Fechar
-        </Button>
-      </Modal>
-    </>
-  );
-}
-```
-
-Mantenha o estado de abertura na aplicação e forneça um título significativo. ModalCard é uma superfície visual; use Modal quando precisar do comportamento de diálogo.
-
-## Servidor e navegador
-
-As entradas de componentes, inclusive `/core` e a raiz, declaram `"use client"`: agrupam componentes com hooks/contexto. Podem participar de SSR em aplicações React, mas não são entradas exclusivas de React Server Components. Funções dessas entradas devem ser chamadas no contexto cliente em aplicações RSC. `/countries` permanece sem diretiva cliente e pode ser usado no servidor. Callbacks e estado devem ser definidos em um componente cliente.
-
-## Temas, acessibilidade e fontes
-
-Os tokens canônicos ficam em `tokens/design-system.tokens.json`. Edite essa fonte e execute `npm run tokens:generate`; não edite os arquivos gerados manualmente.
-
-```html
-<html
-  data-color-scheme="dark"
-  data-ds-theme="verde3"
-  data-contrast="high"
-  data-contrast-theme="dark"
-  data-font-scale="large"
-  data-motion="reduce"
-></html>
-```
-
-| Atributo              | Valores                                                                                                       |
-| --------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `data-color-scheme`   | `light`, `dark`                                                                                               |
-| `data-ds-theme`       | `default`, `azul1`, `azul2`, `azul3`, `laranja1`, `laranja2`, `verde1`, `verde2`, `verde3`, `verde4`, `rosa1` |
-| `data-contrast`       | `normal`, `high`                                                                                              |
-| `data-contrast-theme` | `light`, `dark` (esquema do alto contraste)                                                                   |
-| `data-font-scale`     | `default`, `large`, `extra-large`                                                                             |
-| `data-motion`         | `full`, `reduce`                                                                                              |
-
-As preferências são controladas pelo consumidor, que também cuida da persistência e sincronização. As classes legadas das paletas continuam disponíveis. Tokens de cores usam triplets RGB para aceitar opacidade.
-
-O pacote não distribui nem baixa fontes. Configure `--font-nunito-sans` ou sobrescreva `--font-family-base`; sem Nunito Sans disponível, o navegador usa `sans-serif`. O Storybook carrega Nunito Sans pelo Google Fonts e precisa de rede para reproduzir essa tipografia nas referências visuais existentes. O consumidor pode hospedar a própria fonte; não há dependência de `next/font`.
-
-### Alterar o tema em execução
-
-No navegador, atualize os atributos do elemento raiz:
-
-```ts
-const root = document.documentElement;
-root.dataset.colorScheme = "dark";
-root.dataset.dsTheme = "azul1";
-root.dataset.contrast = "normal";
-root.dataset.contrastTheme = "dark";
-root.dataset.fontScale = "large";
-root.dataset.motion = "reduce";
-```
-
-Use o `html` para que diálogos e listas renderizados fora da árvore do componente recebam o mesmo tema. Aplique as preferências conhecidas antes da primeira pintura quando houver SSR. Para acompanhar o tema do sistema, a aplicação deve resolver a preferência para `light` ou `dark`.
+### Entrypoints
 
-AccessibilityPreferencesPanel recebe `preferences` e entrega mudanças parciais em `onPreferencesChange`. Mescle essas mudanças com o estado atual e sincronize os atributos CSS. O valor `fontScale="standard"` do painel corresponde a `data-font-scale="default"`; `highContrast` corresponde a normal/high e `reduceMotion` a full/reduce. O painel não persiste nem aplica automaticamente as preferências no documento.
+| Entry point | Conteúdo |
+| --- | --- |
+| `@aspprev/versi-ds` | API principal e componentes mais usados |
+| `/core` | componentes base, layout, status, tabela e hooks |
+| `/forms` | campos Formik e controlados, seleção e OTP |
+| `/documents` | documentos, upload, FileViewer e QRCode |
+| `/overlays` | modal, preferências e camadas interativas |
+| `/charts` | gráficos e seletores de período |
+| `/countries` | países, telefones e bandeiras |
+| `/styles.css` | estilos e tokens base |
+| `/themes.css` | presets de tema |
 
-### Usar tokens no CSS da aplicação
+Evite deep imports. Use somente os entrypoints públicos documentados no `package.json`.
 
-Prefira tokens semânticos, que expressam a função da cor, em vez de copiar valores de uma paleta:
-
-```css
-.resumo-cadastro {
-  color: rgb(var(--content-primary));
-  background-color: rgb(var(--surface-page));
-  border: 1px solid rgb(var(--border-default));
-  padding: var(--spacing-md);
-  border-radius: var(--border-radius-md);
-}
-
-.resumo-cadastro:focus-visible {
-  outline: 2px solid rgb(var(--focus-ring));
-  outline-offset: 2px;
-}
-```
+## Organização do Design System
 
-Tokens de cor contêm os canais RGB, sem `#` e sem a função `rgb()`; tokens de espaço e raio já incluem a unidade. Ao personalizar cores, confira também os modos escuro e de alto contraste. Evite tamanhos de fonte fixos que impeçam a escala tipográfica do DS.
+- **Components**: controles de ação, formulários, feedback, navegação, dados, documentos, overlays e layout.
+- **Foundations**: cores, tipografia, espaçamento e sombras derivados dos tokens.
+- **Themes**: esquema claro/escuro, contraste, escala tipográfica e presets de identidade.
+- **Hooks e utilitários**: breakpoints, acessibilidade, preferências e posicionamento.
+- **Countries e charts**: dados de países/bandeiras e integrações de gráficos.
 
-O CSS distribuído inclui as classes necessárias aos componentes, não todas as classes possíveis do Tailwind. Para layouts próprios, use seu CSS ou o build Tailwind da aplicação; o `tailwind.config.cjs` deste repositório não é um export público.
+Os tokens canônicos ficam em `tokens/design-system.tokens.json`. Arquivos CSS gerados não devem ser editados manualmente.
 
-### Configurar a família tipográfica
+## Storybook
 
-Depois de carregar a fonte escolhida, configure sua família no CSS global. Para uma alternativa sem download de fonte:
+Instale as dependências e inicie a documentação visual:
 
-```css
-:root {
-  --font-nunito-sans: system-ui;
-  --font-family-base: var(--font-nunito-sans), sans-serif;
-}
+```bash
+npm install
+npm run storybook
 ```
 
-Configure também `--font-nunito-sans` porque Typography usa essa variável. Trocar apenas a família do `body` não alcança todos os componentes.
-
-### Boas práticas de acessibilidade
-
-- Use títulos em ordem, rótulos de campos e texto que explique status e erros.
-- Mantenha foco visível e verifique Tab, Enter, Espaço e Escape nos controles interativos.
-- Teste claro, escuro e alto contraste, além de fonte ampliada e movimento reduzido.
-- Em ações com ícone sem texto, forneça um nome acessível, como `aria-label`.
-- Verifique o conteúdo da aplicação com leitor de tela; a composição e os textos também influenciam a acessibilidade.
-
-## Países e bandeiras locais
-
-A lista contém 250 países/territórios. `COUNTRY_OPTIONS` e `PHONE_COUNTRY_OPTIONS` são a mesma lista; `getCountryOptions()` retorna uma cópia editável. Os componentes usam a lista automaticamente quando `options`/`countries` são omitidos. Por isso, `/forms` e a raiz incluem os dados; `/core` não os exige.
+O servidor usa a porta `6006`. Para a configuração standalone:
 
-```tsx
-import { Formik } from "formik";
-import { SelectCountry, InputPhone } from "@aspprev/versi-ds/forms";
-
-<Formik
-  initialValues={{ pais: "Brasil", telefone: { ddi: 55, ddd: "", numero: "" } }}
-  onSubmit={() => {}}
->
-  <form>
-    <SelectCountry
-      name="pais"
-      label="País"
-      countryList={{ mode: "include", codes: ["BR", "PT", "US"] }}
-    />
-    <InputPhone
-      name="telefone"
-      label="Telefone"
-      countryList={{ mode: "exclude", codes: ["US"] }}
-    />
-  </form>
-</Formik>;
+```bash
+npm run storybook:standalone
 ```
 
-`countryList` aceita `all` (padrão), `include` ou `exclude`; `codes` usa ISO-2. Na lista padrão, o **valor do SelectCountry é o nome** (`Brasil`), e `cca2` contém `BR`. O payload telefônico é `{ ddi, ddd, numero }`; países com o mesmo DDI não podem ser distinguidos ao restaurar apenas esse payload. A escolha explícita preserva o ISO-2 enquanto o componente estiver montado.
-
-Os componentes usam SVGs locais por `cca2`, inclusive em opções customizadas: `/flags/br.svg`, por exemplo. Todos os arquivos são publicados em `dist/flags`; o consumidor precisa servi-los em `/flags` no mesmo domínio. Na raiz da aplicação consumidora:
-
-```bash
-node --input-type=module -e "import {cpSync} from 'node:fs'; import {fileURLToPath} from 'node:url'; cpSync(fileURLToPath(new URL('./flags/', import.meta.resolve('@aspprev/versi-ds/countries'))), 'public/flags', {recursive:true})"
+A árvore da documentação é organizada assim:
+
+```text
+Getting Started
+├── Introduction
+├── Installation
+├── Usage
+└── Contributing
+
+Foundations
+├── Overview
+├── Colors
+├── Typography
+├── Spacing
+└── Shadows
+
+Components
+├── Actions
+├── Forms
+├── Feedback
+├── Data Display
+├── Documents
+├── Navigation
+├── Overlay
+├── Layout
+└── Accessibility
+
+Patterns
+├── Forms
+└── Feedback
+
+Themes
+├── Overview
+├── Comparison
+└── ThemeLab
+
+Guidelines
+├── Accessibility
+└── Usage
 ```
 
-Em aplicações com subpath, configure uma rota estática para `/flags` na raiz do domínio. O campo legado `flags.png` contém metadados remotos; os componentes usam o SVG local e não requisitam esse PNG. `staticDirs` serve os SVGs no Storybook.
+A toolbar permite comparar esquema de cores, preset, contraste, escala de fonte e movimento reduzido. O addon de acessibilidade permanece disponível para inspeção manual e os testes automatizados usam Axe nos cenários visuais.
 
 ## Desenvolvimento e validação
 
 ```bash
-npm install
 npm run tokens:check
-npm run check:governance
 npm run typecheck
-npm run build
 npm test
-npm run check:size
+npm run build
 npm run build-storybook
-npx playwright install chromium
 npm run test:visual
 npm run check:package
-npm run test:package
-npm pack --dry-run
+npm run prepack
 ```
 
-`typecheck` inclui código, stories e configuração visual. `test:package` instala um tarball em diretório temporário fora do repositório, primeiro sem peers opcionais e depois com todos eles; verifica ESM, CSS, SSR e TypeScript strict/NodeNext. Requer acesso ao registro npm e limpa seu diretório temporário.
-
-Use `npm run storybook` (6006) ou `npm run storybook:standalone` (6007). Playwright inicia seu próprio servidor; `STORYBOOK_DS_PORT` altera a porta. As referências visuais existentes são Chromium/Windows, desktop e mobile. Revise diferenças antes de usar `npm run test:visual:update`. Axe e testes automatizados não substituem revisão manual com leitor de tela.
-
-No Storybook, abra o grupo `Design System` e escolha um componente. Use suas stories para comparar estados e variantes, e os controles para experimentar as propriedades disponíveis. A barra de ferramentas altera esquema de cores, paleta, contraste, escala da fonte e movimento. O `ThemeLab/Playground` reúne a exploração dos temas; o painel de acessibilidade ajuda na inspeção de cada cenário.
-
-`prepack` verifica tokens, governança, TypeScript, build, tamanho e conteúdo antes de empacotar. O tarball inclui somente `dist/`, `README.md` e o `package.json` obrigatório do npm. Stories, testes, documentação interna e ferramentas não são publicados. Sourcemaps em `dist` são intencionais para diagnóstico.
+O script `prepack` valida tokens, governança, segurança, TypeScript, build, tamanho e conteúdo do pacote. O projeto não possui um script `lint` separado.
 
-## Aplicação de exemplo
-
-O repositório inclui uma aplicação React/Vite em `examples/pilot`, com cadastro,
-validação de formulário, países/telefone, tabela, modal e controles de aparência.
-Ela instala o DS a partir do tarball e usa apenas os entrypoints públicos.
-
-Na raiz do repositório:
+Para testar o exemplo integrado:
 
 ```bash
 npm run pilot:prepare
-npm run pilot:dev
+npm run test:pilot
 ```
 
-Abra `http://127.0.0.1:4175`. Para compilar e testar o piloto em produção, execute
-`npm run test:pilot`. As instruções completas estão em `examples/pilot/README.md`.
-O exemplo não faz parte do pacote npm e seus dados ficam somente na memória da página.
+Antes de uma publicação, gere um tarball local com `npm pack` e valide sua instalação nos consumidores.
 
-## Problemas comuns
+## Temas
 
-| Sintoma                                                  | O que conferir                                                                                                    |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| Componentes sem estilo                                   | Importe styles.css uma vez na entrada da aplicação e verifique regras que o sobrescrevem.                         |
-| Uma classe Tailwind própria não funciona                 | O CSS do pacote inclui as classes dos componentes; compile as classes da sua aplicação ou use CSS próprio.        |
-| Erro ao resolver Formik, Headless UI ou outra integração | Instale os peers da camada importada. A entrada raiz precisa do conjunto completo.                                |
-| Erro de contexto Formik                                  | Envolva os controles integrados em Formik; para Input controlado, use InputStandalone.                            |
-| Bandeiras não aparecem                                   | Confirme que /flags/br.svg responde no domínio da aplicação e copie dist/flags para os arquivos públicos.         |
-| SelectCountry não mostra o valor inicial                 | Na lista padrão, use Brasil como valor; BR é o código de filtragem ISO-2.                                         |
-| Diálogo ou dropdown com tema diferente                   | Aplique os atributos de tema no html para alcançar também os elementos renderizados fora da árvore do componente. |
-| Fonte diferente do Storybook                             | Carregue a fonte desejada e configure --font-nunito-sans; a fonte não acompanha o pacote.                         |
-| Erro de hooks em aplicação RSC                           | Defina estado e callbacks em um componente cliente; consulte a seção sobre servidor e navegador.                  |
+As preferências são controladas pelo consumidor no elemento `html`:
 
-## Documentação do repositório
+```ts
+const root = document.documentElement;
+root.dataset.colorScheme = "dark";
+root.dataset.dsTheme = "azul1";
+root.dataset.contrast = "high";
+root.dataset.fontScale = "large";
+root.dataset.motion = "reduce";
+```
 
-Para aprofundar o uso e a manutenção, consulte os arquivos abaixo no checkout do projeto. Eles não acompanham o tarball npm.
+Os valores válidos estão documentados em **Themes/Overview** no Storybook. Prefira tokens semânticos, como `--surface-page`, `--content-primary`, `--border-default` e `--focus-ring`, em vez de copiar valores de uma paleta.
 
-| Arquivo                           | Conteúdo                                                |
-| --------------------------------- | ------------------------------------------------------- |
-| docs/API-PUBLICA-CONTROLES.md     | Contratos dos controles, estado, teclado e dependências |
-| docs/COMPONENTES-CLIENT-SERVER.md | Fronteiras cliente e servidor                           |
-| docs/THEMELAB-E-GLOBALS-CSS.md    | Temas e personalização do CSS                           |
-| tokens/README.md                  | Fonte e geração dos tokens                              |
-| docs/GOVERNANCA-DESIGN-SYSTEM.md  | Contribuição, versionamento e publicação                |
-| docs/EVOLUCAO-DESIGN-SYSTEM.md    | Histórico de mudanças e validações                      |
+## Contribuição
 
-O contexto específico do portal, o plano de migração e as pendências dessa transição ficam exclusivamente em `MIGRACAO-DO-PORTAL.md`.
-# versi-design-system
+Ao criar ou alterar um componente:
 
+1. reutilize tokens e componentes existentes;
+2. mantenha a API tipada e compatível com React;
+3. garanta foco visível, teclado, nomes acessíveis, erros e estados de carregamento;
+4. crie ou atualize stories com estados relevantes;
+5. adicione testes unitários, de interação e de acessibilidade quando aplicável;
+6. execute `npm run prepack` antes de gerar o pacote.
 
+Detalhes de contratos, governança e segurança ficam na pasta `docs/`. A documentação de uso visual deve permanecer principalmente no Storybook.

package/dist/charts.js

@@ -12,7 +12,7 @@ import {
   normalizeTimeSeriesTooltipColor,
   resolveInteractiveDonutColors,
   resolveRelativeDonutSelection
-} from "./chunk-6MXHE5MD.js";
+} from "./chunk-V66QL3TD.js";
 import "./chunk-2NMEKWO5.js";
 export {
   InteractiveDonutChart,

package/dist/{chunk-OWXG2A4N.js → chunk-ATWH3MA6.js}

@@ -74,4 +74,4 @@ function DocumentItem(_a) {
 export {
   DocumentItem
 };
-//# sourceMappingURL=chunk-OWXG2A4N.js.map
+//# sourceMappingURL=chunk-ATWH3MA6.js.map

package/dist/chunk-ATWH3MA6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/document-item/DocumentItem.tsx"],"sourcesContent":["import classNames from \"classnames\";\nimport type { HTMLAttributes, ReactNode } from \"react\";\n\nexport interface DocumentItemDetail {\n  label: ReactNode;\n  value: ReactNode;\n}\n\nexport interface DocumentItemProps\n  extends Omit<HTMLAttributes<HTMLDivElement>, \"title\"> {\n  title: ReactNode;\n  label?: ReactNode;\n  description?: ReactNode;\n  details?: DocumentItemDetail[];\n  status?: ReactNode;\n  actions?: ReactNode;\n  illustration?: ReactNode;\n  variant?: \"plain\" | \"subtle\";\n  titleClassName?: string;\n}\n\nexport function DocumentItem({\n  title,\n  label,\n  description,\n  details = [],\n  status,\n  actions,\n  illustration,\n  variant = \"plain\",\n  titleClassName,\n  className,\n  ...rest\n}: DocumentItemProps) {\n  return (\n    <div\n      className={classNames(\n        \"flex min-w-0 flex-col gap-4 rounded-md tablet:flex-row tablet:items-center tablet:justify-between\",\n        variant === \"subtle\" && \"bg-surface-subtle p-4 tablet:p-5\",\n        className,\n      )}\n      {...rest}\n    >\n      <div className=\"min-w-0 flex-1 space-y-3\">\n        <div className=\"min-w-0\">\n          {label && (\n            <p className=\"text-sm text-content-secondary\">{label}</p>\n          )}\n          <p\n            className={classNames(\n              \"break-words text-content-primary\",\n              titleClassName,\n            )}\n          >\n            {title}\n          </p>\n          {description && (\n            <div className=\"mt-1 break-words text-sm text-content-secondary\">\n              {description}\n            </div>\n          )}\n        </div>\n\n        {(details.length > 0 || status) && (\n          <div className=\"flex flex-wrap items-start gap-x-8 gap-y-3\">\n            {details.map((detail, index) => (\n              <div key={index} className=\"min-w-0\">\n                <p className=\"text-sm text-content-secondary\">{detail.label}</p>\n                <div className=\"break-words font-semibold text-content-primary\">\n                  {detail.value}\n                </div>\n              </div>\n            ))}\n            {status && <div className=\"min-w-0\">{status}</div>}\n          </div>\n        )}\n      </div>\n\n      {illustration && (\n        <div className=\"hidden shrink-0 desktop:block\" aria-hidden=\"true\">\n          {illustration}\n        </div>\n      )}\n\n      {actions && (\n        <div className=\"flex w-full shrink-0 flex-col gap-2 tablet:w-auto tablet:flex-row tablet:flex-wrap tablet:justify-end\">\n          {actions}\n        </div>\n      )}\n    </div>\n  );\n}\n"],"mappings":";;;;;;;AAAA,OAAO,gBAAgB;AA4Cf,SAEI,KAFJ;AAvBD,SAAS,aAAa,IAYP;AAZO,eAC3B;AAAA;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU,CAAC;AAAA,IACX;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU;AAAA,IACV;AAAA,IACA;AAAA,EA/BF,IAqB6B,IAWxB,iBAXwB,IAWxB;AAAA,IAVH;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA;AAGA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA,YAAY,YAAY;AAAA,QACxB;AAAA,MACF;AAAA,OACI,OANL;AAAA,MAQC;AAAA,6BAAC,SAAI,WAAU,4BACb;AAAA,+BAAC,SAAI,WAAU,WACZ;AAAA,qBACC,oBAAC,OAAE,WAAU,kCAAkC,iBAAM;AAAA,YAEvD;AAAA,cAAC;AAAA;AAAA,gBACC,WAAW;AAAA,kBACT;AAAA,kBACA;AAAA,gBACF;AAAA,gBAEC;AAAA;AAAA,YACH;AAAA,YACC,eACC,oBAAC,SAAI,WAAU,mDACZ,uBACH;AAAA,aAEJ;AAAA,WAEE,QAAQ,SAAS,KAAK,WACtB,qBAAC,SAAI,WAAU,8CACZ;AAAA,oBAAQ,IAAI,CAAC,QAAQ,UACpB,qBAAC,SAAgB,WAAU,WACzB;AAAA,kCAAC,OAAE,WAAU,kCAAkC,iBAAO,OAAM;AAAA,cAC5D,oBAAC,SAAI,WAAU,kDACZ,iBAAO,OACV;AAAA,iBAJQ,KAKV,CACD;AAAA,YACA,UAAU,oBAAC,SAAI,WAAU,WAAW,kBAAO;AAAA,aAC9C;AAAA,WAEJ;AAAA,QAEC,gBACC,oBAAC,SAAI,WAAU,iCAAgC,eAAY,QACxD,wBACH;AAAA,QAGD,WACC,oBAAC,SAAI,WAAU,yGACZ,mBACH;AAAA;AAAA;AAAA,EAEJ;AAEJ;","names":[]}

package/dist/{chunk-CWIPMGCA.js → chunk-ET2BGHTO.js}

@@ -306,9 +306,10 @@ var Tooltip = ({
 var Tooltip_default = Tooltip;
 
 export {
+  breakpoints,
   useBreakpoint,
   mergeAriaDescribedBy,
   getFloatingLayerClass,
   Tooltip_default
 };
-//# sourceMappingURL=chunk-CWIPMGCA.js.map
+//# sourceMappingURL=chunk-ET2BGHTO.js.map