basecoat/docs/src/customization.md

templateEngineOverride, layout, title, description, icon, toc

templateEngineOverride	layout	title	description	icon	toc
njk	layouts/page.njk	Customization	Configure icons, themes, fonts, and style overrides.	settings-2	label id Icons icons label id Theming theming label id Fonts fonts label id Custom styles custom-styles label id Style overrides style-overrides

{% from "macros/code_block.njk" import code_block %}

Icons

Basecoat uses Lucide icons. You have three options:

• Copy SVG code: Visit lucide.dev/icons, click any icon to copy the SVG, and paste it directly in your HTML. Best for simple projects or occasional icon usage.
• Install lucide: Follow the installation guide to install the lucide package and dynamically render icons. Best for projects that need many icons or want tree-shaking.
• Use framework packages: Browse framework-specific packages (React, Vue, Angular, etc.) for component-based icon usage. Best if you're using a supported framework.

Browse icons {% lucide "arrow-right" %} Installation guide {% lucide "arrow-right" %} Packages {% lucide "arrow-right" %}

Theming

You can import any shadcn/ui compatible theme (e.g. tweakcn). For example:

• Go to ui.shadcn.com/themes and select a theme.
• Click "Copy code" and save the theme variables in a file (e.g. theme.css).
• Import the theme in your CSS file: {% set code %}@import "tailwindcss"; @import "basecoat-css/sera"; @import "./theme.css";{% endset %} {{ code_block(code, "css") }}

About shadcn/ui theming {% lucide "arrow-right" %}

Fonts

Basecoat does not ship web fonts by default. The Basecoat docs site uses the same font choices as the current shadcn/ui site: Geist Sans for sans and heading text, and Geist Mono for monospace text.

To use the same setup, load the fonts and override the font tokens after importing Basecoat:

{% set code %}@import "tailwindcss"; @import "basecoat-css/sera"; @import "@fontsource/geist-sans/400.css"; @import "@fontsource/geist-sans/500.css"; @import "@fontsource/geist-sans/600.css"; @import "@fontsource/geist-sans/700.css"; @import "@fontsource/geist-mono/400.css"; @import "@fontsource/geist-mono/500.css"; @import "@fontsource/geist-mono/600.css"; @import "@fontsource/geist-mono/700.css";

:root { --font-sans: "Geist Sans", ui-sans-serif, system-ui, sans-serif; --font-heading: "Geist Sans", ui-sans-serif, system-ui, sans-serif; --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }{% endset %} {{ code_block(code, "css") }}

Keep font overrides in a small CSS file imported after Basecoat. This makes fonts a project-level customization instead of a Basecoat package default.

Custom styles

Basecoat style packs combine shared Basecoat structure with visual rules for each component. If you want to write a full custom style, import the styleless Basecoat base and then your own style file.

{% set code %}@import "tailwindcss"; @import "basecoat-css/base"; @import "./style-acme.css";{% endset %} {{ code_block(code, "css") }}

basecoat-css/base includes Basecoat tokens, semantic utilities, and component structure, but no Vega/Nova/Maia/etc. visual style pack. Your style file is responsible for component visuals such as colors, radius, shadows, focus rings, spacing, and variant treatment.

The practical way to start is to copy one existing style pack, rename it, and edit from there. The style files live in src/css/styles/ and are also published under basecoat-css/styles/*.

{% set code %}@import "basecoat-css/base"; @import "./style-acme.css";

/* style-acme.css can start as a copy of basecoat-css/styles/nova. */{% endset %} {{ code_block(code, "css") }}

Do not load a full Basecoat style bundle and then override it wholesale. For example, avoid importing basecoat-css/nova before your custom style. That loads Nova component visuals and forces your file to undo them. Use basecoat-css/base instead.

Style overrides

You can override default styles using Tailwind:

{% set code %}Click me{% endset %} {{ code_block(code, "html") }}

You can also extend or override the existing styles in your own Tailwind files:

{% set code %}@import "tailwindcss"; @import "basecoat-css/sera"; @import "./custom.css";{% endset %} {{ code_block(code, "css") }}

More importantly, you can use the theme variables to customize many aspects of the components (colors, fonts, sizes, etc).

If you want to make more drastic changes, you can copy the basecoat.css file into your project and make your changes there.