---
title: Configuration
description: The fields, defaults, and constraints accepted by brandtree.config.ts.
---

`brandtree.config.ts` is the single source of structured brand data and site
settings. Use `defineConfig` from `brandtree` for editor completion; the CLI
validates values when it loads the project. Unknown fields are rejected.

For a guided setup, start with [Brand configuration](/brand-configuration).
This page follows the config object's structure so you can find a field quickly.

## Define and validate your config

This is the shape of a config file, **not a complete runnable configuration**.
Keep the required brand sections from the [Quickstart](/quickstart) starter.

```ts title="brandtree.config.ts — structure only"
import { defineConfig } from "brandtree";

export default defineConfig({
  brand: {
    // Required: meta, colors, theme, typography, logo, and contact.
  },
  navigation: { numbering: true },
});
```

The loader recognizes `brandtree.config.ts`, `.mts`, `.js`, `.mjs`, and `.cjs`,
in that order. Keep one config file. A config-free project does not currently
provide a complete brand automatically.

| Prop | Type | Default | Description |
| - | - | - | - |
| `brand` | `BrandConfig` | - | Structured identity, colors, themes, typography, logos, contacts, and optional downloads and translations. |
| `fonts?` | `FontConfig[]` | `Inter (Google)` | Font loading declarations. An explicit array replaces the default; [] disables font downloads. |
| `basePath?` | `string` | `""` | Route mount point such as /guidelines, normalized to an empty string or /segment. Does not add a sidebar group. |
| `navigation?` | `{ numbering?: boolean }` | `{ numbering: false }` | Whether sidebar sections display numbers. See Navigation. |
| `i18n?` | `I18nConfig` | - | Opt-in locales, content parser, URL prefix policy, and fallback. See Localization. |
| `seo?` | `{ og?: OgConfig }` | `{ og: { enabled: true } }` | Generated social-card settings. See Social cards and SEO. |

> **Use Brandtree's config surface**
>
> There is no top-level `title`, `content`, `deployment`, or arbitrary Astro
> configuration block. See [Navigation](/navigation),
> [Localization](/localization), and [Build and deployment](/publishing) for the
> supported site workflows.

## Brand fields

| Prop | Type | Default | Description |
| - | - | - | - |
| `meta` | `BrandMeta` | - | Identity and document metadata. |
| `colors` | `{ palette: PaletteFamily[]; swatches: Swatch[] }` | - | Authored color values and approved brand swatches. |
| `theme` | `{ default: 'light' \| 'dark' \| 'system'; light: Scheme; dark: Scheme }` | - | Complete semantic color roles for both themes. |
| `typography` | `BrandTypography` | - | Font stacks, family descriptions, weights, and type scale. |
| `logo` | `BrandLogo` | - | Artwork variants and usage specifications. |
| `contact` | `BrandContact` | - | Optional public contact fields. An empty object is allowed. |
| `downloads?` | `BrandDownload[]` | - | Shared downloadable resources and their display metadata. |
| `localeOverrides?` | `Record<string, BrandLocaleOverride>` | - | Reader-facing copy and typography stacks by configured locale code. Requires root i18n. |

## Brand metadata

All paths below are relative to `brand.meta`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | Public brand name. |
| `legalName?` | `string` | - | Registered legal name. |
| `tagline?` | `string` | - | Short brand tagline. |
| `documentTitle` | `string` | - | Guidelines document label. |
| `version` | `string` | - | Brand-document version, independent of the package version. |
| `year` | `number` | - | Document year. |
| `url` | `string` | - | Production origin used by the generated site and absolute metadata URLs. |
| `description` | `string` | - | Site description. |

See [Brand identity](/brand-identity) for an example and the distinction between
structured identity and editorial brand stories.

## Color families and swatches

`brand.colors.palette` contains families with required `id`, `name`, and
`shades`. Each `shades` object must contain all eleven stops: `50`, `100`, `200`,
`300`, `400`, `500`, `600`, `700`, `800`, `900`, and `950`.

A shade uses `{ space: "hex", value: "#64748b" }` or
`{ space: "oklch", l: 0.55, c: 0.12, h: 250, alpha: 1 }`. For OKLCH, `alpha` is
optional, lightness uses the 0–1 scale, and hue is in degrees.

Other color fields take references such as `slate-700`, `black`, or `white`.
`black` and `white` are built in. Raw hex strings are not valid references.

| Prop | Type | Default | Description |
| - | - | - | - |
| `id` | `string` | - | Swatch identifier, unique within swatches. |
| `name` | `string` | - | Visible color name. |
| `color` | `ColorReference` | - | Palette reference or black/white. |
| `cmyk?` | `[number, number, number, number]` | - | Authored print specification. |
| `pantone?` | `string` | - | Print reference label. |
| `usage?` | `string` | - | Short usage guidance. |
| `category?` | `"primary" \| "secondary"` | - | Color category. |
| `span?` | `1 \| 2` | - | Horizontal swatch span. |
| `rows?` | `1 \| 2` | - | Vertical swatch span. |
| `on?` | `ColorReference` | - | Explicit swatch foreground. |

The table describes an entry in `brand.colors.swatches`. See [Colors](/colors)
for a complete palette example.

## Light and dark themes

`brand.theme.default` is `"light"`, `"dark"`, or `"system"`. Both `light` and
`dark` require all of the following roles, each a color reference:

| Group               | Required roles                                                                                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page                | `background`, `foreground`                                                                                                                               |
| Cards               | `card`, `cardForeground`                                                                                                                                 |
| Popovers            | `popover`, `popoverForeground`                                                                                                                           |
| Main actions        | `primary`, `primaryForeground`                                                                                                                           |
| Supporting surfaces | `secondary`, `secondaryForeground`, `muted`, `mutedForeground`                                                                                           |
| Accent              | `accent`, `accentForeground`                                                                                                                             |
| Destructive actions | `destructive`, `destructiveForeground`                                                                                                                   |
| Controls            | `border`, `input`, `ring`                                                                                                                                |
| Charts              | `chart1`, `chart2`, `chart3`, `chart4`, `chart5`                                                                                                         |
| Sidebar             | `sidebar`, `sidebarForeground`, `sidebarPrimary`, `sidebarPrimaryForeground`, `sidebarAccent`, `sidebarAccentForeground`, `sidebarBorder`, `sidebarRing` |

See [Themes](/themes) for how roles map to CSS variables and how to review both
schemes without relying on JavaScript.

## Typography specifications

`brand.typography` requires the CSS font-family stacks `display`, `text`, and
`mono`, plus `families`, `weights`, and `scale` arrays.

- Family entries require `id` (`"display"`, `"text"`, or `"mono"`) and `name`.
  Optional fields: `foundry`, `url`, `note`.
- Weight entries require `name` and numeric `weight`. Optional: `italic`.
  Weight numbers must be unique, including entries marked italic.
- Scale entries follow the table below.

| Prop | Type | Default | Description |
| - | - | - | - |
| `id` | `string` | - | Stable style identifier, unique within scale. |
| `name` | `string` | - | Visible style name. |
| `size` | `string` | - | CSS font size, including responsive clamp expressions. |
| `lineHeight` | `string` | - | CSS line-height value. |
| `tracking` | `string` | - | CSS letter-spacing value. |
| `font?` | `"display" \| "text"` | - | Typography role. |
| `weight?` | `number` | - | Font weight. |
| `role?` | `string` | - | Short usage explanation. |
| `sample?` | `string` | - | Specimen text. |
| `transform?` | `"none" \| "uppercase" \| "lowercase" \| "capitalize"` | - | Text transformation. |
| `print?` | `{ size: string; leading: string; tracking: string }` | - | Print specification. All three fields are required when present; this does not generate a PDF. |

See [Typography](/typography) for a complete example.

## Load fonts

Root-level `fonts` is an array; it is separate from `brand.typography`.
When omitted, it declares Inter from Google with `"100 900"` weights, normal and
italic styles, and system fallbacks. Supplying an array replaces that default.

| Prop | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | - | Nonempty provider family name. |
| `cssVariable` | `string` | - | Unique CSS variable matching -- followed by a letter or underscore, then letters, numbers, underscores, or hyphens. |
| `provider` | `"google" \| "fontsource" \| "bunny" \| "fontshare" \| "adobe" \| "local"` | - | Serializable Astro font-provider declaration. |
| `id?` | `string` | - | Required nonempty Adobe project ID when provider is adobe; unsupported for other providers. |
| `options?` | `{ variants: FontVariant[] }` | - | Required for local fonts. Nonempty variants; each needs a nonempty src array relative to the client project root. |
| `weights?` | `(number \| string)[]` | - | Nonempty list; variable ranges use a string such as 100 900. |
| `styles?` | `("normal" \| "italic" \| "oblique")[]` | - | Nonempty style list. |
| `subsets?` | `string[]` | - | Nonempty provider subset list. |
| `formats?` | `("woff2" \| "woff" \| "ttf" \| "otf" \| "eot")[]` | - | Nonempty format list. |
| `fallbacks?` | `string[]` | - | CSS fallback family names. |
| `optimizedFallbacks?` | `boolean` | - | Whether to optimize fallback metrics. |
| `display?` | `"auto" \| "block" \| "swap" \| "fallback" \| "optional"` | - | Font-display policy. |
| `stretch?` | `string` | - | CSS stretch value. |
| `featureSettings?` | `string` | - | CSS feature settings. |
| `variationSettings?` | `string` | - | CSS variation settings. |
| `unicodeRange?` | `string[]` | - | Nonempty CSS unicode-range list. |

Local variants accept optional `weight` and `style`, plus `display`, `stretch`,
`featureSettings`, `variationSettings`, and `unicodeRange`. See [Fonts](/fonts)
for hosted and local examples and warning behavior.

## Logo specifications

`brand.logo` requires `logotype`, `brandmark`, `clearspace`, `minSize`, and
`colorways`. Optional fields are `favicon` and `pronunciation`.

| Object                  | Required fields                                                     | Optional fields |
| ----------------------- | ------------------------------------------------------------------- | --------------- |
| `logotype`, `brandmark` | `onLight`, `onDark` (file paths); `aspect` (numeric width / height) | `altText`       |
| `clearspace`            | `unit` (description), `ratio` (number)                              | —               |
| `minSize`               | `digital`, `print` (descriptive strings)                            | —               |
| Each `colorways` entry  | Unique `id`, `fg`, `bg` (color references)                          | `label`         |

The generated site otherwise references `/favicon.svg`. Keep the preferred
colorway first. See [Logos](/logos) for an example with artwork paths.

## Contact and downloads

`brand.contact` is required, but `{}` is allowed. Its optional fields are
`email`, `website`, `phone`, `address` (string array), and `socials`.
Each social entry requires a unique `id` plus `label`, `handle`, and `url`.
See [Contact and social profiles](/contact).

`brand.downloads` is optional. Entries require unique `id`, `label`, and `href`;
`format`, `size`, and `note` are optional display strings. Brandtree does not
create archives or calculate file sizes. See [Brand assets](/brand-assets).

## Localized brand copy

`brand.localeOverrides` is an optional record keyed by locale code. It requires
root `i18n`, and each key must be configured in `i18n.locales`.

Supported overrides are reader-facing metadata, palette names, swatch names and
usage, typography stacks and labels, logo text, address lines, social labels,
and download labels and notes. Array entries match canonical `id` values;
weight entries match their numeric `weight`. Unknown and duplicate identifiers
are invalid. Artwork paths, colors, URLs, measurements, and theme roles stay
canonical. See [Localization](/localization) for the complete workflow.

## Social preview settings

`seo.og` accepts the following fields:

| Prop | Type | Default | Description |
| - | - | - | - |
| `enabled?` | `boolean` | `true` | Generate per-page social cards. Explicit page SEO images still work when disabled. |
| `logo?` | `string \| false` | - | Local SVG override; false hides the logo. |
| `eyebrow?` | `string \| false` | - | Label above the headline; defaults to the localized site title. |
| `description?` | `string \| false` | - | Subtitle; defaults to the site description. |
| `site?` | `string \| false` | - | Footer site text; false hides it. |
| `palette?` | `{ accent?: string; background?: string; border?: string; foreground?: string; muted?: string }` | - | Actual CSS colors, unlike brand color-reference fields. |
| `titles?` | `Record<string, string>` | - | Card headlines for custom route paths. Content pages use their page title. |

See [Social cards and SEO](/social-cards) for generation and page-level overrides.

## Check your changes

Config validation checks unknown fields, duplicate IDs and weights, complete
schemes, color references, font variables, and locale references. It also reports
local asset warnings. See [Validation](/validation) for the checking workflow.
Visual review still matters for contrast, artwork, and typography.