Thèmes

Le thème Ardo est complet. Personnalisez-le là où vous composez le site : dans app/root.tsx, avec des props React et des fichiers importés. Commencez par quelques teintes :

1. Prop theme: teintes, saturation, encadrés, polices et tokens.
2. Logo et favicon : fichiers importés avec fingerprints Vite.
3. Variables CSS et Vanilla Extract : vos styles avec les tokens Ardo.
4. Tailwind CSS : classes utilitaires pour pages et composants.

Pour remplacer l’en-tête, la barre latérale ou le pied de page, consultez Mise en page et navigation.

Couleurs, logo et favicon

app/root.tsx:

import { ArdoRoot } from "ardo/ui"

import logo from "./assets/logo.svg"

export default function Root() {
  return (
    <ArdoRoot theme={{ color: "blue", accent: "teal", neutral: "slate" }} logo={logo} icon={logo} />
  )
}

theme définit trois teintes : color pour liens, boutons et focus, accent pour accents secondaires et code, neutral pour fonds, bordures, texte et navigation. Ardo en déduit les autres couleurs claires et sombres.

logo et icon prennent des fichiers importés. Vite ajoute un fingerprint aux URL pour renouveler le cache au déploiement. Ici, le logo sert de favicon ; pour un logo textuel, passez une marque carrée à icon.

• Logos clair et sombre : logo={{ light: logoLight, dark: logoDark }}.
• Accueil iOS : appleTouchIcon prend un PNG 180×180.
• Sans icon : Ardo lie ses icônes de chouette. Les accès directs à /favicon.ico reçoivent aussi la chouette, sauf si vous placez votre propre favicon.ico dans public/.

La configuration ne contient ni couleurs ni ressources, mais les données du build : titre, base, versions et référence API.

Teintes et préréglages

color, accent et neutral acceptent un préréglage ou un angle OKLCH de 0 à 360:

<ArdoRoot theme={{ color: 240, accent: 170, neutral: 260 }} />

Préréglages : berry (défaut), red, orange, amber, green, teal, blue, indigo, purple, pink, slate, gray. gray est sans teinte et slate est un bleu atténué.

Sans accent, Ardo choisit une complémentaire de color. Sans neutral, l’interface prend une légère teinte de marque. neutral: "gray" reste sans coloration.

Saturation

chroma règle la saturation. 1 conserve la palette, une valeur inférieure l’atténue et 0 rend le rôle gris. Un nombre s’applique à color et accent; un objet règle chaque rôle, dont neutral:

<ArdoRoot
  theme={{
    color: "green",
    accent: "orange",
    neutral: 95,
    chroma: { color: 0.4, accent: 2, neutral: 1.6 },
  }}
/>

Au-dessus de 1, certaines teintes comme le turquoise sortent du gamut sRGB. Vérifiez le contraste des liens en augmentant color.

Couleurs des encadrés

Les encadrés gardent leurs teintes pour rester reconnaissables. En cas de conflit avec l’accent, réglez status. Ardo déduit texte, fond et bordure pour les deux modes :

<ArdoRoot theme={{ accent: 38, status: { warning: 72 } }} />

status accepte tip, warning, danger, info et note, comme préréglage ou teinte. Chaque préréglage maintient un contraste textuel d’au moins 4,5:1.

Polices

Chargez une police comme dépendance et nommez-la dans fonts, par exemple avec Fontsource:

pnpm add @fontsource-variable/inter

import "@fontsource-variable/inter"
import { ArdoRoot } from "ardo/ui"

export default function Root() {
  return <ArdoRoot theme={{ fonts: { body: '"Inter Variable", system-ui, sans-serif' } }} />
}

Les titres suivent body sauf réglage heading. mono définit la police du code.

Tokens de design

tokens règle les tokens pour les deux modes. light et dark les remplacent séparément, notamment pour les couleurs :

import { ArdoRoot, type ArdoThemeProps } from "ardo/ui"

const theme: ArdoThemeProps = {
  tokens: {
    radius: { sm: "0px", base: "0px", lg: "0px" },
    color: {
      shadowSm: "0 0 0 0 transparent",
      shadowMd: "0 0 0 0 transparent",
      shadowLg: "0 0 0 0 transparent",
    },
  },
  light: { color: { bg: "#fbfbf8", text: "#101010", brand: "#0038ff", brandGradient: "#0038ff" } },
  dark: { color: { bg: "#101010", text: "#fbfbf8" } },
}

export default function Root() {
  return <ArdoRoot theme={theme} />
}

TypeScript signale les tokens inconnus, qu’Ardo rejette aussi au rendu. shadowSm, shadowMd, shadowLg et codeShadow sont des valeurs box-shadow complètes. Pour aucun ombrage, utilisez 0 0 0 0 transparent: none casse les ombres combinées. brandGradient accepte une couleur simple.

La documentation reprend ainsi la palette de la chouette : olive, terre cuite, blanc légèrement chaud et moutarde pour les avertissements :

const theme: ArdoThemeProps = {
  color: 123,
  accent: 38,
  neutral: 95,
  chroma: { color: 0.4, accent: 2, neutral: 1.6 },
  status: { warning: 72 },
  light: { color: { codeBg: "oklch(0.973 0.006 95)", codeBorder: "oklch(0.9 0.009 95)" } },
  dark: { color: { codeBg: "oklch(0.205 0.01 95)", codeBorder: "oklch(0.31 0.014 95)" } },
}

Racine personnalisée

ArdoRoot rend le thème automatiquement. Une racine composée avec ArdoProvider et ArdoLayout rend <ArdoTheme> avec les mêmes props, passe logo à ArdoHeader et le favicon au shell ArdoRootLayout:

import type { ReactNode } from "ardo/react"
import { ArdoRootLayout, ArdoTheme } from "ardo/ui"

import icon from "./assets/icon.svg"
import { SiteShell } from "./site-shell"

export function Layout({ children }: { children: ReactNode }) {
  return <ArdoRootLayout icon={icon}>{children}</ArdoRootLayout>
}

export default function Root() {
  return (
    <>
      <ArdoTheme color="blue" neutral="slate" />
      <SiteShell />
    </>
  )
}

Variables CSS

Chaque token est aussi une variable CSS, comme --ardo-hue-brand ou --ardo-color-bg. Vos styles hors couche priment sur la couche ardo. Une couleur sur :root s’applique donc aussi en sombre ; limitez les couleurs à leur mode :

:root:not(.dark) {
  --ardo-color-bg: oklch(0.99 0.004 95);
}

.dark {
  --ardo-color-bg: oklch(0.17 0.006 95);
}

Les variables de teinte, saturation, mise en page et typographie conviennent à :root. Valeurs courantes et défauts :

:root {
  /* Hues */
  --ardo-hue-brand: 356;
  --ardo-hue-accent: 230;
  --ardo-hue-neutral: 356;
  --ardo-hue-tip: 155;
  --ardo-hue-warning: 45;
  --ardo-hue-danger: 25;
  --ardo-hue-info: 220;
  --ardo-hue-note: 270;

  /* Chroma multipliers: 1 is the default saturation, 0 is gray */
  --ardo-chroma-brand: 1;
  --ardo-chroma-accent: 1;
  --ardo-chroma-neutral: 1;

  /* Layout */
  --ardo-layout-sidebarWidth: 20rem;
  --ardo-layout-tocWidth: 15rem;
  --ardo-layout-contentMaxWidth: 36em; /* em: the measure follows each element's font size */
  --ardo-layout-pageMaxWidth: 69rem; /* header, hero, features, footer on bare pages */
  --ardo-layout-headerHeight: 3.5rem;

  /* Typography */
  --ardo-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", ...;
  --ardo-font-familyHeading: var(--ardo-font-family);
  --ardo-font-mono: ui-monospace, SFMono-Regular, ...;
  --ardo-font-lineHeight: 1.65;

  /* Border radius */
  --ardo-radius-sm: 0.25rem;
  --ardo-radius-base: 0.5rem;
  --ardo-radius-lg: 0.75rem;
}

Tokens Vanilla Extract

L’interface utilise Vanilla Extract. Les tokens typés d’ardo/theme fournissent autocomplétion et erreurs de compilation en cas de référence incorrecte.

La CLI inclut le plugin : les .css.ts fonctionnent sans réglage Vite supplémentaire. Installez d’abord l’API de styles dans le paquet :

pnpm add @vanilla-extract/css

Utiliser les tokens

Créez un fichier .css.ts dans le projet :

// styles/custom.css.ts
import { style, globalStyle } from "@vanilla-extract/css"
import { vars } from "ardo/theme"

export const highlight = style({
  background: vars.color.brandSubtle,
  borderLeft: `3px solid ${vars.color.brand}`,
  padding: "16px",
  borderRadius: vars.radius.base,
})

// Override Ardo's default styles
globalStyle(".ardo-content a", {
  color: vars.color.brand,
  textDecoration: "underline",
})

Stylesheets et cascade

Ardo charge ardo/ui/styles.css après les imports CSS de la racine. Il contient interface, reset et thème dans la couche ardo. Les imports de composants ou un import explicite n’ajoutent aucune seconde copie.

Le CSS normal sans couche prime, quel que soit l’ordre de chargement. Vous pouvez redéfinir .ardo-footer directement. Avec vos propres couches, déclarez leur ordre dans le premier stylesheet racine, par exemple @layer ardo, app;.

Sélecteurs stables

Les classes générées sont internes. Utilisez les classes stables pour des ajustements ciblés :

Ces classes sont des points de personnalisation, pas une autre API. Préférez tokens et props, puis ces sélecteurs pour les ajustements propres au projet.

Limitez les remplacements au wrapper du site. Vous pouvez masquer .ardo-sidebar-tabs si votre navigation garde toutes les sections accessibles sur ordinateur et mobile. Placez les variables nécessaires aux portails du body, comme la recherche, sur le className d’ArdoRootLayout.

Catégories de tokens

vars fournit les catégories suivantes :

• vars.color — Couleurs, surfaces, texte, bordures, ombres et couleurs sémantiques.
• vars.hue — Teintes de marque, accent, neutre et encadrés.
• vars.chroma — Facteurs de saturation de marque, accent et neutre.
• vars.layout — Largeurs de navigation, sommaire, contenu et page, hauteur d’en-tête.
• vars.transition — Transitions rapides, normales et lentes.
• vars.font — Polices de texte, titres et code, taille de base et interligne.
• vars.fontSize — Échelle typographique de xs à 4xl.
• vars.space — Échelle d’espacement de xs à 4xl.
• vars.radius — Rayons sm, base, lg, xl, full.

Tailwind CSS

Tailwind CSS v4 est optionnel pour vos pages, exemples et contenus MDX. Conservez votre solution de styles existante en adoptant Ardo.

Ardo utilise Vanilla Extract pour son interface. Tailwind sert à vos contenus : des styles dans React sans second système de thèmes.

Installation

Installez tailwindcss et @tailwindcss/vite en développement, puis configurez :

1. @tailwindcss/vite dans les plugins de vite.config.ts
2. tailwindcss comme dépendance de développement
3. app/app.css avec les couches de thème et d’utilitaires de Tailwind

@layer theme, base, ardo, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);

/* Follow Ardo's theme toggle, which sets the .dark class on <html>. */
@custom-variant dark (&:where(.dark, .dark *));

Importez le fichier dans app/root.tsx. Ardo charge son stylesheet ensuite ; l’ordre déclaré ici s’applique. Placez ardo avant components et utilities pour donner priorité aux utilitaires.

La variante dark: de Tailwind suit normalement le système. La ligne @custom-variant la fait suivre le sélecteur Ardo afin que les classes dark: changent avec le site.

Exemples

Encadré dans MDX

Ce contenu fonctionne directement dans tout .mdx:

<div
  className="flex gap-3 rounded-lg border border-blue-200 bg-blue-50 p-4 dark:border-blue-800 dark:bg-blue-950"
>
  <span className="text-xl">💡</span>
  <div>
    <p className="font-semibold text-blue-900 dark:text-blue-100">Good to know</p>
    <p className="text-sm text-blue-700 dark:text-blue-300">
      Tailwind classes work in MDX files, TSX components, and anywhere else in your Ardo project.
    </p>
  </div>
</div>

Hero personnalisé

Créez un en-tête d’accueil sans écrire de CSS :

import { ArdoLink } from "ardo/ui"

export default function Home() {
  return (
    <div className="flex min-h-[60vh] flex-col items-center justify-center gap-6 text-center">
      <h1 className="text-5xl font-bold tracking-tight text-gray-900 dark:text-white">
        My Project
      </h1>
      <p className="max-w-2xl text-lg text-gray-600 dark:text-gray-400">
        A short description that tells visitors exactly what this is and why they should care.
      </p>
      <div className="flex gap-3">
        <ArdoLink
          to="/guide/getting-started"
          className="rounded-lg bg-blue-600 px-5 py-2.5 text-sm font-medium text-white hover:bg-blue-700"
        >
          Get Started
        </ArdoLink>
        <a
          href="https://github.com/your/repo"
          className="rounded-lg border border-gray-300 px-5 py-2.5 text-sm font-medium text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:text-gray-300 dark:hover:bg-gray-800"
        >
          GitHub
        </a>
      </div>
    </div>
  )
}

Pourquoi sans Preflight ?

Ardo fournit les styles de base du contenu : typographie, titres, liens, listes et code. Le reset Preflight entrerait en conflit avec cette apparence.

Si vous contrôlez tous les styles d’un site très personnalisé, activez Preflight dans app/app.css:

@layer theme, base, ardo, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

Les styles Ardo définissent explicitement marqueurs, bordures de tableaux, code et espaces. Le contenu reste lisible avec un reset hôte. ardo suit base, donc Preflight ne l’annule pas, et précède utilities, qui garde priorité.