---
name: Validate - ui-polish + verify wiring
description: Enforce theme tokens via the ui-polish CLI, verify the scaffold-doc outputs + applied wiring, then typecheck
next_step: null
---

## STEP 03: Validate — ui-polish + verify integration

`scaffold-doc` (step-02) already wrote the i18n files, upserted
`docs-manifest.json`, and handed you the wiring plan you applied. This step
**enforces colours deterministically** and **verifies** the result.

### 0. Structure gate (blocking)

The doc must lead with a factual **objective** and carry **no** value-proposition
pitch (SKILL.md rule #12). Re-run `extract-doc` on the module and assert the scan
of the **now-generated** artifacts is both clean and complete:

```bash
npx tsx skills/documentation/cli/extract-doc/index.ts \
  --spec '{"type":"<type>","target":"<module>","application":"<app>","projectPath":"<project-root>"}'
```

Two mirror conditions, both hard gates:

- **`report.existingDoc.forbiddenSections` MUST be empty.** If non-empty, the doc
  is **not** done: for each `{ file, line, token }`, remove the offending section
  (problème/solution, Bénéfices, Avant/Après — see step-02 "Correcting an existing
  doc"), then re-run until it returns 0.
- **`report.existingDoc.missingRequired` MUST be empty.** It can list:
  - `"objective"` — the mandatory Section 1 is absent: add the **Objectif** section
    first (i18n `sections.objective` + `objective`, or `overview.objective` for
    DocRenderer; rendered via `t('objective')`) — the header subtitle does NOT count.
  - `"summary"` (user) — the header accent tagline is absent: add the `summary` key
    and render it between title and subtitle (`text-xl … text-[var(--color-accent-600)]`),
    with the inline stats line.

  Fix each and re-run until it returns 0.

This reuses the exact same deterministic detection as step-01 — no separate rules.

### 1. Colour / theme compliance → run ui-polish

Theme-token compliance is NOT checked by hand here — the ui-polish CLI does it.
Run it on the generated page (apply mode, regeneration disabled so the page is
never rebuilt — only colour utilities are rewritten):

```bash
npx tsx skills/development/frontend/ui-polish/cli/ui-polish/index.ts \
  --project-path "<web-root>" --mode apply --regenerate-threshold 0 \
  --page "src/pages/docs/business/<group>/<app>/<module>/index.tsx" \
  --rules R2,R3,R7,R12,R13,R14,R15,R16,R17
```

Then re-run in `--mode audit` and confirm **0 errors**. Finish the residual
neutral cases the CLI flags (see the `/ui-components` skill). Doc-specific intent
the CLI can't infer — verify by eye: dashboard chart series use `--dataviz-*`
(not accent), highlight blocks use the discreet accent pattern.

### 2. Verify the scaffold-doc outputs

- [ ] 4 i18n files at `src/i18n/locales/{fr,en,de,it}/docs-{kebab}.json` — `user` FLAT (no root key); `developer/database/testing` nested under the namespace key
- [ ] `docs-manifest.json` has the entry (correct `id`, `path`, `i18nNamespace`, `languages`)
- [ ] **Wiring applied** (each plan item's `idempotencyMarker` now present):
  - `i18n/config.ts` — namespace in all 4 spots (destructured var, `import()`, return object, `ns: [ … ]`)
  - `components/routing/DocRoutes.tsx` — lazy import + `<Route>` child under the `/docs/business` group
  - `contexts/DocPanelContext.tsx` — `docMapping` keys (+ `appDocMapping` if default)
  - `pages/system/docs/user/UserIndexPage.tsx` — module entry (user type) + its `user.modules.<x>.name/.description` i18n keys

### 3. Quality checks (user type — the Mock UI is yours)

- [ ] Mock UI faithfully reproduces the real page (not a generic KPI/table)
- [ ] Each chart matches the real recharts TYPE (from `extract-doc` `charts[]`)
- [ ] Expressive mock data: ratio max/min(>0) ≥ 5x, peak ≥ 90% + valley ≤ 15%, height ≥ `h-24`/`h-20`
- [ ] Every Mock UI block has an `Annotation`, inside the same padded container
- [ ] No DocPanel overflow: `overflow-hidden` on chart cards, `min-w-0` on flex children, no fixed px widths
- [ ] Root container `<div className="space-y-8 max-w-5xl mx-auto pb-12">` (no horizontal padding)
- [ ] Section 1 is **Objectif** (description of what the module does) — no problème/solution, Bénéfices or Avant-Après (enforced by the §0 gate)

### 4. Typecheck

At the web root: `npm run typecheck` (or `tsc --noEmit`) — phantom imports or a
malformed wiring edit fail here. Fix before finishing.

### Artifact reference (verified against the app)

| Artifact | Path |
|----------|------|
| User doc page | `src/pages/docs/business/{platform\|personal}/{app}/{module}/index.tsx` (route omits the `platform/personal` segment) |
| i18n (central) | `src/i18n/locales/{lang}/docs-{kebab}.json` (FLAT for user; nested under the namespace for DocRenderer) |
| i18n registration | `src/i18n/config.ts` |
| Routing | `src/components/routing/DocRoutes.tsx` (NOT `DynamicRouter.tsx` — it only calls `{DocRoutes()}`) |
| Manifest | `src/pages/docs/docs-manifest.json` |
| Contextual panel | `src/contexts/DocPanelContext.tsx` |
| User index | `src/pages/system/docs/user/UserIndexPage.tsx` |

### Completion

Documentation is generated, themed (ui-polish), wired, internationalised (4 langs)
and listed in the manifest. Route renders inside `DocsLayout`; the DocPanel edge
button opens it for the module's routes.
