Design System

Overview

The shipped theme is BuildPad brand — Ink & Ember, aligned with buildpad.ai : ink (#0a0a0b) is the primary action colour (a Button with no color renders as a black pill), ember orange (#e86a00) is the brand accent for interactive state and highlights, on cool neutral greys. Headings use Inter Tight, body text Inter, code JetBrains Mono. See the Styleguide for every token rendered live.

The design system has three layers:

1. Design tokens in app/design-tokens.css (single source of truth)
2. Mantine theme mapping in lib/theme.ts (tokens → component defaults)
3. Global overrides in app/globals.css (Mantine class-level tweaks)

Token Strategy

Tokens use the --ds- prefix and CSS custom properties so themes can be swapped without rebuilding.

:root {
  --ds-primary: #e86a00;          /* ember — brand accent */
  --ds-secondary: #2a2b31;        /* ink */
  --ds-gray-600: #54555d;
  --ds-cta-bg: #0a0a0b;           /* default Button */
  --ds-font-display: "Inter Tight", var(--ds-font-sans);
  --ds-spacing-4: 1rem;
  --ds-radius: 0.5rem;
}

Mantine Theme Mapping

lib/theme.ts maps token values into Mantine, so all components inherit system defaults automatically.

import { createTheme } from "@mantine/core";
 
export const theme = createTheme({
  primaryColor: "primary",
  fontFamily: "var(--ds-font-family)",
  spacing: {
    sm: "var(--ds-spacing-4)"
  }
});

Dark Mode

Dark mode is handled with the [data-mantine-color-scheme="dark"] selector in design-tokens.css. Mantine uses ColorSchemeScript and defaultColorScheme="auto" in the root layout. The numbered scales mirror (50↔950, …) so light-authored tokens stay legible, ink inverts to light greys, and the CTA flips to a light pill with ink text.

How to Customize

1. Update token values in app/design-tokens.css
2. Extend lib/theme.ts for component-level defaults
3. Add any global overrides in app/globals.css

Delivery & upgrades

These files are scaffolded by buildpad init/bootstrap as the design-system lib module (design-tokens.css, globals.css, theme.ts, plus the ColorSchemeToggle and AuthenticatedShell app shell) and tracked in buildpad.json. To pull a newer design from the registry without losing your customizations:

buildpad upgrade --design              # refresh tokens/theme/globals/shell
buildpad upgrade --design --three-way  # merge your local token edits

Your edits are preserved via three-way merge (or written as .new) — pristine files overwrite cleanly. buildpad outdated reports the module when it’s behind. See the CLI docs for details.