Visual Customization

Global Configuration#

Edit brief/config/visuals.ts to customize Brief's appearance.

import { defineVisuals } from '@brief/ui/config/visuals'
import { GEIST, GEIST_MONO } from '@brief/ui/fonts'
import { OUTLINE_DUO_ICONS } from '@brief/ui/icons/interface-icons/outline-duo'

export default defineVisuals({
  interfaceIcons: OUTLINE_DUO_ICONS,
  logo: {
    light: '/logo-light.svg',
    dark: '/logo-dark.svg',
    href: 'https://example.com',
  },
  tokens: {
    colors: { accent: 'cyan', base: 'zinc' },
    radius: 'large',
    typography: {
      body: { family: GEIST },
      code: { family: GEIST_MONO },
    },
  },
  layout: {
    sidebar: { variant: 'tracker-line' },
    toc: { variant: 'tracker-dot' },
  },
  components: {
    callout: { variant: 'quote-card' },
    code: { frame: 'debossed' },
  },
})

Branding#

Colors#

Built-in palettes include blue, cyan, violet, zinc, and slate. Brief selects shades for light and dark mode automatically.

Background#

Typography#

Import bundled fonts from @brief/ui/fonts.

Borders and Shadows#

Navigation#

Component-Specific Styles#

Icons#

There are two sets of icons in the application:

1. Interface icons are used for icons baked into Brief's layout like the theme toggle or the generic copy icon across all components.
2. Content icons can be used by in-page components like Icon, Badge, and Callout.

Interface Icons#

Customize interfaceIcons to set the interface icons. Make your own bundle of icons or choose from one of the default bundles.

Content Icons#

Content icons are SVG components that forward their SVG props and use currentColor.

Register content icons in the icons map in brief/config/visuals.ts. Each icon's key can then be referenced and used in authors' pages.

export default defineVisuals({
  interfaceIcons: OUTLINE_DUO_ICONS,
  icons: { star: StarIcon },
})

You can then start using it in certain components across all pages.

:Icon{name="star"}
:Badge[Favorite]{icon="star"}

Individual Page Customization#

Pages have individual settings that can be customized via their frontmatter.

---
title: Product Overview
description: Explore the product's features and architecture.
content_width: large
toc: false
---

Custom Components#

For a rendered component with authored attributes, use these registration fields:

import type { z } from 'zod'

import type { releaseLabelSchema } from './releaseLabelSchema'

interface ReleaseLabelProps extends z.infer<typeof releaseLabelSchema> {}

export function ReleaseLabel({ version }: ReleaseLabelProps) {
  return <p>Available in version {version}.</p>
}

import { z } from 'zod'

export const releaseLabelSchema = z.object({ version: z.string().min(1) })

import { lazy } from 'react'

import { ComponentRegistry, defineComponent } from '@brief/ui/components'

import { releaseLabelSchema } from '../components/releaseLabelSchema'

export default new ComponentRegistry().with({
  ReleaseLabel: defineComponent({
    component: lazy(() =>
      import('../components/ReleaseLabel').then((module) => ({ default: module.ReleaseLabel })),
    ),
    schema: releaseLabelSchema,
    search: ({ node: [, { version }] }) => ({
      text: `Available in version ${version}.`,
    }),
    markdown: ({ node: [, { version }] }) => [
      ['p', {}, `Available in version ${version}.`],
    ],
  }),
})

You can then start using the registered component:

::ReleaseLabel{version="2.0"}
::