# ZLEF — Direction Artistique (Design Authority)

> The single source of truth for the visual language of every zlef.fr property.
> Dark, atmospheric, minimal. Two deep desaturated accents — OLIVE LEAF (#3E4618)
> and VINTAGE GRAPE (#4C3B4D) — over near-black. Lightly rounded corners, flat
> crisp components (no gradients, no glow). Large, legible type. No light theme,
> no web fonts, no blue. When in doubt, import the canonical stylesheet and use
> its tokens rather than inventing values.

Live guide:   https://da.zlef.fr
Tokens CSS:   https://da.zlef.fr/tokens.css   (import this — it IS the system)
Machine JSON: https://da.zlef.fr/design.json
This file:    https://da.zlef.fr/llms.txt

## How to apply (for an LLM building a zlef.fr page or component)

1. Add `<link rel="stylesheet" href="https://da.zlef.fr/tokens.css">`.
2. Set the page background to `var(--zl-bg)` and text to `var(--zl-text)`; use the
   `.zl-body` helper on `<body>` or `.zl-scope` on a wrapper.
3. Build UI from the component classes below; pull every colour, size, radius and
   spacing value from a `--zl-*` variable. Never hard-code a hex that isn't a token.
4. Components reference palette-agnostic roles (`--zl-accent*` = primary olive,
   `--zl-accent2*` = secondary grape). Raw ramps are `--zl-olive*` / `--zl-grape*`.
5. For landing/marketing surfaces, add the shared atmospheric field:
   `<script src="https://assets.zlef.fr/particles.js"></script>` (it also wires up
   analytics). Keep content panels opaque enough to stay readable above it.

## Core principles

- DARK ONLY. Background is near-black `#06060a`. There is no light theme.
- TWO ACCENTS ONLY. Olive leaf `#3E4618` (primary) and vintage grape `#4C3B4D`
  (secondary). Both deep and desaturated. Everything else is a neutral grey.
- LIGHT ROUNDING. Corners are subtle: 3px badges/chips, 5px buttons/inputs, 8px
  cards. Never pill-shaped UI, never heavily rounded.
- FLAT, CRISP COMPONENTS. Solid fills, 1px borders, NO gradients, NO coloured glow.
  Hover shifts the fill one shade — it never blooms, jumps or scales.
- LEGIBLE BY DEFAULT. Body text is 17px and never below 16px. Line-height 1.6.
  Controls are ≥44px tall. "Never too small, never too big."
- SUBTLE MOTION. Ease `cubic-bezier(.22,.61,.36,1)`, 110–360ms, no bounce. Honour
  `prefers-reduced-motion`.

## Palette

Surfaces:  bg #06060a · surface-1 #0e0e13 · surface-2 #15151c · surface-3 #1d1d25
Text:      #e9eae2 (primary) · #b6b7ad (soft) · #7d7e76 (muted) · #54554f (faint)
Olive leaf (primary):  deep #2c3212 · base #3e4618 · mid #59642a · soft #9dae50 · bright #bdce74
Vintage grape (2ndary):deep #382b39 · base #4c3b4d · mid #6b5470 · soft #b095b3 · bright #cdb6cf
  → base fills solid surfaces; soft is the readable text/link tint on dark.
Semantic:  success #6f9a3a · warning #c79a3e (amber) · danger #c2566a (dusty rose-red) · info #b095b3 (=grape)
Lines:     rgba(255,255,255,.07) hairline · .13 strong · olive focus ring.
Grape rgba(76,59,77,.10) appears ATMOSPHERICALLY ONLY (haze) — never as a UI fill.

## Banned (do NOT do these)

- Light / white backgrounds or any light theme.
- Blue accents or blue links in UI chrome — use olive instead. (Data-series
  colours from zl-charts `--zlc-cat-*` are exempt — charts may use their full
  validated categorical palette.)
- Pure `#000000` surfaces — use `#06060a` and the surface ramp.
- Full pills and systematically heavy rounding — keep rounding light (3–8px);
  circles stay circles.
- The "AI-generated" aesthetic: gradients on buttons, coloured glows, scale/zoom
  on hover. Flat, crisp, one-shade hover shift.
- Body text below 16px; low-contrast grey-on-grey for primary copy; thin hairline.
- Web-font dependencies — use the system sans stack + a monospace for code/data.
- Glossy gradients, skeuomorphism, bouncy motion.
- Unstyled framework defaults (Bootstrap/Material) that ignore these tokens.

## Typography

Sans: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
Mono: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace
Scale: xs 13 · sm 14.5 · base 17 · lg 19 · xl 22 · 2xl 28 · 3xl clamp(30,4vw,38) · 4xl clamp(40,6vw,56)
Weights: 400 normal · 550 medium · 700 bold.  Headings: tight tracking -0.02em.
Eyebrows/labels: UPPERCASE, 0.14em tracking, olive-soft.

## Spacing / radius / elevation

Spacing (4px base): 4 8 12 16 24 32 48 64  → `--zl-space-1..8`
Radius (LIGHT): sm 3 (badges) · md 5 (buttons/inputs) · lg 8 (cards) · xl 12 · pill 999 (circular only)
Shadow: sm/md/lg plain dark drops. No coloured glow — flatness is intentional.

## Components (classes in tokens.css)

- Buttons: `.zl-btn` + `--primary` (solid olive) | `--secondary` (solid grape) |
  `--ghost` (outline) | `--destructive` (SOLID rose-red for a destructive MAIN
  action — fill `--zl-danger`, ink `--zl-on-danger`, hover `--zl-danger-mid`,
  active `--zl-danger-deep`) | `--danger` (outline rose-red = the QUIET
  destructive variant: table rows, toolbars) | `--loading` (pair with a
  `.zl-spinner--btn` + `disabled`); sizes `--sm` / (default) / `--lg`. Flat, 5px
  radius, 1px border, ≥44px tall. Hover shifts fill one shade. Works identically
  as `<button>` or `<a>` — text-decoration is reset, never underlined.
  Destructive dialog pairing: `--destructive` action + « Annuler » as
  `--secondary` (or `--ghost` on dense UIs). Never olive for a destructive CTA.
- Inputs: `.zl-input`, `.zl-textarea`, `.zl-select`, `.zl-check`, `.zl-toggle`
  (toggle is a lightly-rounded rectangle, not a pill); wrap with `.zl-field` +
  `.zl-label` + `.zl-hint` (`.zl-hint--error`). Focus = olive border + soft ring.
  SELECT: customize end-to-end with `.zl-pick` — the generic custom select,
  sharing every tokens.css rule with `.zl-langpick` (flag span optional):
  `__btn` (value + chevron) over a `__menu` listbox of `__opt` rows + selected ✓
  (`__check`); `aria-expanded` drives open; keyboard ↑/↓/Home/End/Enter/Esc,
  click-outside; sync `aria-selected` into a hidden input or real `<select>`
  (markup + JS live on da.zlef.fr#champs). EXCEPTION — iOS keeps the NATIVE
  `<select class="zl-select">` (Apple HIG system picker wins on touch); detect:
  `/iP(hone|ad|od)/.test(navigator.userAgent) || (navigator.maxTouchPoints > 1
  && /Mac/.test(navigator.userAgent))`.
- Badges: `.zl-badge` + `--accent|--accent2|--success|--warning|--danger`;
  moods `--new|--beta|--wip|--draft|--experimental|--live|--deprecated|--archived`;
  sizes `--sm|--lg`; `.zl-badge--dot`; `--solid` (solid fill + dark ink,
  high-signal chips only). 3px radius (not a pill; `--lg` may reach 4px).
  Moods = product/feature lifecycle, strictly on-palette: draft/experimental
  are dashed, live has a built-in dot, deprecated is muted rose, archived faint.
- Cards: `.zl-card` + `--hover` / `--accent` (olive hairline); `.zl-card__title`,
  `.zl-card__body`. 8px radius.
- Header: `.zl-header` (translucent, blurred, hairline) with `.zl-header__brand`,
  `.zl-header__nav`, `.zl-navlink` (`--active` = olive-soft). Sticky top by
  default (z-index `--zl-z-nav`) and flex-wraps on narrow screens — no overflow;
  `.zl-header--static` opts out (embedded/demo headers). Moods (same markup):
  `--hero` (marketing/landing: transparent, no blur, no border, larger brand,
  non-sticky — sits over a hero/particle field) · `--compact` (utility/tool:
  slim, smaller brand, solid surface-1, no blur; stays sticky) · `--editorial`
  (magazine masthead: centered brand on its own line over a centered
  hairline-framed nav, generous vertical padding, non-sticky).
- Footer: `.zl-footer` (muted, hairline top border, links hover to olive-soft).
  Moods: `--columns` (sitemap: auto-fit grid of `.zl-footer__col` link columns
  with `.zl-footer__col-title`, collapses 4→2→1 with container width;
  `.zl-footer__bottom` bar for © + legal) · `--slim` (one thin centered xs
  line, minimal padding) · `--cta` (conversion: `.zl-footer__cta` headline +
  `__cta-sub` + primary button on a flat olive wash — no gradient — above a
  classic `.zl-footer__bottom` line).
  MOBILE RULE: every header/footer mood is intrinsically responsive (flex-wrap /
  grid auto-fit / min()) — it adapts to its CONTAINER width and must never
  overflow horizontally, even at 360px.
- Links: `.zl-link` (olive-soft, faint olive underline that fills on hover) +
  `--quiet` (neutral until hover). Keyboard keys: `.zl-kbd`.
- Tables: `.zl-table` inside `.zl-table-wrap` (rounded border, horizontal overflow,
  sticky header). Hairline rows, uppercase label headers, quiet row hover; numeric
  cells take `.zl-num` (mono tabular numerals, right-aligned).
- Tabs: `.zl-tabs` (role=tablist) + `.zl-tab`; active = `[aria-selected="true"]`
  or `--active` → olive-soft underline indicator. Never a filled pill.
- Alerts: `.zl-alert` + `--info` (grape, never blue) | `--success` | `--warning` |
  `--danger`; `.zl-alert__title` sits on its OWN line ABOVE the body (stacked,
  like a card title over its body — never inline; direct-child `<span>`s stack).
  Semantic wash + 3px left border; the copy says what to do next, not just what
  happened.
- Tooltip: put `data-zl-tip="…"` on any element — CSS-only bubble on surface-3,
  shows on hover AND keyboard focus.
- Empty state: `.zl-empty` + `.zl-empty__title` — an empty screen is an invitation
  to act: say what to create and give the button.
- Divider: `.zl-divider`.

## Loading states — MANDATORY sitewide

Nothing on zlef.fr may feel frozen. Every async action (fetch, submit, navigation,
long render) shows a visible state, built from these tokens.css primitives:
- Spinner: `.zl-spinner` (+ `--lg`); inside a pending button use
  `.zl-btn--loading` + `disabled` with a `.zl-spinner--btn` before the label.
- Skeleton: `.zl-skeleton` + `--title|--text|--block|--circle|--cell|--chart`.
  COMPOSE skeletons to mirror the final layout (title + lines + block) — never a
  lone gray box, and same dimensions as the real content so nothing jumps when
  it loads.
- Progress: `.zl-progress` > `.zl-progress__bar` (set the bar width inline/JS);
  unknown totals use `.zl-progress--indeterminate`.
- Full page / route transition: `.zl-loader-page` — centered column with a
  `.zl-spinner--lg` over a short muted label.
Per use case: loading TABLE = keep the real `.zl-table` columns, fill rows with
`--cell` lines; loading CHART = card with a `--title` skeleton + `--chart` (ghost
olive-tinted bars); FORM submit = inputs `disabled` + primary `.zl-btn--loading`;
media GALLERY = cards of `--block` + `--text` lines; UPLOAD = `.zl-progress` with
filename + percent label and a ghost `--sm` cancel button.
Under `prefers-reduced-motion` the skeleton shimmer stops (`--chart` included)
but the spinner keeps turning (slower) — it IS the status signal.

## Internationalisation (i18n) — language switching convention

Every project ships keyed string dictionaries, English + French at minimum. The
FALLBACK locale is the project's PRIMARY-audience language, NOT always English:

- GENERAL / worldwide projects → fallback `en` (a French browser gets French,
  everyone else English).
- FRENCH-DATA projects → fallback `fr`. A "French-data project" is one built
  primarily on French open data (INSEE, DVF, DECP, ARCOM, SNCF, OSM-France,
  RNE/OFGL, Joconde…) OR whose subject is France / French people with a primarily
  French audience (the fiche* family, the guess-the-French-value games, the maps,
  etc.). For these the default is French: a non-FR, non-EN browser AND the SSR
  first paint AND `<html lang>` all default to `fr`. EN stays fully available (via
  cookie or a navigator=en browser, and as the missing-string fallback).

The LANGUAGE SELECTOR is conditional — do not always render one:

- TWO LOCALES (en + fr, the default): show NO language selector. Pick the language
  silently from the browser (`navigator.language` / `Accept-Language`), falling back
  to the project's primary locale (en, or fr for French-data projects) — no UI chrome.
- THREE OR MORE LOCALES: show ONE curated global selector. It is a dropdown whose
  options are `<flag emoji> + native language name` (endonym), e.g.
  🇬🇧 English · 🇫🇷 Français · 🇪🇸 Español · 🇩🇪 Deutsch. Not a flag-only row, not
  English names — flag emoji THEN the language's own name.

Persistence is SITEWIDE, not per-app. The chosen language must follow the visitor
across every *.zlef.fr property. Store it in a cookie `zl-lang` scoped to domain
`.zlef.fr` (path `/`, ~1 year) — NOT localStorage (that is per-origin and won't
share across subdomains). Resolution order on load:
`zl-lang` cookie → `navigator.language` → primary fallback (`en`, or `fr` for a
French-data project). Writing the selector updates the cookie so the next zlef site
already opens in that language.

Use the canonical `.zl-langpick` custom dropdown (CSS ships in tokens.css;
markup + a11y JS live on da.zlef.fr) — NOT a native `<select>`, which can't
render flag emoji reliably
(blank on Windows) and can't be styled to the token system. The picker is a
button (current flag + native name + chevron) over a token-styled menu with a
selected ✓, full keyboard support (↑/↓/Home/End/Enter/Esc) and click-outside to
close. Place it in the header (or footer on minimal pages). Logged-in users may
also persist to their account, but the `.zlef.fr` cookie stays the cross-site
source of truth.

## Charts, graphs & timelines — zl-charts

Do NOT hand-roll chart SVG or pull in a charting library. Every project that shows
data uses the shared, dependency-free engine. Import it AFTER tokens.css:
  <link rel="stylesheet" href="https://da.zlef.fr/zl-charts.css">
  <script defer src="https://da.zlef.fr/zl-charts.js"></script>

Two ways to draw. Declarative (best for SSR — emit container + JSON, the engine
hydrates every `[data-zlc]` on load):
  <figure class="zlc" data-zlc>
    <script type="application/json" class="zlc-spec">
      {"type":"bar","title":"Ventes","x":{"values":["Nord","Sud"]},
       "series":[{"name":"2025","data":[120,90]}],"valueFmt":"integer"}
    </script>
  </figure>
Imperative: `ZLC.mount(el, spec)`.

Forms (`spec.type`): `bar` (add `horizontal:true`, `stacked:true`, or an
`emphasis` index) · `line` · `area` · `scatter` (data = `[{x,y,label}]`) ·
`heatmap` (`rows`, `x.values`, `data[r][c]`) · `timeline` (`events:[{t,label}]`
+ `periods:[{from,to,label}]`, t/from/to = year number or ISO date) · `stat`
(tile: `value`,`delta`,`sub`,`spark[]`,`hero:true`) · `meter`
(`value`,`max`,`thresholds`) · `sparkline`.

Common spec keys: `title`/`subtitle`, `x:{values,title,type:'time'}`,
`series:[{name,data,color?}]`, `valueFmt` (`'number'|'compact'|'euro'|'percent'|
'integer'` or a function), `valueDecimals`, `unit`, `height`, `table:false` to
drop the table toggle, `locale` (else auto from `<html lang>` / `zl-lang`).

Rules the engine enforces so you don't have to (ZELF data-viz method):
- ONE axis, never two scales. Two measures of different scale → two charts.
- Categorical hues assigned in FIXED order (`--zlc-cat-1..8`), never cycled; a 9th
  series folds into "Other". Palette is CVD-validated on the ZLEF surface (worst
  adjacent ΔE 14.7). Color follows the entity, not its rank.
- Sequential = one olive ramp (`--zlc-seq-*`); diverging = rose↔gray↔olive.
- Status colors (`--zlc-good/warning/serious/critical`) are RESERVED for state and
  ship with an icon+label — never reused as "series 4".
- Legend auto-shown for ≥2 series; direct labels stay sparing; grid is hairline.
- Tooltips are ON by default (hover on desktop, tap on mobile) via a single shared
  floating node; a table-view twin toggles under every cartesian chart; numbers and
  dates format through Intl in the resolved locale. Dark-only (one mode).
- Dense temporal series get ZOOM + internal horizontal scroll automatically: it turns
  on when `x.type:"time"` (or many points — line/area ≥20, bar >24, timeline >10),
  and `zoom:true`/`zoom:false` force it either way. The plot re-lays-out at
  (containerWidth × zoom) px inside its own scroll box (text/marks keep true size),
  the Y-axis stays PINNED while you pan the full range, and the whole range is
  reachable by scroll. Controls: −/⤡/+ buttons · ⌘/Ctrl+wheel zoom-at-pointer ·
  shift+wheel pan · drag-to-pan (desktop) · pinch + one-finger swipe (mobile).
  Tune with `maxZoom` / `zoomStart`.
- EVERY chart renders pixel-accurate at the real container width and redraws on
  resize: axis text and marks keep their true size at any width. The engine never
  stretches a fixed viewBox, so never wrap it in transforms that scale text.
Override any series hue per project by redefining `--zlc-cat-N` in your own CSS.

## Logo

Geometric ZLEF wordmark with angular notch cuts, white fill, faint glow filter,
no web font. SVG: https://assets.zlef.fr/logo.svg (viewBox 0 0 322 100).

## Mascot — Sylve

ZLEF's mascot: a faceted low-poly origami sentinel folded from olive-leaf planes,
crown notched like the wordmark, a sparing vintage-grape gaze. Self-contained SVG,
transparent bg, viewBox 0 0 240 200, class-grouped for restyling.
- https://da.zlef.fr/mascot.svg (detailed)
- https://da.zlef.fr/mascot-mini.svg (simplified, icon scale)
Use as the default media for EMPTY STATES, 404s, and illustrations — drop it inside
`.zl-empty` above the title. Keep it sparing: one per empty screen, never decoration
on a view that already has data. When possible (and validated by the owner), derive
a PRODUCT-SPECIFIC variant instead of reusing stock Sylve: same low-poly origami
construction and class-based palette, re-themed to the product's identity — the
classes (`.m-lit`, `.m-eye`, …) exist precisely so a product can restyle it.