@gitbutler/design-core

Design tokens and fonts for GitButler applications. This package provides CSS custom properties, design tokens in JSON format, and web fonts used across GitButler products.

Installation

npm install @gitbutler/design-core

Usage

Single Import

The easiest way to get everything — fonts, CSS reset, text utilities, and design tokens:

@import "@gitbutler/design-core/core";

Or in JavaScript/TypeScript:

import "@gitbutler/design-core/core";

Design Tokens (CSS)

Import only the design tokens CSS file:

@import "@gitbutler/design-core/tokens";

Or in JavaScript/TypeScript:

import "@gitbutler/design-core/tokens";

This provides CSS custom properties for colors, spacing, typography, and other design tokens with automatic light/dark mode support.

Fonts

Import all font declarations:

@import "@gitbutler/design-core/fonts";

Or reference individual font files directly:

@import "@gitbutler/design-core/fonts/inter/Inter-Variable.woff2";
@import "@gitbutler/design-core/fonts/geist-mono/GeistMono-Variable.woff2";
@import "@gitbutler/design-core/fonts/but-head/But-Head-Regular.woff2";

Styles

Import individual style sheets:

@import "@gitbutler/design-core/styles/reset"; /* CSS reset */
@import "@gitbutler/design-core/styles/text"; /* Text utilities */

CSS Reset

The reset is scoped to @layer reset to avoid specificity conflicts with application styles. It applies the following normalizations:

• Box sizing — box-sizing: border-box on all elements and pseudo-elements.
• Font rendering — -webkit-font-smoothing: antialiased, -moz-osx-font-smoothing: grayscale, text-rendering: optimizeLegibility, and font size inflation prevention on html.
• Body defaults — zero padding and margin, overflow-x: hidden, and base values for color, font-family, font-weight, and line-height pulled from design tokens.
• Form elements — input, textarea, select, and button have their padding, border, and background stripped, and inherit color and font from the parent.
• Headings — h1–h6 have margin-block removed.
• Code & pre — code and pre use var(--fontfamily-mono).
• Lists & paragraphs — ul and ol have padding-left and list-style removed; ul, pre, and p have margin-block removed.

Text Utilities

Text classes are scoped to @layer text. The layer also sets three font-family custom properties on :root:

Property	Value
--fontfamily-base	var(--text-fontfamily-base), sans-serif
--fontfamily-mono	var(--text-fontfamily-mono), monospace
--fontfamily-accent	var(--text-fontfamily-accent), serif

Size classes set font-size, font-weight: regular, line-height, and font-family: base as a self-contained unit:

Class	Font size
.text-10	10px (0.625rem)
.text-11	11px (0.6875rem)
.text-12	12px (0.75rem)
.text-13	13px (0.8125rem)
.text-14	14px (0.875rem)
.text-15	15px (0.938rem)
.text-16	16px (1rem)
.text-accent-head	62px (3.875rem) — display / brand heading

Modifier classes are designed to be composed on top of a size class:

Class	Effect
.text-semibold	font-weight: var(--text-weight-semibold)
.text-bold	font-weight: var(--text-weight-bold)
.text-italic	font-style: italic
.text-monospace	Switches to var(--fontfamily-mono)
.text-body	Switches to the looser var(--text-lineheight-body) line height
.text-balance	text-wrap: balance — ideal for short headings
.text-pre	white-space: pre-wrap + word-break: break-word — preserves whitespace without overflow

Example usage:

<p class="text-13 text-semibold">Label</p>
<code class="text-12 text-monospace">git commit</code>
<h1 class="text-accent-head text-italic">GitButler</h1>

Available Exports

• @gitbutler/design-core/core - Single import: fonts + reset + text utilities + tokens
• @gitbutler/design-core/tokens - CSS custom properties (design tokens)
• @gitbutler/design-core/fonts - All font CSS declarations
• @gitbutler/design-core/fonts/* - Individual font files
• @gitbutler/design-core/styles/reset - CSS reset
• @gitbutler/design-core/styles/text - Text utility classes

Included Fonts

All fonts are variable fonts unless noted.

• Inter — Primary UI font (Inter-Variable.woff2, Inter-Variable-Italic.woff2)
• Geist Mono — Monospace font for code (GeistMono-Variable.woff2)
• But Head — Brand display font (But-Head-Regular.woff2, But-Head-Italic.woff2)

Development

This package uses Terrazzo to generate CSS custom properties from design tokens.

# Install dependencies
npm install

# Build tokens
npm run build

# Watch for changes
npm run dev:tokens

Color Tool

hue-dini is the tool used to preview and export the GitButler color palette. It applies a single shared luminance scale across all hues — gray, accent, and semantic — so shades at the same step feel visually equivalent regardless of hue.

Live: https://gitbutlerapp.github.io/design-core/

cd tools/hue-dini
pnpm install
pnpm dev

See tools/hue-dini/README.md for more details.