Skip to main content

The design system

Kiln's UI grew a real palette early — with adaptive light and dark themes — but everything else was inline magic numbers: font sizes from 9 to 14 repeated across hundreds of call sites, ad-hoc paddings, corner radii written as bare numbers. This page covers the move toward naming those values, a shared component family, and visual regression tests that guard how the components look.

The work is deliberately additive. Old code continues to work alongside new code, so views adopt the scale at their own pace.

Tokens​

Three scales define the UI's semantic values:

  • Typography — semantic type roles (label, caption, footnote, callout, body, headline) plus display(_:) for the Instrument Serif face and code(_:) re-exporting JetBrains Mono. A size or weight change for a role happens once.
  • Space — a 4-pt spacing scale (xxs 2 → xxl 32). Round to the nearest step when adopting; keep a literal where nothing fits rather than bending the layout.
  • Radius — corner radii (sm 3 for inline code chips, md 8 for cards, lg 12 for popovers).

Tokens and colour themes work together as the UI language.

Themes​

Kiln ships a family of named palettes rather than one fixed pair of faces. The app picks one light theme and one dark theme:

  • Light: Cream (the original warm paper) and Kiln (its eponymous twin), Cloud (a cool monochrome white), VS Code (Light+), Lime White (a green-tinged white), Blush (a pink tinge), Claudius (Claude's brand — ivory paper, slate ink, a coral accent), and Porcelain (hand-painted delftware — cobalt blue ink and accents on speckled cream stoneware).
  • Dark: Coffee (the original espresso) and Kiln Dark (its eponymous twin), Terracotta (warm clay), Gunmetal (a near-monochrome graphite, the Cursor-style black), Navy (deep blue), Willow (a muted forest), VS Code (Dark+), Claudius (Claude's brand — a near-black cinder canvas, ivory ink, the signature Claude coral), and Porcelain (a delftware night — cream ink and a cobalt glow on a deep blue-black canvas).

Both are chosen in Settings ▸ General. Switching themes recolors the whole app instantly, including the syntax highlighter.

The pill family​

The editor's marginalia chips — story chips, the imports and collapse folds — all use a unified design: a faint tint fill inside a capsule, ringed by a slightly stronger tint hairline. This lets the whole family tune from one place.

Kiln has a built-in component catalog that documents each UI element and tests how it looks. New components are documented and visually verified by adding them to the catalog.

Visual regression testing​

Components are visually regression-tested under both light and dark themes to catch accidental restyling. The catalog includes reference screenshots that verify each component looks correct.