---
name: ui-nova-tema-tokens
description: Aplicar tema (light/dark/system) e design tokens --v-* da ui-nova (vueui-nova-kit). Use ao estilizar qualquer coisa num projeto com ui-nova, criar CSS/SCSS, ajustar cores, espaçamentos, raios, sombras ou tipografia, implementar dark mode, ou ao revisar código que usa hex/rgb/px literais.
---

# Tema e tokens da ui-nova

> `references/tokens.md` é **gerado** de `src/tokens/_tokens.scss` por
> `scripts/gen-skill-refs.mjs`.

## Regras

1. **Nunca** use hex/rgb/hsl literal nem px "mágico". Use tokens `--v-*` (ou `color-mix()` sobre eles).
2. Prefira **tokens semânticos** (`--v-color-bg`, `--v-color-surface`, `--v-color-text`,
   `--v-color-text-muted`, `--v-color-border`, `--v-color-{success|info|warning|error}-{soft|base|strong|contrast}`…).
   Eles invertem certo no dark. Escalas cruas (`--v-color-primary-600`) só quando não houver semântico.
3. Texto sobre fundo tintado (chips, badges, `primary-50`) usa `--v-color-primary-text`, nunca
   `--v-color-primary`.
4. Espaço, raio e sombra vêm das escalas (`--v-space-*`, `--v-radius-*`, …). Não invente valores
   intermediários.
5. Movimento: respeite `prefers-reduced-motion` com `useReducedMotion()` ou os tokens de motion.

## Ativar tema

```html
<html data-theme="system">  <!-- light | dark | system -->
<section class="v-theme-dark">…</section>  <!-- só uma subárvore -->
```

```ts
import { useTheme } from 'vueui-nova-kit'
const { theme, resolvedTheme, setTheme, toggleTheme } = useTheme({ default: 'system' })
```

`useTheme` persiste em `localStorage` (`storageKey: 'v-theme'`; `false` desliga).

## Customizar marca

Sobrescreva variáveis num escopo, sem editar a lib:

```css
:root { --v-color-primary-500: oklch(62% 0.19 255); }
.v-theme-dark { --v-color-primary-500: oklch(72% 0.16 255); }
```

## Em surfaces A2UI

A v1.0 do A2UI **não** tem tema na mensagem: a surface herda o tema do host. O renderer ui-nova
apenas monta dentro do escopo de tema da página. Payloads A2UI nunca carregam cor; as props de cor
são enum de tom (`tone`, `variant`, `intent`).

## Arquivos

- `references/tokens.md`: **gerado**. Lista de tokens por grupo (semânticos, escalas, motion,
  tipografia).
