# Winerix Reference Visual System

Design system for KPI cards, dashboards, decks and reference pages.

## KPI family tokens

| Family | Tone | Background | Accent | Shape | Copy rule |
|---|---|---|---|---|---|
| Reference authority | institutional, premium, calm | #fff8ea | #7d1f2d | score ring plus proof stack | Use one strong claim, one proof line and one visible caveat. |
| Wine territory | cartographic, grounded, regulatory | #f4efe3 | #52724f | layered map card | Separate area, parcel, product and regulation in the copy. |
| Oenotourism capacity | bright, welcoming, service oriented | #edf7f6 | #2b8f99 | capacity grid with accessibility badges | Never say capacity equals visits; keep the frequency caveat visible. |
| Market context | precise, sober, financial | #f7f3ed | #b15a32 | sparkline and segment badge | Frame as market context, not as a domain-level price. |
| Business density | actionable, sales, territory intelligence | #f0f4ed | #4b7f52 | NAF heatmap plus core/adjacent split | Show aggregated density before any nominative business usage. |
| Source operations | operational, transparent, quality first | #f5f7f8 | #315c7a | kanban mini board with gate badges | Use publish / annotate / block language, not vague readiness claims. |

## Components

### Hero score card

- Use case: Top of page or first slide.
- Structure: eyebrow, large metric, one sentence, caveat badge, primary CTA
- Rules: one metric only; source visible; gate status visible; no decorative chart without meaning

### Proof stack

- Use case: Appellation, source lineage or citation sections.
- Structure: three proof columns plus gap queue
- Rules: show gaps; show source URL or citation; separate official source from Winerix inference

### KPI family card

- Use case: Dashboard rail and scorecard overview.
- Structure: family name, north star, hero KPI, aggregation level, caveat
- Rules: one aggregation level per card; avoid mixed KPI families; keep caveat under 140 characters

### Copy export tile

- Use case: Data room, API manifest and static dashboard.
- Structure: label, audience, endpoint, copy button, format badges
- Rules: make Markdown the default copy format; show JSON and CSV as technical formats; never hide caveats behind a secondary click

### Source gate badge

- Use case: Launch readiness, maintenance board and publication gate.
- Structure: status, due level, action, fallback
- Rules: use strong verbs; red for blocked only; amber for annotate/stale; green only for publishable

## Copy rules

- Always pair number + source + caveat.
  Bad: 12 M oenotourists prove the market.
  Good: Atout France gives a national oenotourism order of magnitude; it does not prove local visits.
- Separate official facts from Winerix inference.
  Bad: This appellation is fully proven.
  Good: INAO and eAmbrosia sources align; remaining textual gaps stay visible for review.
- Use action labels instead of vague status labels.
  Bad: Data is almost ready.
  Good: Publish with annotations after source freshness and import status are checked.
- Do not overstate pipeline-only sources.
  Bad: Sirene gives our wine business map.
  Good: Sirene pipeline is ready; publish aggregated NAF density after local import.