Skip to content
buildspace

Guidelines / v2.0

The system, in writing.

BuildSpace v2 — the full design.md reference behind every item in this registry.

Download design.md

Read this file before styling. The full machine-readable token set, including Night and all semantic accent values, is tokens.json. The showcase and installable theme use the same local CSS sources, checked at build time. llms.txt indexes every installable item and its guide.

Direction

A drawing set, not a sticker book. Warm canvas, ink, rules, dimension lines, and a few flat colored modules. Calm, spacious, purposeful.

This edition adapts the enterprise-portal v2 design system and the current buildspace.tech brand assets. Mint is the default field; the violet wordmark dot follows the supplied website artwork (the original system's default dot was green). Do not recolor the supplied logos.

Scope: this is the public UI registry's v2 contract. Other BuildSpace apps and the monorepo's shared UI package are not migrated by this release.

Color

Canvas and ink carry roughly 90% of the page. Use roles, not raw hex values:

One field color per screen. A field band, featured card, selected nav row, and selected control may share it; never put competing field families side by side. The palette specimen intentionally shows alternatives, not an example layout.

Status is meaningful, not decorative: success (mint), warning (butter), progress / info (lilac), danger (rose). Pair a label or icon with color. Six compatibility accent families remain available with soft, bg, icon, bright, text, and dot tones. Use *-text only on its own *-bg or *-soft. Bright values are not body text colors.

Typography

Short declarative headlines end with a period. Sentence-case headings and body, Title Case CTAs. No hype, invented customers, metrics, or case studies. Mark example data and product mockups as illustrative.

Load all four fonts yourself; a CSS font-family does not download a font. In Next.js use next/font/google, exposing --font-loaded-display, --font-loaded-sans, --font-loaded-serif, and --font-loaded-mono. Include DM Serif Display's italic face. Or add this before other CSS rules:

@import url("https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@500;700;800&family=Instrument+Sans:wght@400;500;600&family=DM+Serif+Display:ital@0;1&family=JetBrains+Mono:wght@400;500&display=swap");

Layout

Use a 4px spacing scale. Site max width: 1360px. Fluid gutters: clamp(20px, 4vw, 56px). Section spacing: clamp(64px, 8vw, 120px). Product UI can be denser: page titles 2–2.75rem, card titles 1.125rem.

Split sections pair an eyebrow and headline on the left with support copy on the right. Sections separate with 1px line rules. The workhorse list has a 1px ink top rule, quiet row separators, and a trailing arrow for actionable rows. Dashed lines are construction lines or add-another slots, not decoration. The drawing grid belongs inside figures, never behind a whole page.

Surfaces and motion

Flat. Paper cards have a 1px line border, no shadow. A hovered tile may swap line to ink; reserve a persistent ink outline for the one thing to act on. Never colored left borders.

Components

Installable brand primitives:

Product primitives:

<h1 className="font-heading text-5xl">
  Built around your <em>business.</em>
</h1>
<FieldBand>
  <h2>Your next <em>step.</em></h2>
</FieldBand>
<DrawingFrame caption="Fig. 01 — Building blocks." sheet="DS / 001">
  <div className="flex min-h-48 items-center justify-center">
    <Glyph shape="arch" size={80} />
  </div>
</DrawingFrame>

Brand assets

Use the actual outlined artwork, selected for the background it sits on:

The artwork is copied from buildspacetech, not redrawn. Keep its violet dot and module mark intact. Do not stretch, recolor, rotate, outline, or add shadows. Give the wordmark at least its dot diameter of clear space and keep it legible. In copy write BuildSpace, not Buildspace or Build Space. The logotype is lowercase by design.

Legacy /brand/buildspace-logo.svg and /shapes/*.webp remain at their old URLs for compatibility only. They are not v2 assets. Do not use the old bracket mark or 3D shapes in new work.

Night

Canvas #141312, surface #1A1918, card #1F1D1B, warm ink #F6F3EE. Primary swaps to warm paper with dark text. Field becomes deep mint. Status fills become deep tints with light text. Shape pastels stay light inside drawings. Borders and a real hierarchy do the work, not dimmed opacity. Use a .dark ancestor; the optional theme-toggle item handles persistence.

Install

Prerequisites: a React project with Tailwind CSS v4 and initialized shadcn/ui. First merge this into components.json (preserve your existing settings):

{
  "registries": {
    "@buildspace": "https://ui.buildspace.studio/r/{name}.json"
  }
}

Load the four fonts, then install the theme:

npx shadcn@latest add https://ui.buildspace.studio/r/buildspace.json
npx shadcn@latest add https://ui.buildspace.studio/r/glyph.json

Stock shadcn components inherit the theme via data-slot CSS. All accent tokens are included; theme-accents is a compatibility alias. Pick individual items from llms.txt, or use the blocks and chat-kit bundles. Every /r/<name>.md guide lists exact dependencies and files.

Registry source installs into a standard @/-aliased app. In a shared UI package, rewrite internal @/ imports to relative paths after installation; an app-level alias otherwise points at the wrong tree.

Migration

v2 replaces the registry's old Ink & Paper contract. Commit local changes before reinstalling; review the CLI diff and theme CSS rather than accepting an overwrite blindly. This is opt-in for existing consumers.

  1. Load Bricolage Grotesque and Instrument Sans instead of DM Sans.
  2. Change whole font-serif headings and stat numbers to font-heading. Keep serif only on the one italic phrase.
  3. Remove inline offset shadows, lift transforms, tilted stickers, colored italics, old bracket logos, and 3D imagery.
  4. Replace card fills with paper; keep one mint field moment.
  5. Use sentence-case status badges. Warning is butter; info/progress is lilac.
  6. Verify light and Night, keyboard focus, and narrow screens.

Existing item names and URLs are retained. btn-lift now stays flat. The old logo-mark item is a compatibility entry; use wordmark and the published brand artwork for current identity.

Accessibility

Agent entry points

Before finishing: one field, flat edges, same-color italic, correct logo, real font faces, visible focus, Night, mobile, and reduced motion.

Raw design tokens (YAML frontmatter)
version: "2.0"
name: BuildSpace
description: "Architectural, engineered, warm: Bricolage headlines, one serif italic phrase, flat surfaces, 1px rules, geometric modules."
canonical: https://ui.buildspace.studio/design.md
tokens: https://ui.buildspace.studio/tokens.json
css: https://ui.buildspace.studio/theme.css
colors:
  canvas: "#F6F3EE"
  surface: "#FBF9F6"
  paper: "#FFFFFF"
  ink: "#121212"
  ink-2: "#3A3733"
  muted: "#6E675F"
  line: "#DDD6CC"
  line-soft: "#EEE9E2"
  grid: "#ECE7E0"
  field-mint: "#D9F0E2"
  field-lilac: "#E6DAFA"
  field-sky: "#D7ECF7"
  field-peach: "#FCE3D3"
  shape-lilac: "#DCCBF5"
  shape-mint: "#BDE8CD"
  shape-peach: "#F9CDB0"
  shape-sky: "#BFE2F4"
  shape-butter: "#F8E39A"
  dot: "#7452DB"
  success: "#26733F"
  success-bg: "#D9F0E2"
  warning: "#8F6B24"
  warning-bg: "#FCF3C5"
  progress: "#5B2F80"
  progress-bg: "#E6DAFA"
  danger: "#B3362B"
  danger-bg: "#FBE0DA"
colors-dark:
  canvas: "#141312"
  surface: "#1A1918"
  card: "#1F1D1B"
  ink: "#F6F3EE"
  muted: "#A39C93"
  line: "#3D3A36"
  field: "#1F3A2B"
typography:
  display: { fontFamily: "Bricolage Grotesque", fontWeight: 800, lineHeight: 0.98, letterSpacing: "-0.045em" }
  heading: { fontFamily: "Bricolage Grotesque", fontWeight: 700, lineHeight: 1.05, letterSpacing: "-0.03em" }
  accent: { fontFamily: "DM Serif Display", fontStyle: italic, fontWeight: 400 }
  body: { fontFamily: "Instrument Sans", fontWeight: 400, lineHeight: 1.5 }
  label: { fontFamily: "JetBrains Mono", fontSize: "10.5px", letterSpacing: "0.08em", textTransform: uppercase }
rounded:
  control: 10px
  button: 999px
  chip: 999px
  row: 8px
  card: 16px
  band: 24px
  drawing: 4px