Theming

Ardos Standardtheme ist vollständig. Du passt es dort an, wo du die Website komponierst: in app/root.tsx mit React-Props und importierten Dateien. Beginne mit wenigen Farben und verfeinere nach Bedarf:

1. theme-Prop: Farben, Sättigung, Callouts, Schriften und alle Designtokens.
2. Logo und Favicon: importierte Dateien mit Vite-Fingerprints.
3. CSS-Variablen und Vanilla Extract: eigene Styles mit Ardos Tokens.
4. Tailwind CSS: Utility-Klassen für eigene Seiten und Komponenten.

Eigene React-Komponenten für Kopfzeile, Seitenleiste und Fußzeile behandelt Layout und Navigation.

Farben, Logo und 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 setzt drei Farbtöne: color für Links, Tasten und Fokusringe, accent für weitere Highlights und Codeflächen und neutral für Hintergründe, Rahmen, Text, Kopfzeile und Seitenleiste. Daraus leitet Ardo alle übrigen Farben für Hell und Dunkel ab.

logo und icon nehmen importierte Dateien. Vite versieht URLs mit Fingerprints, damit neue Logos nach dem Deployment statt aus altem Cache erscheinen. Hier dient das Logo auch als Favicon. Für Wortmarken nutze ein eigenes quadratisches icon.

• Helles und dunkles Logo: logo={{ light: logoLight, dark: logoDark }}.
• iOS-Startbildschirme: appleTouchIcon nimmt ein 180×180-PNG.
• Ohne icon: Ardo verlinkt seine Eulenicons. Direkte Zugriffe auf /favicon.ico liefern ebenfalls die Eule, außer du hinterlegst eine eigene favicon.ico in public/.

Die Konfigurationsdatei enthält weder Farben noch Assets. Sie regelt Build-Daten wie Titel, Basispfad, Versionen und API-Referenz.

Farbtöne und Voreinstellungen

color, accent und neutral akzeptieren Voreinstellungen oder OKLCH-Winkel von 0 bis 360:

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

Voreinstellungen: berry (Standard), red, orange, amber, green, teal, blue, indigo, purple, pink, slate und gray. gray ist ohne Farbton, slate ein gedämpftes Blau.

Ohne accent wählt Ardo eine Komplementärfarbe zu color. Ohne neutral erhält die Oberfläche eine schwache Markenfärbung. neutral: "gray" bleibt völlig neutral.

Sättigung

chroma steuert die Sättigung. 1 erhält die Palette, kleinere Werte beruhigen sie, 0 macht eine Rolle grau. Eine Zahl gilt für color und accent; das Objekt setzt jede Rolle einschließlich neutral:

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

Über 1 können Farben wie Türkis den sRGB-Farbraum verlassen. Prüfe deshalb den Linkkontrast, wenn du color erhöhst.

Callout-Farben

Callouts behalten eigene Farben, damit Warnungen bei jeder Marke erkennbar bleiben. Bei Konflikten mit dem Akzent setzt status neue Farbtöne. Ardo leitet Text, Fläche und Rahmen für beide Modi ab:

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

status akzeptiert tip, warning, danger (Vorsicht), info (wichtig) und note als Voreinstellung oder Farbton. Alle Voreinstellungen halten mindestens 4,5:1 Textkontrast.

Schriften

Lade eine Schrift als Abhängigkeit und setze ihren Namen in fonts, etwa mit 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' } }} />
}

Überschriften folgen body, sofern heading fehlt. mono bestimmt die Schrift für Codeblöcke und Inline-Code.

Designtokens

tokens setzt Ardos Designtokens für beide Modi. light und dark überschreiben sie einzeln; dort gehören die meisten Farben hin:

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 meldet unbekannte Tokens; Ardo lehnt sie auch beim Rendern ab. shadowSm, shadowMd, shadowLg und codeShadow sind vollständige box-shadow-Werte. Für keinen Schatten nutze 0 0 0 0 transparent; none bricht zusammengesetzte Schatten. brandGradient akzeptiert auch eine einfache Farbe.

Ardos Dokumentation nutzt damit die Eulenpalette: Oliv, Terrakotta, leicht warmes Weiß und Senfgelb für Warnungen:

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)" } },
}

Eigene Root-Komponente

ArdoRoot rendert das Theme automatisch. Eigene Hüllen aus etwa ArdoProvider und ArdoLayout rendern <ArdoTheme> mit denselben Props, setzen logo auf ArdoHeader und übergeben das Favicon an die HTML-Hülle 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 />
    </>
  )
}

CSS-Variablen

Jeder Token ist auch eine CSS-Variable wie --ardo-hue-brand oder --ardo-color-bg. Eigene Styles überschreiben Ardos ardo-Kaskadenebene ohne zusätzliche Spezifität. Farben auf :root gelten deshalb auch dunkel; grenze Farben je Modus ein:

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

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

Variablen für Farbton, Sättigung, Layout und Typografie sind auf :root sicher. Häufige Werte und ihre Standards:

: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;
}

Vanilla-Extract-Tokens

Ardos Oberfläche nutzt Vanilla Extract. Alle Tokens lassen sich typsicher aus ardo/theme importieren – mit Autovervollständigung und Compilerfehlern bei falschen Verweisen.

Die CLI enthält das Vanilla-Extract-Plugin. .css.ts funktioniert ohne weitere Vite-Konfiguration. Installiere zuvor die Styling-API im Dokumentationspaket:

pnpm add @vanilla-extract/css

Tokens in eigenen Stilen nutzen

Erstelle eine .css.ts-Datei im Projekt:

// 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",
})

Stylesheet-Zuständigkeit und Kaskade

Ardo lädt ardo/ui/styles.css nach den CSS-Importen des Root-Moduls. Es enthält Oberfläche, Reset und Theme im Layer ardo. Komponentenimporte oder ein zusätzlicher eigener Import laden keine zweite Kopie.

Normales CSS ohne Layer hat unabhängig von der Ladereihenfolge Vorrang. Du kannst etwa .ardo-footer direkt überschreiben. Bei eigenen Layern lege deren Reihenfolge im ersten Root-Stylesheet fest, zum Beispiel @layer ardo, app;.

Stabile CSS-Anpassungspunkte

Generierte Vanilla-Extract-Klassennamen sind Implementierungsdetails. Nutze für gezielte Anpassungen die stabilen Klassen:

Diese Klassen sind Anpassungspunkte, keine eigene Styling-API. Nutze zuerst Tokens und Props und anschließend diese Selektoren für projektspezifische Änderungen.

Begrenze Anpassungen in einem bestehenden Designsystem auf den Website-Wrapper. Hat die Website bereits eine Abschnittsnavigation, darf sie .ardo-sidebar-tabs ausblenden, solange alle Bereiche auf Desktop und Mobilgeräten erreichbar bleiben. Theme-Variablen für Body-Portale wie die Suche gehören auf className von ArdoRootLayout.

Token-Kategorien

vars enthält Tokens für:

• vars.color — Farben, Flächen, Text, Rahmen, Schatten und semantische Farben.
• vars.hue — Marken-, Akzent-, Neutral- und Callout-Farbtöne.
• vars.chroma — Sättigungsfaktoren für Marke, Akzent und neutrale Farben.
• vars.layout — Seitenleisten-, Inhaltsverzeichnis-, Inhalts- und Seitenbreite sowie Kopfzeilenhöhe.
• vars.transition — Schnelle, normale und langsame Übergänge.
• vars.font — Text-, Überschriften- und Codeschriften, Grundgröße und Zeilenhöhe.
• vars.fontSize — Typografieskala von xs bis 4xl.
• vars.space — Abstandsskala von xs bis 4xl.
• vars.radius — Radien sm, base, lg, xl und full.

Tailwind CSS

Tailwind CSS v4 ist optional für eigene Landingpages, Beispiele, Komponentendemos und MDX. Behalte beim Ardo-Einstieg deine bestehende Styling-Lösung bei.

Ardo gestaltet seine Oberfläche mit Vanilla Extract. Tailwind ist für deine Inhalte gedacht: Styling direkt in React, ohne ein zweites Themesystem.

Einrichtung

Installiere tailwindcss und @tailwindcss/vite als Entwicklungsabhängigkeiten und konfiguriere:

1. @tailwindcss/vite in den plugins von vite.config.ts
2. tailwindcss als Entwicklungsabhängigkeit
3. app/app.css mit Tailwinds Theme- und Utility-Layern

@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 *));

Importiere die Datei in app/root.tsx. Da Ardo sein Stylesheet danach lädt, gilt die hier deklarierte Layerreihenfolge: Nenne ardo vor components und utilities, damit Utility-Klassen gegen die Inhaltsstile gewinnen.

Tailwinds Variante dark: folgt standardmäßig dem Betriebssystem. Mit der Zeile @custom-variant folgt sie stattdessen Ardos Theme-Schalter, sodass dark:-Klassen gemeinsam mit der Website wechseln.

Beispiele

Hinweisbox in MDX

Das funktioniert direkt in jeder .mdx-Datei:

<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>

Eigener Hero-Bereich

Erstelle einen Landingpage-Kopf ohne eigene CSS-Zeilen:

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>
  )
}

Warum ohne Preflight?

Ardo bringt Basisstile für Typografie, Überschriften, Links, Listen und Codeblöcke mit. Tailwinds Preflight-Reset würde damit kollidieren und das Standardbild verändern.

Wenn du alle Stile einer stark angepassten Website selbst kontrollierst, kannst du Preflight in app/app.css aktivieren:

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

Ardos Inhaltsstile setzen Listenzeichen, Tabellenrahmen, Code und Abstände ausdrücklich. Markdown bleibt auch unter einem Host-Reset lesbar. ardo liegt nach base, sodass Preflight diese Stile nicht aufhebt, und vor utilities, damit angewendete Utility-Klassen gewinnen.