# My Card · Design System 1.0

Biblioteca digital baseada no **Brand Guidelines 2.0** da My Card. Abra `index.html` diretamente no navegador. Tudo funciona offline; nenhum build, servidor ou conta é necessário para consultar a biblioteca.

## O que foi entregue

- Fundamentos: logos, oito cores institucionais, Barlow Condensed Black e Inter, iconografia e padrões aprovados.
- Regras digitais: escala de 4 px, raios, elevação, grid, movimento, temas e papéis semânticos de cor.
- Componentes: botões e seus estados, campos, select, checkbox, switch, alertas, badges, filtros, tabs, paginação, card, skeleton, estado vazio, toast e diálogos.
- Exemplos locais: coleção, favoritos, lista de desejos, validação e recuperação de erro.
- 104 tokens em JSON com tipos e aliases; CSS gerado; 24 ícones em 16 e 24 px; fontes e licenças locais.
- Busca por seção/componente com `⌘K` ou `Ctrl+K`, cópia de HEX/SVG/tokens e downloads.

## Status e origem

| Parte | Origem / status |
| --- | --- |
| Logo, oito cores, famílias tipográficas, seis ícones Traço Elétrico e 18 Lucide | Aprovados no Brand Guidelines 2.0 |
| Hora da troca v2, Órbita Base v5, Órbita Aberta v5 e Pikachu | Ativos aprovados, copiados sem alteração de bytes |
| Escalas de interface, componentes, nomes de tokens, estados e temas | Propostas de aplicação digital nesta versão 1.0 |
| Verde de sucesso, vermelho de erro, tons de interação e neutros adicionais | Extensões funcionais de UI; não ampliam a paleta institucional |

O documento mais específico e atual é `../brand-guidelines/README.md`, que identifica a edição 2.0. A referência antiga à edição 1.1 no README geral da identidade não rege esta entrega. O guia original e seus ativos não foram modificados.

Fontes consultadas: `../brand-guidelines/consulta-tecnica.html`, `consulta-dados.json`, `assets/sistema/icones/manifesto.json`, páginas visuais do guia e fontes/créditos dos ativos. A integridade das cópias está em `assets/manifest.json`.

## Usar os componentes

Copie `tokens.css`, `system.css` e `assets/` preservando os caminhos relativos:

```html
<link rel="stylesheet" href="tokens.css">
<link rel="stylesheet" href="system.css">

<button class="mc-button" type="button">Adicionar à coleção</button>
<button class="mc-button mc-button--secondary" type="button">Explorar cartas</button>
<button class="mc-button mc-button--outline" type="button">Filtrar</button>
```

As classes são prefixadas com `mc-`. `system.css` contém a aparência dos componentes, não o JavaScript do seu produto. `docs.css` e `app.js` pertencem ao catálogo e não são necessários para utilizar os estilos em outra aplicação. Os exemplos precisam de lógica própria ao integrar com dados reais.

Defina o tema na raiz; o modo claro é o padrão:

```html
<html lang="pt-BR" data-theme="dark">
```

Use os papéis semânticos nos componentes, em vez de fixar primitivos:

```css
.meu-painel {
  color: var(--mc-color-text-default);
  background: var(--mc-color-surface-raised);
  padding: var(--mc-space-24);
  border: 1px solid var(--mc-color-border-subtle);
  border-radius: var(--mc-radius-large);
}
```

Tokens de breakpoint documentam as medidas; variáveis CSS não funcionam diretamente em media queries. Use `600px`, `900px` e `1200px` nas regras responsivas da aplicação. A documentação usa uma coluna no celular, duas em blocos de tablet e grade de seis colunas no desktop. A organização do catálogo pode usar subdivisões específicas.

## Tipografia

Barlow Condensed Black 900 em chamadas curtas. Inter 400, 600 e 700 nos textos. Os arquivos locais são carregados por `@font-face` em `system.css`; Inter usa sua fonte variável oficial.

| Token | Fonte / peso | Tamanho / entrelinha |
| --- | --- | --- |
| `type-display` | Barlow Condensed 900 | 72 / 72 px; celular 40 / 40 |
| `type-heading-1` | Barlow Condensed 900 | 56 / 56 px; celular 40 / 40 |
| `type-heading-2` | Barlow Condensed 900 | 40 / 40 px |
| `type-heading-3` | Inter 600 | 28 / 36 px |
| `type-support` | Inter 600 | 20 / 26 px |
| `type-body` | Inter 400 | 16 / 24 px |
| `type-label` | Inter 600 | 14 / 20 px |
| `type-caption` | Inter 400 | 13 / 20 px |

Legendas não devem carregar a única versão de um dado essencial. Use `font-variant-numeric: tabular-nums` em preços e tabelas. A redução de certos títulos na documentação organiza a navegação; a escala de produto é a tabela acima.

## Ícones

Os 24 SVGs aprovados estão em `assets/icons/svg/16/` e `24/`. Use o desenho óptico correspondente ao tamanho. Em 32 e 48 px, parta da versão 24. Para herdar a cor, insira o SVG inline; `img` não herda `currentColor`.

```html
<button class="mc-button" type="button" aria-label="Adicionar carta">
  <!-- Cole aqui o SVG aprovado, com aria-hidden="true" no svg. -->
</button>
```

Não use o ícone isolado para transmitir o único significado de uma ação. Em botões só com ícone, forneça `aria-label`. A documentação monta os SVGs inline a partir de `icons-data.js`; isso é uma conveniência local, não um requisito de integração.

## Estados e comportamento

| Componente | Estados / comportamento |
| --- | --- |
| Botão | Padrão, hover, pressionado, foco, desabilitado, carregando; principal, secundário, contorno, texto e destrutivo |
| Campo | Padrão, preenchido, foco, inválido e desabilitado; label associado e ajuda via `aria-describedby` |
| Toast | `role="status"`, anúncio educado; feedback transitório sem retirar foco |
| Alertas | Cor + mensagem + ícone. Em atualizações use `status`; reserve `alert` para erros urgentes |
| Tabs | Setas esquerda/direita, Home e End; `aria-selected`, `aria-controls` e tabulação do painel ativo |
| Filtros | `aria-pressed` acompanha a seleção |
| Diálogo | Elemento nativo `dialog`, foco contido pelo navegador, Escape fecha e devolve foco ao acionador |
| Navegação móvel | Abre como diálogo, contém foco e fecha por botão, fundo ou Escape |
| Coleção | Card, vazio, carregamento, erro e recuperação demonstrados |

Esta referência mantém favoritos e coleções somente na memória da página. Recarregar reinicia os exemplos. O tema pode ser lembrado em `localStorage`; se o navegador bloquear o armazenamento, a biblioteca continua funcionando.

## Acessibilidade

O projeto adota controles de **44 × 44 px** ou maiores. WCAG 2.2 AA define um mínimo de 24 × 24 com exceções; os 44 px são a decisão do sistema. Textos correntes precisam de 4,5:1; textos grandes e limites visuais essenciais de controles, 3:1. O catálogo calcula as razões dos pares de marca com luminância sRGB.

Referências verificadas em 20/10/2026: [contraste de texto](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [contraste não textual](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) e [tamanho dos alvos](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html). Critérios de construção e verificações automatizadas não equivalem a uma declaração de conformidade integral; avalie cada produto com seu conteúdo, fluxos, tecnologias assistivas e dados reais.

## Créditos e uso das imagens

Logos, padrões e família Traço Elétrico vêm do acervo aprovado da My Card. Os créditos de personagens e imagens de cartas seguem os registros do guia e estão em `assets/source-credits.json`. Personagens e cartas Pokémon pertencem aos respectivos titulares; sua inclusão reproduz o repertório já selecionado no guia, sem criar novas permissões de uso.

Pikachu 025/165, Scarlet & Violet 151 em inglês, é uma referência de catálogo. Não representa oferta, estoque ou estado de uma unidade. Para ofertas reais, mostre a unidade e informe fotos, estado, marcas, edição, número, idioma, preço, disponibilidade e condições.

Licenças: `assets/fonts/Inter-OFL.txt`, `assets/fonts/BarlowCondensed-OFL.txt` e `assets/icons/LICENSE-LUCIDE.txt`. Preserve-as ao distribuir os respectivos ativos.

## Manter e reproduzir

1. Edite `tokens/tokens.json` para alterar valores e aliases; cores seguem a estrutura sRGB com componentes de 0 a 1. Edite `tokens/themes.json` para as sobrescritas escuras.
2. Execute `python3 scripts/build.py` a partir desta pasta. O script gera CSS e dados do catálogo e sincroniza as cópias dos ativos aprovados. O guia original deve existir no diretório vizinho. A biblioteca pronta não depende dele.
3. Edite `system.css` para componentes e `docs.css`/`index.html`/`app.js` para a documentação.
4. Execute `node scripts/verify.cjs`. Requer Playwright e Chrome; aceite `MY_CARD_CHROME` para o executável e `NODE_PATH` para resolver pacotes. O teste cobre arquivos, responsividade, tokens, integridade e interações reais.
5. Execute `python3 scripts/package.py` para atualizar `my-card-design-system.zip`. O ZIP contém a pasta pronta e não inclui o próprio ZIP.

`verificacao.json` registra a última conferência. `previas/` contém imagens reais do navegador. A biblioteca estática abre pelo arquivo; para servir via HTTP, use `python3 -m http.server 8765` nesta pasta e acesse `http://localhost:8765`.

Alterações institucionais devem ser incorporadas primeiro ao brand guideline. Mudanças em padrões digitais podem evoluir no design system, com nova versão e registro do que mudou.