Configuration

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

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.

PropType

brandBrandConfig

Structured identity, colors, themes, typography, logos, contacts, and optional downloads and translations.

TypeBrandConfig

fonts?FontConfig[]

Font loading declarations. An explicit array replaces the default; [] disables font downloads.

TypeFontConfig[]

DefaultInter (Google)

basePath?string

Route mount point such as /guidelines, normalized to an empty string or /segment. Does not add a sidebar group.

Typestring

Default""

navigation?{ numbering?: boolean }

Whether sidebar sections display numbers. See Navigation.

Type{ numbering?: boolean }

Default{ numbering: false }

i18n?I18nConfig

Opt-in locales, content parser, URL prefix policy, and fallback. See Localization.

TypeI18nConfig

seo?{ og?: OgConfig }

Generated social-card settings. See Social cards and SEO.

Type{ og?: OgConfig }

Default{ og: { enabled: true } }

Brand fields

PropType

metaBrandMeta

Identity and document metadata.

TypeBrandMeta

colors{ palette: PaletteFamily[]; swatches: Swatch[] }

Authored color values and approved brand swatches.

Type{ palette: PaletteFamily[]; swatches: Swatch[] }

theme{ default: 'light' | 'dark' | 'system'; light: Scheme; dark: Scheme }

Complete semantic color roles for both themes.

Type{ default: 'light' | 'dark' | 'system'; light: Scheme; dark: Scheme }

typographyBrandTypography

Font stacks, family descriptions, weights, and type scale.

TypeBrandTypography

logoBrandLogo

Artwork variants and usage specifications.

TypeBrandLogo

contactBrandContact

Optional public contact fields. An empty object is allowed.

TypeBrandContact

downloads?BrandDownload[]

Shared downloadable resources and their display metadata.

TypeBrandDownload[]

localeOverrides?Record<string, BrandLocaleOverride>

Reader-facing copy and typography stacks by configured locale code. Requires root i18n.

TypeRecord<string, BrandLocaleOverride>

Brand metadata

All paths below are relative to brand.meta.

PropType

namestring

Public brand name.

Typestring

legalName?string

Registered legal name.

Typestring

tagline?string

Short brand tagline.

Typestring

documentTitlestring

Guidelines document label.

Typestring

versionstring

Brand-document version, independent of the package version.

Typestring

yearnumber

Document year.

Typenumber

urlstring

Production origin used by the generated site and absolute metadata URLs.

Typestring

descriptionstring

Site description.

Typestring

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

PropType

idstring

Swatch identifier, unique within swatches.

Typestring

namestring

Visible color name.

Typestring

colorColorReference

Palette reference or black/white.

TypeColorReference

cmyk?[number, number, number, number]

Authored print specification.

Type[number, number, number, number]

pantone?string

Print reference label.

Typestring

usage?string

Short usage guidance.

Typestring

category?"primary" | "secondary"

Color category.

Type"primary" | "secondary"

span?1 | 2

Horizontal swatch span.

Type1 | 2

rows?1 | 2

Vertical swatch span.

Type1 | 2

on?ColorReference

Explicit swatch foreground.

TypeColorReference

The table describes an entry in brand.colors.swatches. See 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 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.

PropType

idstring

Stable style identifier, unique within scale.

Typestring

namestring

Visible style name.

Typestring

sizestring

CSS font size, including responsive clamp expressions.

Typestring

lineHeightstring

CSS line-height value.

Typestring

trackingstring

CSS letter-spacing value.

Typestring

font?"display" | "text"

Typography role.

Type"display" | "text"

weight?number

Font weight.

Typenumber

role?string

Short usage explanation.

Typestring

sample?string

Specimen text.

Typestring

transform?"none" | "uppercase" | "lowercase" | "capitalize"

Text transformation.

Type"none" | "uppercase" | "lowercase" | "capitalize"

print?{ size: string; leading: string; tracking: string }

Print specification. All three fields are required when present; this does not generate a PDF.

Type{ size: string; leading: string; tracking: string }

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

PropType

namestring

Nonempty provider family name.

Typestring

cssVariablestring

Unique CSS variable matching -- followed by a letter or underscore, then letters, numbers, underscores, or hyphens.

Typestring

Serializable Astro font-provider declaration.

id?string

Required nonempty Adobe project ID when provider is adobe; unsupported for other providers.

Typestring

options?{ variants: FontVariant[] }

Required for local fonts. Nonempty variants; each needs a nonempty src array relative to the client project root.

Type{ variants: FontVariant[] }

weights?(number | string)[]

Nonempty list; variable ranges use a string such as 100 900.

Type(number | string)[]

styles?("normal" | "italic" | "oblique")[]

Nonempty style list.

Type("normal" | "italic" | "oblique")[]

subsets?string[]

Nonempty provider subset list.

Typestring[]

formats?("woff2" | "woff" | "ttf" | "otf" | "eot")[]

Nonempty format list.

Type("woff2" | "woff" | "ttf" | "otf" | "eot")[]

fallbacks?string[]

CSS fallback family names.

Typestring[]

optimizedFallbacks?boolean

Whether to optimize fallback metrics.

Typeboolean

display?"auto" | "block" | "swap" | "fallback" | "optional"

Font-display policy.

Type"auto" | "block" | "swap" | "fallback" | "optional"

stretch?string

CSS stretch value.

Typestring

featureSettings?string

CSS feature settings.

Typestring

variationSettings?string

CSS variation settings.

Typestring

unicodeRange?string[]

Nonempty CSS unicode-range list.

Typestring[]

Local variants accept optional weight and style, plus display, stretch, featureSettings, variationSettings, and unicodeRange. See 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 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.

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.

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 for the complete workflow.

seo.og accepts the following fields:

PropType

enabled?boolean

Generate per-page social cards. Explicit page SEO images still work when disabled.

Typeboolean

Defaulttrue

logo?string | false

Local SVG override; false hides the logo.

Typestring | false

eyebrow?string | false

Label above the headline; defaults to the localized site title.

Typestring | false

description?string | false

Subtitle; defaults to the site description.

Typestring | false

site?string | false

Footer site text; false hides it.

Typestring | false

palette?{ accent?: string; background?: string; border?: string; foreground?: string; muted?: string }

Actual CSS colors, unlike brand color-reference fields.

Type{ accent?: string; background?: string; border?: string; foreground?: string; muted?: string }

titles?Record<string, string>

Card headlines for custom route paths. Content pages use their page title.

TypeRecord<string, string>

See Social cards and SEO 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 for the checking workflow. Visual review still matters for contrast, artwork, and typography.