# Oficio&Circular — Handoff a Claude Code

> **Producto:** Oficio&Circular (oficioycircular.cl)
> **Empresa:** NormaViva SpA
> **Sub-producto:** ImpuestoFácil (facil.normaviva.cl)
> **Versión del DS:** 2.1 (P1 completo)
> **Stack sugerido:** Next.js 15 (App Router) · React 19 · TypeScript · CSS modules o Tailwind v4 con `@theme` apuntando a `tokens.css`

---

## 1. Estructura de archivos

```
design-system/
├── tokens/tokens.css          ← fuente única de verdad (388 líneas, WCAG AA)
├── icons/icons.svg            ← sprite con 10 símbolos editoriales
├── components/
│   ├── Header.html            ← 3 variantes (pública, logged, mobile)
│   └── Footer.html            ← responsive con métricas
├── layouts/
│   ├── Editorial.html         ← shell para home pública + Chat IA
│   └── Biblioteca.html        ← shell con sidebar para listados densos
├── screens/
│   ├── Home.html              ← P1.2 · 3 tabs SPA (fallos/chat/normativa)
│   ├── Chat.html              ← P1.1 · 5 estados de conversación
│   ├── FallosTTA.html         ← P1.3 · listado denso 7 col + filtros
│   ├── DetalleFallo.html      ← P1.4 · vista lectura editorial
│   ├── Pricing.html           ← P1.5 · 3 tiers + Early Access
│   ├── ImpuestoFacil.html     ← P1.6 · entrada minimal mobile-first
│   └── Componentes.html       ← P1.7 · 17 patrones atómicos
└── HANDOFF.md                 ← este archivo
```

## 2. Identidad

- **Marca:** Oficio&Circular (mark "O&C" sans, separator "&" en `--navy-500`).
- **Tipografía:** Inter Tight (sans), Source Serif 4 (titulares editoriales), JetBrains Mono (números, RIT, kickers, badges).
- **Voz:** chilena formal sin voseo, profesional sin solemnidad, directa.
- **Slogan:** "Investigación tributaria · Chile".

## 3. Tokens críticos (`tokens.css`)

| Token | Uso |
|---|---|
| `--navy-950 / 900 / 800` | Fondos oscuros, CTAs primarios, headers de hero |
| `--navy-700` | Color de enlaces (`--link`) — AA 9.4:1 |
| `--paper` | Fondo principal (`#fbfaf7` warm) |
| `--ink-900` | Body text · `--ink-950` headings |
| `--ink-500` | Mínimo aceptable para texto secundario (4.7:1) |
| `--accent` | **Solo** para tag de Circular y sello editorial — NUNCA decorativo |
| `--verde-700 / rojo-700 / ambar-700 / gris-700` | Chips de resultado: acoge / rechaza / parcial / **indeterminado** |

> Regla absoluta de color: el dorado (`--accent`) solo aparece en `tag--circular`. Header, footer, hero, kickers, CTAs y banners usan navy. **Nunca** combines navy + dorado en un mismo elemento.

## 4. Datos reales del corpus (no inventar)

| Recurso | Conteo |
|---|---:|
| Fallos TTA (1ª instancia) | 11.193 |
| Oficios SII | 4.861 |
| Resoluciones SII | 1.688 |
| Circulares SII | 190 |
| Leyes tributarias | 72 |

Estos números aparecen en hero de Home, footer global y sidebar de Biblioteca. Mantén sincronía vía variable de entorno o constante única (`@/config/corpus.ts`).

## 5. Componentes a extraer (orden sugerido)

**Tier 1 (P0):**
1. `<Button>` — primary / secondary / ghost · sm
2. `<Tag>` — fallo / oficio / circular / ley / pro
3. `<ChipResult>` — acoge / rechaza / parcial / indeterminado
4. `<Header>` — navega 3 tabs SPA + ⌘K + login
5. `<Footer>` — métricas + newsletter mensual + disclaimer NormaViva
6. `<TableGrid>` — `<table>` semántico con `display: contents` para `<tr>`

**Tier 2 (P1):**
7. `<SearchBar>` con `data-search-target="active-panel"` para el ⌘K
8. `<FilterChips>` (chips removibles + count)
9. `<PullQuote>` — copiable
10. `<SourceCard>` — mini card de cita
11. `<Considerando>` — bloque de fallo
12. `<TierCard>` — tarjeta de pricing (con variante `--popular`)
13. `<Banner>` — info / warn / err / ok
14. `<Skeleton>` — loader genérico
15. `<EmptyState>`
16. `<CommandPalette>` (⌘K)
17. `<Tooltip>`, `<Dropdown>`, `<Tabs>`, `<Pagination>`, `<Dialog>`, `<Toggle>`

## 6. Reglas de layout

- **Container max:** 1180–1320 px. Padding lateral 32 px desktop, 16 px mobile.
- **Editorial layout** (Home, Chat, marketing): hero oscuro + body warm paper. Tipografía serif para titulares, sans para UI.
- **Biblioteca layout** (Fallos, Oficios, Resoluciones, Circulares, Leyes): sidebar de 240 px + main. Drawer en mobile (`<900px`).
- **Tablas densas:** `grid-template-columns` por tabla específica; `<thead>`, `<tbody>`, `<tr>` con `display: contents` para que el grid se aplique a los `<th>`/`<td>` directamente sin perder semántica.

## 7. Accesibilidad (no negociable)

- Todos los pares de color cumplen **WCAG AA** (auditados en P0.html).
- `--ink-500` es el **mínimo absoluto** para texto · nunca usar `--ink-400` para texto, solo deshabilitado.
- Foco visible: ring de 3 px con `color-mix(in srgb, var(--navy-700) 15%, transparent)`.
- Hit targets: ≥ 36 px en desktop, ≥ 44 px en mobile.
- Cada `<button>` y `<a>` con texto descriptivo o `aria-label`.

## 8. Decisiones técnicas (confirmadas con producto)

1. **3 tabs SPA en `/`** — `?tab=fallos|chat|normativa`, deeplink, scroll preservado.
2. **⌘K global** — busca dentro del panel activo vía `data-search-target="active-panel"`.
3. **Banner ImpuestoFácil** — *no* sticky en header. Aparece solo como card en Home tras "Esta semana".
4. **Plan en avatar dropdown** — no en header chrome.
5. **Tablas semánticas** — `<table role="table">` + `display: grid` + `display: contents`.
6. **Trial 10 días** — sin tarjeta. Botón "Empezar 10 días gratis".
7. **Kickers simples** — sin `::before` decorativo. Solo `padding-left + border-left`.
8. **Newsletter mensual** — frecuencia explícita en footer.
9. **Drawers en mobile** — para sidebars y filtros densos.
10. **Copy chileno formal** — sin voseo, sin "vos", sin emojis. Acepta "tú" en ImpuestoFácil (público amplio) y "ustedes" en pricing.

## 9. ImpuestoFácil tiene su propio look

Sub-producto en `facil.normaviva.cl` con:
- Header propio con mark `If` + "por NormaViva".
- Tipografía igual (Inter Tight + Source Serif 4) pero radios más generosos (12–14 px vs 6–8 px).
- Disclaimer explícito siempre visible.
- Output con fuentes oficiales numeradas (1, 2, 3) enlazando al SII directamente.
- CTA al final hacia Oficio&Circular para profesionales.

## 10. Checklist antes de mergear a producción

- [ ] `tokens.css` en `app/globals.css` o como `@theme` en Tailwind v4
- [ ] Sprite SVG inlined en `<body>` o servido como sprite externo con `<use href="/icons.svg#balanza" />`
- [ ] Logo PNG provisto por usuario reemplaza wordmark sans actual (header 36–40 px, footer claro)
- [ ] Lighthouse ≥ 95 en Performance, ≥ 100 en Accessibility (decirme si no llega)
- [ ] Verificación de chips de resultado: 4 estados, no 3
- [ ] Métricas reales (11.193 / 4.861 / 1.688 / 190 / 72) en una sola constante
- [ ] Atribución legal "NormaViva SpA" en footer + términos + privacidad

## 11. Preguntas para Claude Code antes de implementar

1. ¿Tailwind v4 con `@theme` o CSS modules con `tokens.css` importado en `globals.css`? (recomiendo Tailwind por velocidad de iteración)
2. ¿Cómo manejas el corpus de fallos en dev? (sugerencia: API mock con `/api/fallos` y MSW para tests)
3. ¿Server Components para listados (Fallos, Oficios) y Client Components solo para Chat IA + ⌘K?
4. ¿Auth con Clerk, Supabase Auth o NextAuth? (Empresa requiere SSO SAML/OIDC en P2)
5. ¿Stripe Tax o Khipu para facturación electrónica chilena? (NormaViva es SpA chilena, factura 33)
6. ¿Cómo cacheas el feed semanal de "Esta semana"? (sugerencia: ISR con `revalidate: 3600`)

Cuando me respondas estas 6 preguntas más cualquier ajuste de scope, vamos al P2 (alertas, equipos, calculadoras UF/UTM/IPC, pantalla de cuenta, onboarding).