Architecture

Le site est une application Next.js 16 (App Router) construite en HTML statique au moment du build, stylisée avec le langage de design YuTheme, déployée sur Vercel. Il n'y a pas de runtime serveur.

Stack

• Next.js 16 (App Router, génération statique)
• React 19
• TypeScript
• pnpm (gestionnaire de paquets, version épinglée via packageManager)
• Monorepo Turborepo (apps/, packages/)
• next-intl pour les sept langues, localePrefix: as-needed
• Tokens et conventions éditoriales YuTheme (voir design.md)
• Icônes Lucide via lucide-react
• Polices : Geist Variable et Geist Mono Variable via next/font/local

Le seul JavaScript client est une petite quantité d'hydratation : le menu mobile du header, le scrollspy, le défilement doux des ancres et les révélations au scroll.

Structure

apps/web/src/
  app/
    [locale]/
      layout.tsx            coque du document, polices, metadata, JSON-LD
      page.tsx              accueil mono-page
      docs/page.tsx         index de la documentation
      docs/[slug]/page.tsx  pages individuelles de documentation
      globals.css           tokens YuTheme, styles de base, motion
    sitemap.ts              sitemap pour toutes les langues
    robots.ts
  components/
    Analytics.tsx           hook Umami, activé par env, inerte par défaut
    Footer.tsx
    Header.tsx              header fixe, scrollspy, panneau mobile
    Icon.tsx                carte d'icônes Lucide, noms typés
    Reveal.tsx              révélation au scroll via IntersectionObserver
    sections/
      Hero.tsx              titre + carte terminal
      About.tsx
      WhatIDo.tsx           grille de cartes
      HowIWork.tsx
      WhereILive.tsx
      SelectedWork.tsx      liste de travaux publics
  data/site.ts              constantes du site : URLs, navigation
  i18n/                     routing, config de request, navigation typée
  lib/docs.ts               pipeline markdown des pages de docs
packages/
  content/                  sources docs/, lues par langue avec fallback EN
  i18n/                     liste des langues + messages des sept locales
  ui/styles/                CSS YuTheme canonique, référence des tokens

Localisation

• Langues : en (par défaut, sans préfixe), pt, es, fr, de, ja, zh-CN.
• Le copy d'interface vit dans packages/i18n/messages/<locale>.json.
• La documentation vit dans packages/content/docs/<locale>/ ; quand une langue n'a pas de fichier, la version anglaise est servie en fallback.
• Les routes sont statiques : chaque langue et chaque slug de doc est pré-rendu au build via generateStaticParams.

Pipeline des docs

Les pages de documentation lisent le dossier packages/content/docs/ via packages/content/src/index.ts :

• chaque doc est un fichier Markdown avec frontmatter : title, description, order, updated ;
• l'app le rend avec remark/rehype (GFM, headings avec slug, autolinks, HTML assaini) sur /docs/<slug>, avec un index sur /docs ;
• @ellamizuki/content reste externe au bundle de l'app (serverExternalPackages) pour que les lectures filesystem fonctionnent en production.

Comme la collection lit le même dossier versionné dans le dépôt, les docs restent synchronisées : une source de vérité, deux vues (page du site et fichiers du repo).

Flux de données

• Au build : Next.js pré-rend /, /docs, /docs/* pour chaque langue.
• Le contenu est pré-rendu ; pas de serveur, pas d'API, pas de données au runtime.
• Analytics (Umami) n'est injecté que lorsque NEXT_PUBLIC_UMAMI_SRC et NEXT_PUBLIC_UMAMI_WEBSITE_ID sont définies au build.

Conventions

• HTML sémantique avec un seul h1 par page.
• Headings de section ordonnés (h2 puis h3), jamais de niveaux sautés.
• Les liens externes s'ouvrent dans un nouvel onglet avec rel="noopener noreferrer".
• Les liens rendus par next-intl ne reçoivent jamais un href déjà préfixé ; le préfixe de langue est toujours ajouté par les helpers de navigation.
• Le reduced motion est respecté partout : shimmer, révélations et transitions sont contrôlés par prefers-reduced-motion.