Personalización visual

El tema Ardo está completo. Personalízalo donde compones el sitio: en app/root.tsx, con props React y archivos importados. Empieza por unos tonos:

1. Prop theme: tonos, saturación, avisos, fuentes y tokens.
2. Logotipo y favicon: archivos importados con huellas de Vite.
3. Variables CSS y Vanilla Extract: tus estilos con tokens Ardo.
4. Tailwind CSS: clases de utilidad para páginas y componentes.

Para sustituir cabecera, barra lateral o pie, consulta Diseño y navegación.

Colores, logotipo y 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 define tres tonos: color para enlaces, botones y foco, accent para acentos secundarios y código, y neutral para fondos, bordes, texto y navegación. Ardo deriva los demás colores claros y oscuros.

logo e icon reciben archivos importados. Vite añade huellas a las URL para renovar la caché al desplegar. Aquí el logotipo sirve de favicon; para una marca textual, pasa una imagen cuadrada a icon.

• Logotipos claro y oscuro: logo={{ light: logoLight, dark: logoDark }}.
• Inicio de iOS: appleTouchIcon recibe un PNG de 180×180.
• Sin icon: Ardo enlaza sus iconos de búho. Los accesos directos a /favicon.ico también reciben el búho, salvo que coloques tu propio favicon.ico en public/.

La configuración no contiene colores ni recursos, sino datos del build: título, base, versiones y referencia API.

Tonos y preajustes

color, accent y neutral aceptan un preajuste o un ángulo OKLCH de 0 a 360:

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

Preajustes: berry (predeterminado), red, orange, amber, green, teal, blue, indigo, purple, pink, slate y gray. gray carece de tono y slate es azul apagado.

Sin accent, Ardo elige un complementario de color. Sin neutral, la interfaz adopta un leve tono de marca. neutral: "gray" queda sin tinte.

Saturación

chroma ajusta la saturación. 1 conserva la paleta, valores inferiores la suavizan y 0 vuelve gris el rol. Un número se aplica a color y accent; un objeto ajusta cada rol, incluido neutral:

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

Por encima de 1, tonos como el turquesa salen de la gama sRGB. Comprueba el contraste de enlaces al aumentar color.

Colores de avisos

Los avisos conservan sus tonos para seguir reconocibles. Si chocan con el acento, ajusta status. Ardo deriva texto, fondo y borde para ambos modos:

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

status admite tip, warning, danger, info y note como preajuste o tono. Cada preajuste mantiene un contraste de texto mínimo de 4,5:1.

Fuentes

Carga una fuente como dependencia y nómbrala en fonts, por ejemplo con 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' } }} />
}

Los títulos siguen body salvo ajuste de heading. mono define la fuente del código.

Tokens de diseño

tokens ajusta los tokens para ambos modos. light y dark los reemplazan por separado, especialmente para colores:

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 señala tokens desconocidos y Ardo también los rechaza al renderizar. shadowSm, shadowMd, shadowLg y codeShadow son valores box-shadow completos. Para no mostrar sombra, usa 0 0 0 0 transparent: none rompe sombras combinadas. brandGradient admite un color simple.

La documentación usa así la paleta del búho: oliva, terracota, blanco cálido y mostaza para avisos:

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

Raíz propia

ArdoRoot renderiza el tema automáticamente. Una raíz compuesta con ArdoProvider y ArdoLayout renderiza <ArdoTheme> con las mismas props, pasa logo a ArdoHeader y el favicon al 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

Cada token es también una variable CSS, como --ardo-hue-brand o --ardo-color-bg. Tus estilos sin capa prevalecen sobre la capa ardo. Un color en :root también se aplica en oscuro; limita los colores a su modo:

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

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

Las variables de tono, saturación, diseño y tipografía funcionan en :root. Valores habituales y predeterminados:

: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

La interfaz usa Vanilla Extract. Los tokens tipados de ardo/theme aportan autocompletado y errores de compilación para referencias incorrectas.

La CLI incluye el plugin: .css.ts funciona sin ajustes Vite adicionales. Instala antes la API de estilos en el paquete:

pnpm add @vanilla-extract/css

Usar los tokens

Crea un archivo .css.ts en el proyecto:

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

Hojas de estilo y cascada

Ardo carga ardo/ui/styles.css después de los imports CSS de la raíz. Contiene interfaz, reset y tema en la capa ardo. Los imports de componentes o uno explícito no añaden una segunda copia.

El CSS normal sin capa tiene prioridad sin importar el orden de carga. Puedes sobrescribir .ardo-footer directamente. Si usas capas, declara su orden en la primera hoja raíz, por ejemplo @layer ardo, app;.

Selectores estables

Las clases generadas son internas. Usa las clases estables para ajustes concretos:

Estas clases son puntos de personalización, no otra API. Prioriza tokens y props y usa después los selectores para ajustes propios.

Limita los cambios al wrapper del sitio. Puedes ocultar .ardo-sidebar-tabs si tu navegación mantiene todas las secciones accesibles en escritorio y móvil. Pon las variables necesarias para portales del body, como la búsqueda, en el className de ArdoRootLayout.

Categorías de tokens

vars incluye estas categorías:

• vars.color — Colores, superficies, texto, bordes, sombras y colores semánticos.
• vars.hue — Tonos de marca, acento, neutros y avisos.
• vars.chroma — Factores de saturación de marca, acento y neutros.
• vars.layout — Anchuras de navegación, índice, contenido y página, altura de cabecera.
• vars.transition — Transiciones rápidas, normales y lentas.
• vars.font — Fuentes de texto, títulos y código, tamaño base e interlineado.
• vars.fontSize — Escala tipográfica de xs a 4xl.
• vars.space — Escala de espacios de xs a 4xl.
• vars.radius — Radios sm, base, lg, xl y full.

Tailwind CSS

Tailwind CSS v4 es opcional para tus páginas, ejemplos y MDX. Conserva tu solución de estilos al adoptar Ardo.

Ardo usa Vanilla Extract para su interfaz. Tailwind sirve a tus contenidos: estilos en React sin otro sistema de temas.

Instalación

Instala tailwindcss y @tailwindcss/vite como dependencias de desarrollo y configura:

1. @tailwindcss/vite en las plugins de vite.config.ts
2. tailwindcss como dependencia de desarrollo
3. app/app.css con las capas de tema y utilidades 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 *));

Importa el archivo en app/root.tsx. Ardo carga su hoja después, así que se aplica este orden. Pon ardo antes de components y utilities para priorizar las utilidades.

La variante dark: de Tailwind sigue normalmente al sistema. La línea @custom-variant hace que siga al selector Ardo para que las clases dark: cambien con el sitio.

Ejemplos

Aviso en MDX

Funciona directamente en cualquier .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 personalizado

Crea una cabecera de portada sin escribir 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>
  )
}

¿Por qué sin Preflight?

Ardo aporta estilos base de tipografía, títulos, enlaces, listas y código. El reset Preflight entraría en conflicto con esa apariencia.

Si controlas todos los estilos de un sitio muy personalizado, activa Preflight en 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);

Ardo define explícitamente marcadores, bordes de tablas, código y espacios. El contenido sigue legible con un reset del host. ardo va después de base, por lo que Preflight no lo anula, y antes de utilities, que conserva la prioridad.