Usage Monitor Design

---
name: usage-monitor-design
description: Apply the Usage Monitor design system (tokens, primitive contracts, precedence over the prototype, UI kit) when drawing, changing, or auditing any visible surface — Compose screens, dialogs, tray, PDF report — or building a visual prototype for this project.
---

# Usage Monitor — design system

A fonte de verdade visual deste repositório é [`docs/design-system/`](../../../docs/design-system/).
Ela é normativa: divergência entre o Compose e o design system é defeito do Compose. A tabela
completa de precedência está em [CLAUDE.md](../../../CLAUDE.md), seção *Sistema visual → Design
system — precedência*.

## Antes de desenhar qualquer coisa

1. Ler [`docs/design-system/readme.md`](../../../docs/design-system/readme.md) inteiro. Ele carrega
   os fundamentos de conteúdo (voz, casing, "todo estado carrega uma palavra", "controle
   desabilitado sempre diz por quê") e as fundações visuais.
2. Ler os tokens em [`docs/design-system/tokens/`](../../../docs/design-system/tokens/). Eles já têm
   equivalente exato em Kotlin — `AppSpacing`, `AppShapes`, `AppElevation`, `AppMotion`,
   `AppThemePreset.OBSIDIANA_DARK`/`PORCELANA_LIGHT` e `AppAccents` em
   `src/commonMain/kotlin/com/usagemonitor/presentation/ui/theme/`. **Não introduza um valor novo:**
   se falta um degrau, a decisão vai para o design system antes de ir para o código.
3. Ler o contrato da primitiva que você vai usar em
   [`docs/design-system/components/`](../../../docs/design-system/components/). Cada `*.prompt.md`
   diz o que a primitiva resolve e o que é proibido dentro dela.
4. Abrir o mockup da tela no protótipo aprovado,
   [`docs/planos/prototipo-visual-opencode.html`](../../../docs/planos/prototipo-visual-opencode.html),
   e o kit correspondente em
   [`docs/design-system/ui_kits/desktop-app/`](../../../docs/design-system/ui_kits/desktop-app/).

## Regras que não se negociam

- **Nenhuma tela reimplementa uma primitiva.** Antes de escrever `Surface`, `Card`,
  `Modifier.border`, `.background` com cor de superfície ou `RoundedCornerShape`, procure em
  `presentation/ui/components/AppStructure.kt`, `AppControls.kt`, `AppStates.kt` e nos vizinhos
  `AppTabs.kt`, `AppSettingsNav.kt`, `AppSurfaceDepth.kt`, `AppChips.kt`, `AppMenu.kt` e
  `AppTooltip.kt`.
- **Primitiva construída e não adotada não conserta nada.** O commit que cria e o que consome são o
  mesmo.
- **Cor de acento vem de `AppAccents.current` e `AppTone`**, nunca de `darkAppAccents` /
  `lightAppAccents` diretamente — `val` de topo de arquivo não lê o tema em vigor.
- **Cor nunca informa sozinha.** Todo estado carrega ponto **e** palavra (`AppStatusIndicator`).
- **Nenhuma animação infinita.** Ela trava o `waitForIdle` dos testes de componente. Carregamento é
  esqueleto estático, sem shimmer e sem spinner.
- **Sem emoji.** Os ícones são marcas Unicode em IBM Plex Mono, e a lista está no `readme.md`.
- Escala tipográfica fechada em 10/12/14/16/20/28; raio com teto de 10dp; elevação 8 só para janela,
  diálogo, menu e overlay.

## Ao terminar

Registrar a mudança **no mesmo commit**, nos dois documentos: a seção da tela no protótipo e, quando
a tela tem kit, o `.jsx` em `ui_kits/desktop-app/`. Primitiva nova ou contrato alterado vira
`components/<grupo>/<Nome>.prompt.md` mais a entrada no índice do `readme.md`.

Verificar com `gradlew.bat desktopTest --tests "com.usagemonitor.ui.*"` e, para comparação visual,
`gradlew.bat generateScreenshots`.

## Para mocks e protótipos descartáveis

Copie `docs/design-system/styles.css`, `tokens/` e `assets/` para junto do HTML e monte a página com
as primitivas de `components/`. `_ds_local.js` monta os componentes sem o bundle compilado.