@hgdc/docs 0.2.0 → 0.4.0

package/docs.schema.json

@@ -248,6 +248,27 @@
         }
       }
     },
+    "redirects": {
+      "maxItems": 500,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "type": "string",
+            "pattern": "^\\/(?!\\/)[A-Za-z0-9._~\\-/%]*$"
+          },
+          "destination": {
+            "type": "string",
+            "minLength": 1
+          },
+          "permanent": {
+            "type": "boolean"
+          }
+        },
+        "required": ["source", "destination"]
+      }
+    },
     "assistant": {
       "type": "object",
       "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/docs",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Modèle de site de HGDC Docs : documentation MDX (docs.json) construite avec Astro Starlight, recherche, versions, llms.txt et assistant.",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,6 +31,7 @@
     "@astrojs/starlight": "0.42.6",
     "@fontsource-variable/geist": "5.3.0",
     "@fontsource-variable/inter": "5.3.0",
+    "@mdx-js/mdx": "3.1.1",
     "astro": "7.3.8",
     "github-slugger": "2.0.0",
     "hast-util-select": "6.0.4",
@@ -41,6 +42,7 @@
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
     "vfile": "6.0.3",
+    "yaml": "2.9.1",
     "zod": "4.6.5"
   },
   "devDependencies": {

package/src/build/auto-import.ts

@@ -1,30 +1,7 @@
 import type { Root } from "mdast"
 import type { VFile } from "vfile"
 
-/**
- * Composants disponibles dans chaque page MDX sans `import`, comme chez Mintlify
- * (`<Note>`, `<Steps>`, `<Card>`…). Le plugin ajoute en tête du fichier l'import des
- * composants que la page n'importe pas déjà elle-même.
- */
-export const MDX_COMPONENTS = [
-  "Accordion",
-  "AccordionGroup",
-  "Card",
-  "CardGroup",
-  "Check",
-  "CodeGroup",
-  "Columns",
-  "Danger",
-  "Frame",
-  "Info",
-  "Note",
-  "Step",
-  "Steps",
-  "Tab",
-  "Tabs",
-  "Tip",
-  "Warning",
-] as const
+import { MDX_COMPONENTS } from "../core/components.ts"
 
 const SOURCE = "@hgdc/docs/components"
 
@@ -64,6 +41,10 @@ function importNode(name: string): EsmNode {
   }
 }
 
+/**
+ * Ajoute en tête de chaque page MDX l'import des composants (`core/components.ts`) que la
+ * page n'importe pas déjà elle-même : `<Note>`, `<Steps>`… s'écrivent sans `import`.
+ */
 export function remarkAutoImport() {
   return (tree: Root, file: VFile) => {
     if (!String(file.path ?? file.history.at(-1) ?? "").endsWith(".mdx")) return

package/src/build/content.ts

@@ -0,0 +1,82 @@
+import type { Element, ElementContent, Root, RootContent } from "hast"
+
+/**
+ * Mise en forme du contenu, au build.
+ *
+ * Titre d'endpoint (`## GET /v9/projects`) en barre de méthode : la méthode en pastille
+ * colorée, le chemin en police mono, ses paramètres (`:id`, `{id}`) soulignés. Le texte du
+ * titre ne change pas : l'ancre, la table des matières et la recherche restent les mêmes.
+ * Tableau : enveloppé dans `.hd-table`, qui défile en largeur sans déborder de la colonne.
+ */
+const ENDPOINT = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/\S*)$/
+const PARAM = /(:[A-Za-z_][\w]*|\{[^}/]+\})/
+
+export function parseEndpoint(text: string): { method: string; path: string } | null {
+  const match = ENDPOINT.exec(text.trim())
+  return match ? { method: match[1]!, path: match[2]! } : null
+}
+
+function textOf(node: Element): string | null {
+  let text = ""
+  for (const child of node.children) {
+    if (child.type === "text") text += child.value
+    else if (child.type === "element" && child.tagName === "code") {
+      for (const inner of child.children) if (inner.type === "text") text += inner.value
+    } else return null
+  }
+  return text
+}
+
+function pathChildren(path: string): Array<ElementContent> {
+  return path
+    .split(PARAM)
+    .filter(Boolean)
+    .map((part) =>
+      PARAM.test(part)
+        ? {
+            type: "element",
+            tagName: "span",
+            properties: { className: ["hd-path__param"] },
+            children: [{ type: "text", value: part }],
+          }
+        : { type: "text", value: part },
+    )
+}
+
+export function rehypeDocsContent() {
+  const walk = (nodes: Array<RootContent | ElementContent>) => {
+    for (const [index, node] of nodes.entries()) {
+      if (node.type !== "element") continue
+      // Tableau : un cadre qui défile seul en largeur, le tableau garde toute la largeur.
+      if (node.tagName === "table") {
+        nodes[index] = { type: "element", tagName: "div", properties: { className: ["hd-table"] }, children: [node] }
+        continue
+      }
+      if (node.tagName !== "h2" && node.tagName !== "h3") {
+        walk(node.children)
+        continue
+      }
+      const text = textOf(node)
+      const endpoint = text ? parseEndpoint(text) : null
+      if (!endpoint) continue
+      node.properties.className = [...((node.properties.className as Array<string>) ?? []), "hd-endpoint"]
+      node.children = [
+        {
+          type: "element",
+          tagName: "span",
+          properties: { className: ["hd-method"], dataMethod: endpoint.method.toLowerCase() },
+          children: [{ type: "text", value: endpoint.method }],
+        },
+        { type: "text", value: " " },
+        {
+          type: "element",
+          tagName: "code",
+          properties: { className: ["hd-path"] },
+          children: pathChildren(endpoint.path),
+        },
+      ]
+    }
+  }
+  // Typé en `unknown` : Astro et ce paquet ne résolvent pas toujours le même @types/hast.
+  return (tree: unknown) => walk((tree as Root).children)
+}

package/src/build/markdown.ts

@@ -70,12 +70,17 @@ function replaceCodeBlocks(content: Element): void {
   }
 }
 
-/** Encadré → citation dont la première ligne porte le titre en gras : `> **Note**`. */
+/**
+ * Encadré → citation dont la première ligne porte le titre en gras : `> **Note**`. Le titre
+ * est celui de la page, sinon le nom du type (`aria-label` de `.hd-callout`).
+ */
 function replaceAsides(content: Element): void {
-  for (const aside of selectAll("aside.starlight-aside", content)) {
-    const title = select(".starlight-aside__title", aside)
-    const body = select(".starlight-aside__content", aside)
-    const label = title ? toString(title as Parameters<typeof toString>[0]).trim() : ""
+  for (const aside of selectAll("aside.starlight-aside, aside.hd-callout", content)) {
+    const title = select(".starlight-aside__title, .hd-callout__title", aside)
+    const body = select(".starlight-aside__content, .hd-callout__body", aside)
+    if (body && title) body.children = body.children.filter((child) => child !== title)
+    const named = typeof aside.properties["ariaLabel"] === "string" ? aside.properties["ariaLabel"] : ""
+    const label = title ? toString(title as Parameters<typeof toString>[0]).trim() : named
     const quote: Element = {
       type: "element",
       tagName: "blockquote",

package/src/components/Accordion.astro

@@ -1,4 +1,6 @@
 ---
+import Icon from "../overrides/Icon.astro"
+
 interface Props {
   title: string
   defaultOpen?: boolean
@@ -7,6 +9,6 @@ const { title, defaultOpen = false } = Astro.props
 ---
 
 <details class="hgdc-accordion" open={defaultOpen}>
-  <summary>{title}</summary>
+  <summary><Icon name="chevron-right" size={16} class="hgdc-accordion__chevron" /><span>{title}</span></summary>
   <div class="hgdc-accordion__body"><slot /></div>
 </details>

package/src/components/Callout.astro

@@ -0,0 +1,31 @@
+---
+import Icon from "../overrides/Icon.astro"
+
+/**
+ * Encadré commun à Note, Info, Tip, Check, Warning et Danger : un lavis de sa couleur, un
+ * filet de la même teinte et son icône. Le type est dit au lecteur d'écran.
+ */
+export type CalloutTone = "note" | "info" | "tip" | "check" | "warning" | "danger"
+interface Props {
+  tone: CalloutTone
+  title?: string | undefined
+}
+const LABELS: Record<CalloutTone, string> = {
+  note: "Note",
+  info: "Info",
+  tip: "Astuce",
+  check: "Validé",
+  warning: "Attention",
+  danger: "Danger",
+}
+const ICONS = { note: "note", info: "info", tip: "tip", check: "circle-check", warning: "warning", danger: "danger" } as const
+const { tone, title } = Astro.props
+---
+
+<aside class="hd-callout" data-tone={tone} aria-label={title ?? LABELS[tone]}>
+  <Icon name={ICONS[tone]} class="hd-callout__icon" />
+  <div class="hd-callout__body">
+    {title && <p class="hd-callout__title">{title}</p>}
+    <slot />
+  </div>
+</aside>

package/src/components/Card.astro

@@ -1,4 +1,6 @@
 ---
+import Icon from "../overrides/Icon.astro"
+
 interface Props {
   title: string
   href?: string
@@ -10,6 +12,6 @@ const Tag = href ? "a" : "div"
 ---
 
 <Tag class:list={["hgdc-card", { "hgdc-card--link": href }]} href={href}>
-  <span class="hgdc-card__title">{title}</span>
+  <span class="hgdc-card__title">{title}{href && <Icon name="arrow-right" size={16} class="hgdc-card__arrow" />}</span>
   <div class="hgdc-card__body"><slot /></div>
 </Tag>

package/src/components/Check.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title } = Astro.props
 ---
 
-<Aside type="tip" title={title}><slot /></Aside>
+<Callout tone="check" title={Astro.props.title}><slot /></Callout>

package/src/components/CodeGroup.astro

@@ -1,4 +1,12 @@
 ---
+// Plusieurs blocs de code en onglets, nommés d'après le titre de chaque bloc (```bash npm).
+// Sans JavaScript, seul le premier bloc s'affiche ; le script ajoute les onglets.
 ---
 
-<div class="hgdc-code-group"><slot /></div>
+<hd-code-group class="hgdc-code-group not-content"><slot /></hd-code-group>
+
+<script>
+  import { defineCodeGroup } from "../widget/code.ts"
+
+  defineCodeGroup()
+</script>

package/src/components/Danger.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title } = Astro.props
 ---
 
-<Aside type="danger" title={title}><slot /></Aside>
+<Callout tone="danger" title={Astro.props.title}><slot /></Callout>

package/src/components/Info.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title = "Info" } = Astro.props
 ---
 
-<Aside type="note" title={title}><slot /></Aside>
+<Callout tone="info" title={Astro.props.title}><slot /></Callout>

package/src/components/Note.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title } = Astro.props
 ---
 
-<Aside type="note" title={title}><slot /></Aside>
+<Callout tone="note" title={Astro.props.title}><slot /></Callout>

package/src/components/Tip.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title } = Astro.props
 ---
 
-<Aside type="tip" title={title}><slot /></Aside>
+<Callout tone="tip" title={Astro.props.title}><slot /></Callout>

package/src/components/Warning.astro

@@ -1,10 +1,9 @@
 ---
-import { Aside } from "@astrojs/starlight/components"
+import Callout from "./Callout.astro"
 
 interface Props {
   title?: string
 }
-const { title } = Astro.props
 ---
 
-<Aside type="caution" title={title}><slot /></Aside>
+<Callout tone="warning" title={Astro.props.title}><slot /></Callout>

package/src/core/components.ts

@@ -0,0 +1,166 @@
+/**
+ * Composants disponibles dans chaque page MDX sans `import`, comme chez Mintlify
+ * (`<Note>`, `<Steps>`, `<Card>`…). Lus par le build (`build/auto-import.ts`) et par
+ * l'éditeur de la console (validation, insertion par « / » ou « < », mode visuel).
+ * Les props décrites ici sont celles des fichiers `src/components/*.astro`.
+ */
+export const MDX_COMPONENTS = [
+  "Accordion",
+  "AccordionGroup",
+  "Card",
+  "CardGroup",
+  "Check",
+  "CodeGroup",
+  "Columns",
+  "Danger",
+  "Frame",
+  "Info",
+  "Note",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tip",
+  "Warning",
+] as const
+
+export type MdxComponent = (typeof MDX_COMPONENTS)[number]
+
+export function isMdxComponent(name: string): name is MdxComponent {
+  return (MDX_COMPONENTS as ReadonlyArray<string>).includes(name)
+}
+
+export type ComponentProp = {
+  name: string
+  label: string
+  type: "string" | "number" | "boolean"
+  required?: boolean
+}
+
+/** Props de chaque composant, pour les formulaires du mode visuel. */
+export const COMPONENT_PROPS: Record<MdxComponent, ReadonlyArray<ComponentProp>> = {
+  Accordion: [
+    { name: "title", label: "Titre", type: "string", required: true },
+    { name: "defaultOpen", label: "Ouvert au départ", type: "boolean" },
+  ],
+  AccordionGroup: [],
+  Card: [
+    { name: "title", label: "Titre", type: "string", required: true },
+    { name: "href", label: "Lien", type: "string" },
+  ],
+  CardGroup: [{ name: "cols", label: "Colonnes", type: "number" }],
+  Check: [{ name: "title", label: "Titre", type: "string" }],
+  CodeGroup: [],
+  Columns: [{ name: "cols", label: "Colonnes", type: "number" }],
+  Danger: [{ name: "title", label: "Titre", type: "string" }],
+  Frame: [{ name: "caption", label: "Légende", type: "string" }],
+  Info: [{ name: "title", label: "Titre", type: "string" }],
+  Note: [{ name: "title", label: "Titre", type: "string" }],
+  Step: [{ name: "title", label: "Titre", type: "string", required: true }],
+  Steps: [],
+  Tab: [{ name: "title", label: "Titre", type: "string", required: true }],
+  Tabs: [{ name: "syncKey", label: "Clé de synchronisation", type: "string" }],
+  Tip: [{ name: "title", label: "Titre", type: "string" }],
+  Warning: [{ name: "title", label: "Titre", type: "string" }],
+}
+
+export type BlockCategory = "Encadrés" | "Mise en page" | "Contenu"
+
+/**
+ * Blocs proposés à l'insertion, dans l'ordre du menu. `snippet` est le MDX inséré ; `$|`
+ * marque l'endroit où placer le curseur. Plusieurs blocs peuvent produire le même
+ * composant (colonnes à 2, 3 ou 4).
+ */
+export type Block = {
+  id: string
+  label: string
+  description: string
+  category: BlockCategory
+  keywords: ReadonlyArray<string>
+  snippet: string
+}
+
+const callout = (name: string, label: string, description: string, keywords: Array<string>): Block => ({
+  id: name.toLowerCase(),
+  label,
+  description,
+  category: "Encadrés",
+  keywords: [name.toLowerCase(), ...keywords],
+  snippet: `<${name}>\n$|\n</${name}>`,
+})
+
+const columns = (cols: number): Block => ({
+  id: `columns-${cols}`,
+  label: `${cols} colonnes`,
+  description: `Cartes côte à côte, sur ${cols} colonnes.`,
+  category: "Mise en page",
+  keywords: ["colonnes", "columns", "grille", String(cols)],
+  snippet: `<Columns cols={${cols}}>\n${Array.from({ length: cols }, (_, i) => `  <Card title="Carte ${i + 1}">${i === 0 ? "$|" : ""}</Card>`).join("\n")}\n</Columns>`,
+})
+
+export const BLOCKS: ReadonlyArray<Block> = [
+  callout("Note", "Note", "Une information utile à côté du texte.", ["information", "remarque"]),
+  callout("Tip", "Conseil", "Une astuce qui fait gagner du temps.", ["astuce", "conseil"]),
+  callout("Info", "Info", "Un contexte ou une précision.", ["information"]),
+  callout("Warning", "Attention", "Un point à ne pas manquer.", ["attention", "avertissement"]),
+  callout("Danger", "Danger", "Une action risquée ou irréversible.", ["danger", "risque"]),
+  callout("Check", "Validé", "Une étape réussie, un résultat attendu.", ["validé", "succès", "ok"]),
+  columns(2),
+  columns(3),
+  columns(4),
+  {
+    id: "steps",
+    label: "Étapes",
+    description: "Une marche à suivre numérotée.",
+    category: "Mise en page",
+    keywords: ["étapes", "steps", "procédure"],
+    snippet:
+      '<Steps>\n  <Step title="Première étape">\n    $|\n  </Step>\n  <Step title="Deuxième étape">\n  </Step>\n</Steps>',
+  },
+  {
+    id: "tabs",
+    label: "Onglets",
+    description: "Plusieurs variantes d'un même contenu.",
+    category: "Mise en page",
+    keywords: ["onglets", "tabs"],
+    snippet: '<Tabs>\n  <Tab title="Premier">\n    $|\n  </Tab>\n  <Tab title="Second">\n  </Tab>\n</Tabs>',
+  },
+  {
+    id: "accordion",
+    label: "Accordéon",
+    description: "Un détail replié, ouvert au clic.",
+    category: "Mise en page",
+    keywords: ["accordéon", "accordion", "replié", "faq"],
+    snippet: '<AccordionGroup>\n  <Accordion title="Question">\n    $|\n  </Accordion>\n</AccordionGroup>',
+  },
+  {
+    id: "card",
+    label: "Carte",
+    description: "Un lien mis en avant, avec un titre.",
+    category: "Contenu",
+    keywords: ["carte", "card", "lien"],
+    snippet: '<Card title="Titre" href="/">\n  $|\n</Card>',
+  },
+  {
+    id: "code-group",
+    label: "Groupe de code",
+    description: "Le même exemple en plusieurs langages.",
+    category: "Contenu",
+    keywords: ["code", "codegroup", "exemple"],
+    snippet: "<CodeGroup>\n\n```bash npm\n$|\n```\n\n```bash bun\n\n```\n\n</CodeGroup>",
+  },
+  {
+    id: "frame",
+    label: "Cadre",
+    description: "Une image ou une capture, avec sa légende.",
+    category: "Contenu",
+    keywords: ["cadre", "frame", "image", "capture"],
+    snippet: '<Frame caption="Légende">\n  ![Description de l\'image]($|)\n</Frame>',
+  },
+]
+
+/** Texte à insérer et position du curseur dans ce texte. */
+export function expandSnippet(snippet: string): { text: string; cursor: number } {
+  const cursor = snippet.indexOf("$|")
+  return cursor === -1 ? { text: snippet, cursor: snippet.length } : { text: snippet.replace("$|", ""), cursor }
+}

package/src/core/config.ts

@@ -56,6 +56,47 @@ const logo = z.union([
   z.object({ light: z.string(), dark: z.string().optional(), href: z.string().optional() }),
 ])
 
+/**
+ * Réseaux du pied de page : clé de `footer.socials` (celles de Mintlify), libellé, icône de
+ * Starlight. Lu par le build et par le formulaire des réglages de la console.
+ */
+export const SOCIAL_NETWORKS = {
+  linkedin: { label: "LinkedIn", icon: "linkedin" },
+  github: { label: "GitHub", icon: "github" },
+  gitlab: { label: "GitLab", icon: "gitlab" },
+  x: { label: "X", icon: "x.com" },
+  youtube: { label: "YouTube", icon: "youtube" },
+  instagram: { label: "Instagram", icon: "instagram" },
+  facebook: { label: "Facebook", icon: "facebook" },
+  discord: { label: "Discord", icon: "discord" },
+  mastodon: { label: "Mastodon", icon: "mastodon" },
+  bluesky: { label: "Bluesky", icon: "blueSky" },
+  website: { label: "Site web", icon: "external" },
+} as const
+
+/** Ancienne écriture acceptée : `x.com` (Starlight) et `twitter` désignent X. */
+const SOCIAL_ALIASES: Record<string, keyof typeof SOCIAL_NETWORKS> = { "x.com": "x", twitter: "x" }
+
+export function socialNetwork(key: string): (typeof SOCIAL_NETWORKS)[keyof typeof SOCIAL_NETWORKS] | null {
+  const name = (SOCIAL_ALIASES[key] ?? key) as keyof typeof SOCIAL_NETWORKS
+  return SOCIAL_NETWORKS[name] ?? null
+}
+
+const REDIRECT_SOURCE = /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/
+
+/** Ancienne adresse vers la nouvelle (champ `redirects` de Mintlify), sans motif. */
+const redirect = z.object({
+  source: z.string().regex(REDIRECT_SOURCE, "adresse source attendue, commençant par « / » (ex. /guides/ancien)"),
+  destination: z
+    .string()
+    .min(1)
+    .refine(
+      (value) => /^\/(?!\/)/.test(value) || value.startsWith("https://"),
+      "destination attendue : un chemin du site (« /… ») ou une adresse https://",
+    ),
+  permanent: z.boolean().optional(),
+})
+
 export const docsConfigSchema = z.object({
   $schema: z.string().optional(),
   name: z.string().min(1).max(80),
@@ -86,6 +127,7 @@ export const docsConfigSchema = z.object({
     })
     .optional(),
   footer: z.object({ socials: z.record(z.string(), z.url()).optional() }).optional(),
+  redirects: z.array(redirect).max(500, "500 redirections au plus").optional(),
   assistant: z
     .object({
       enabled: z.boolean().default(true),

package/src/core/feedback-api.ts

@@ -0,0 +1,27 @@
+import { z } from "zod"
+
+/**
+ * Contrat de `POST /api/v1/feedback` entre le bas de chaque page (« Cette page t'a aidé ? »)
+ * et la console. Aucune donnée personnelle : la page, la réponse, un commentaire facultatif.
+ */
+export const MAX_FEEDBACK_COMMENT = 1000
+/** Code joint à un signalement « Signaler un code faux », tronqué par le site. */
+export const MAX_FEEDBACK_CODE = 2000
+
+export const feedbackRequestSchema = z
+  .object({
+    project: z.string().regex(/^[a-z0-9]{8,64}$/),
+    /** Chemin de la page, `base` compris (`/docs/guides/publier/`). */
+    page: z.string().startsWith("/").max(512),
+    helpful: z.boolean(),
+    comment: z.string().trim().max(MAX_FEEDBACK_COMMENT).optional(),
+    /** `code` : « Signaler un code faux » sur un bloc de code ; absent, l'avis porte sur la page. */
+    kind: z.enum(["page", "code"]).optional(),
+    code: z.string().max(MAX_FEEDBACK_CODE).optional(),
+  })
+  .refine((value) => value.kind !== "code" || Boolean(value.comment), {
+    message: "un signalement de code dit ce qui ne va pas",
+    path: ["comment"],
+  })
+
+export type FeedbackRequest = z.infer<typeof feedbackRequestSchema>

package/src/core/theme.ts

@@ -12,8 +12,10 @@ export type Theme = { light: AccentPalette; dark: AccentPalette }
 /** Accent violet de la DA HGDC (`--brand-accent` du kit), si le client n'en donne pas. */
 export const HGDC_ACCENT = "#7c3aed"
 
-const LIGHT_BG = "#ffffff"
-const DARK_BG = "#0f0f10"
+/** Fonds sur lesquels l'accent doit tenir 4,5:1 : la surface la plus proche de lui (élément
+ *  courant teinté, encart `muted`), un cran plus foncé ou plus clair que la page. */
+const LIGHT_BG = "#f2f2f2"
+const DARK_BG = "#2a2a2a"
 
 export function themeFor(primary: string = HGDC_ACCENT, dark?: string): Theme {
   const base = hexToOklch(primary)
@@ -48,7 +50,8 @@ export function withContrast(color: Oklch, background: string, ratio: number): s
 export function themeCss(theme: Theme): string {
   const vars = (p: AccentPalette) =>
     `--sl-color-accent-low:${p.low};--sl-color-accent:${p.accent};--sl-color-accent-high:${p.high};--hgdc-on-accent:${p.onAccent};`
-  return `:root{${vars(theme.dark)}}:root[data-theme="light"]{${vars(theme.light)}}`
+  // Clair par défaut : le sombre ne vaut que choisi (`data-hd-theme`, overrides/ThemeProvider.astro).
+  return `:root{${vars(theme.dark)}}:root:not([data-hd-theme="dark"]){${vars(theme.light)}}`
 }
 
 // --- Conversions sRGB ↔ OKLCH (Björn Ottosson) et contraste WCAG 2 ---