Theme

The theme field in docs.json controls the colors and dark mode of your rendered site.

Presets

Four presets ship with Bloques. Set one with the preset field, or omit it to get default.

• default: neutral grays.
• ocean: cool blues.
• emerald: fresh greens.
• rose: warm pinks.

{
  "theme": {
    "preset": "ocean"
  }
}

Each preset defines a full light and dark palette. The dark palette is paired automatically: set the preset once and both modes work.

Primary color override

Replace a preset's primary (and focus ring) color with primaryOverride. A plain string sets the light-mode color, and Bloques derives the dark-mode shade from it.

{
  "theme": {
    "primaryOverride": "oklch(0.62 0.19 145)"
  }
}

primaryOverride accepts any valid CSS color: hex (#10b981), rgb(), hsl(), oklch(), or a named color. Bloques converts the value to oklch() and adjusts its lightness in each mode until the color reaches a contrast ratio of at least 3:1 against that mode's background. Your hue survives the adjustment, and Bloques picks the label color on primary buttons for you.

Pin a color per mode

One color rarely reads well in both modes. A near-black navy only lightens into gray, so give each mode its own value:

{
  "theme": {
    "primaryOverride": {
      "light": "#0f172a",
      "dark": "#7aa2f7"
    }
  }
}

Bloques renders a dark value exactly as written, with no contrast adjustment. A light value goes through the same conversion as the shorthand. Set light alone and dark mode still derives from it. Set dark alone and light mode keeps the preset's primary.

Dark mode

Every preset ships with a paired dark palette, so dark mode works out of the box. The site renders a theme switch in the header with three options: Light, Dark, and System. The default is System, which follows the visitor's operating system preference.