Den Layer gestalten und überschreiben

Ändere zuerst die Tokens. Ersetze eine Komponente nur, wenn die vorhandene Struktur das gewünschte Ergebnis nicht ausdrücken kann.

Integrierte Palette auswählen

Wähle neutrale Flächen und die Farbe für Primäraktionen unabhängig voneinander in der App-Config:

export default defineAppConfig({
  ginkoDocs: {
    theme: {
      neutral: "mauve",
      primary: "violet",
    },
  },
});

Verwende primary: 'neutral', wenn primäre Bedienelemente der Neutralpalette folgen sollen. Die Palettenauswahl ändert semantische shadcn-Tokens; Statusfarben und Markenakzente der Landing Page bleiben unabhängig.

Eigene Paletten definieren

Setze eine oder beide Paletten auf custom und definiere ihre Palettenvariablen anschließend im Theme-CSS des Consumers. Eine eigene Neutralpalette ist eine vollständige Skala:

export default defineAppConfig({
  ginkoDocs: {
    theme: { neutral: "custom", primary: "custom" },
  },
});

html[data-neutral="custom"] {
  --theme-neutral-50: oklch(0.985 0.004 250);
  --theme-neutral-100: oklch(0.965 0.008 250);
  --theme-neutral-200: oklch(0.92 0.012 250);
  --theme-neutral-300: oklch(0.87 0.018 250);
  --theme-neutral-400: oklch(0.71 0.025 250);
  --theme-neutral-500: oklch(0.55 0.03 250);
  --theme-neutral-600: oklch(0.45 0.03 250);
  --theme-neutral-700: oklch(0.37 0.028 250);
  --theme-neutral-800: oklch(0.28 0.024 250);
  --theme-neutral-900: oklch(0.21 0.02 250);
  --theme-neutral-950: oklch(0.14 0.012 250);
}

Eine eigene Primärpalette definiert Farben, Vordergrundfarben und Fokusringe ausdrücklich für beide Farbschemata:

html[data-primary="custom"] {
  --theme-primary-light: oklch(0.52 0.2 255);
  --theme-primary-light-foreground: oklch(0.985 0.004 255);
  --theme-primary-light-ring: oklch(0.62 0.17 255);
  --theme-primary-dark: oklch(0.72 0.14 255);
  --theme-primary-dark-foreground: oklch(0.18 0.025 255);
  --theme-primary-dark-ring: oklch(0.72 0.14 255);
}

Definiere die Vordergrundfarben, statt weißen Text vorauszusetzen. Helle Farben wie Gelb oder Limette benötigen einen dunklen Vordergrund. Fehlende eigene Variablen fallen einzeln auf die Zinc- und Neutral-Standards zurück.

Theme-CSS nach dem Layer laden

Importiere das CSS des Consumers aus einem Nuxt-Plugin. Der Plugin-Import wird nach den Layer-Styles eingefügt, ohne Nuxts zusammengeführtes css-Array zu ersetzen.

import "~/assets/css/theme.css";

export default defineNuxtPlugin(() => {});

Überschreibe die semantischen Variablen, die Shell und Content-Komponenten verwenden:

:root {
  --font-body: Inter, system-ui, sans-serif;
  --font-heading: Inter, system-ui, sans-serif;
  --radius: 0.5rem;

  --background: oklch(0.99 0.004 255);
  --foreground: oklch(0.19 0.025 255);
  --primary: oklch(0.51 0.19 258);
  --primary-foreground: oklch(0.99 0.004 255);
  --muted: oklch(0.96 0.01 255);
  --muted-foreground: oklch(0.48 0.03 255);
  --border: oklch(0.9 0.015 255);
  --ring: oklch(0.62 0.16 258);
}

.dark {
  --background: oklch(0.16 0.02 255);
  --foreground: oklch(0.96 0.008 255);
  --primary: oklch(0.73 0.14 258);
  --primary-foreground: oklch(0.15 0.02 255);
  --muted: oklch(0.23 0.025 255);
  --muted-foreground: oklch(0.72 0.025 255);
  --border: oklch(1 0 0 / 12%);
  --ring: oklch(0.73 0.14 258);
}

Achte in beiden Farbmodi auf lesbare Vordergrund-Hintergrund-Paare. Lade gewählte Webfonts in der App, bevor du sie in einem Token verwendest.

Eine Shell-Komponente ersetzen

Mit Nuxts Regeln für Layer-Overrides kann der Consumer eine stabile Shell-Komponente durch eine gleichnamige Komponente ersetzen. Ginko Docs bietet diese gezielten Grenzen:

• SiteHeader, SiteFooter, SiteBanner und SiteLogoMark;
• SiteInteractionLayer und DocsSidebar;
• SiteLocaleSwitcher, wenn die vollständige Sprachsteuerung eine eigene Implementierung benötigt.

Lege zum Beispiel app/components/SiteFooter.vue an, um nur den Footer zu ersetzen:

<template>
  <footer class="border-t border-border px-6 py-8 text-sm text-muted-foreground">
    <p>© {{ new Date().getFullYear() }} Acme</p>
  </footer>
</template>

Konfiguriere Pfade für helles und dunkles Logo in app.config.ts, wenn sich nur die Bildmarke ändert; dafür ist kein Komponenten-Override nötig.

Eine Seite oder ein Layout ersetzen

Lege denselben Nuxt-Pfad im Consumer an, um eine Seite oder ein Layout des Layers zu ersetzen:

app/pages/index.vue übernimmt die Startseite. app/layouts/docs.vue übernimmt die Dokumentations-Shell. Ein ersetztes Layout muss zugängliche Landmarks, das Sprungziel, responsive Navigation und einen Platz für <slot /> bewahren.

Kopiere nicht den vollständigen Layer in die Anwendung. Ein kopierter Baum erhält keine Korrekturen mehr und verschleiert, ob Konfiguration, Tokens oder Consumer-Code eine Designentscheidung besitzen.