Skip to content

docs(agents): invariantes do sistema de aparência #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johnlaff merged 1 commit into from
Jul 24, 2026
Merged

docs(agents): invariantes do sistema de aparência #70

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ Observações:
- Providers client-side ficam em `src/components/providers.tsx`.
- Fluxo offline fica em `src/lib/offline-queue.ts` e sincroniza via `POST /api/sync`.
- Fila offline deve ser ordenada cronologicamente antes do flush.
- Preferências de aparência persistem SEMPRE via `enqueueAppearancePatch` (`src/lib/settings-sync.ts` — fila serial com merge, debounce e retry offline; a hidratação remota respeita pendência local). Nunca chame `persistAppearanceSettings` direto de componente: PATCHes concorrentes chegam fora de ordem e o last-write-wins do servidor grava valor obsoleto.
- Assets PWA como `/_next/*`, `/icons/*`, `/manifest.json` e `/sw.js` não devem ser bloqueados por auth.

## Datas e Timezone
Expand Down Expand Up @@ -129,6 +130,9 @@ Regras duras:
- Emerald para clock-in, Rose para clock-out e Amber para warning são cores semânticas e não devem mudar com accent.
- Para superfícies neutras que não devem herdar accent, prefira tokens neutros como `--secondary` e `--card` conforme o contexto.
- Evite usar `--muted`, `--input` ou `--accent` para controles que precisam permanecer neutros sob custom accent.
- No accent personalizado, os tokens suaves (`--accent`/`--muted`/foregrounds) derivam do hex em OKLCH direto no CSS (relative color, bloco `[data-accent="custom"]` de `globals.css`); o JS decide apenas contraste de foreground/borda (provider + script anti-flash do layout, com paridade travada por teste). Não reintroduza derivação de superfície em JS/sRGB: limiar de luminância em sRGB falha para cores claras saturadas (amarelo/ciano viram superfície quase pura).
- As fórmulas de cor de `globals.css` têm prova WCAG espelhada em teste que também lê a folha e trava drift (`custom-accent-tokens.test.ts`, `background-tint.test.ts`): quem muda a fórmula atualiza a prova no mesmo commit.
- O reveal de tema é híbrido por necessidade: clip-path estático de raio 0 no CSS (o pseudo-elemento nasce recortado — sem flash no gap até o `ready` no mobile) + WAAPI criado em `transition.ready` (anima com snapshots prontos — sem truncamento durante a captura). Não mover a animação para keyframes CSS nem agendar WAAPI sem o clip estático.
- Ao modificar UI, mantenha consistência com o design system documentado em `docs/` e com `CONTEXT.md`.

## Bibliotecas e UI
Expand Down
Loading