Guidelines / v2.0
The system, in writing.
BuildSpace v2 — the full design.md reference behind every item in this registry.
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:
background: canvas;surface: rails and alternating sections.card/popover: paper. Night swaps them for warm dark surfaces.foreground/primary: ink. Primary text usesprimary-foreground.muted-foreground: secondary text.border/input: the quiet 1px line.field/field-foreground: the one field-color moment, mint by default.dot: the violet brand signature and a single focal point in a drawing.shape-*: immutable pastel fills only inside glyphs and drawings.
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
- Bricolage Grotesque: display at 800, −4.5% tracking, line-height 0.98;
headings at 700, −3% tracking, line-height 1.05. Use
font-heading. - DM Serif Display italic: exactly one accent word or phrase in a
headline, in the same color as its line. Use
<em>; never an all-serif heading or a colored italic word. - Instrument Sans: body, controls, navigation, and badges. 14–16px body,
line-height 1.5. Use
font-sans. - JetBrains Mono: eyebrows, table headers, timestamps, code, and drawing annotations. Labels are 10.5px, uppercase via CSS, +8% tracking.
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.
- Controls: 10px. Product cards, menus, dialogs: 16px.
- Field bands: 24px. Drawing frames: 4px. Buttons and chips: pills.
- Primary buttons darken ink to ink-2 on hover.
- Outline buttons fill with ink; links shift to muted.
- No hover lift, scale, tilt, parallax, bounce, entrance choreography, or 3D.
- Product press feedback may scale to 0.97. Disable for reduced motion.
- Color transitions: 200ms. Overlays: enter 200ms, exit 150ms.
- Only overlays use
shadow-overlay: menus, popovers, dialogs, sheets, toasts. - No gradients or texture on UI chrome. No glass; only a sticky nav may blur.
Components
Installable brand primitives:
- Glyph: arch, block, quarter, circle, pill, steps. CSS shapes
with a 1px ink outline. Decorative (
aria-hidden), for identity, not actions. - Wordmark: lowercase Bricolage 800, −6% tracking, dot at 0.3× font size; work/team use grotesk 500, studio uses serif italic.
- Drawing frame: contained grid, corner crosshairs, mono figure caption (“Fig. 01 — …”), sheet number.
- Field band: one mint field-color moment with a 24px radius.
Product primitives:
- Buttons: ink primary, ink-outline secondary, quiet line-outline actions, low-emphasis ghost. Straight and stable.
- Inputs: paper, 10px radius, line border. Focus turns border ink plus a halo.
- Badges: sentence-case Instrument Sans, 12px semibold; no mono sticker shadow.
- Sidebar rows: sentence-case labels, line icons or identity glyphs; field selected state, semibold text.
- Menus: neutral hover fill, mono group labels. Tables: mono headers and rules.
- Code blocks sit on ink. Empty states get a clear next action.
- Lucide action icons use a 1.5px stroke. Use a published vendor logo when naming a vendor; never invent a logo or use emoji.
<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.
- Load Bricolage Grotesque and Instrument Sans instead of DM Sans.
- Change whole
font-serifheadings and stat numbers tofont-heading. Keep serif only on the one italic phrase. - Remove inline offset shadows, lift transforms, tilted stickers, colored italics, old bracket logos, and 3D imagery.
- Replace card fills with paper; keep one mint field moment.
- Use sentence-case status badges. Warning is butter; info/progress is lilac.
- 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
- Body text contrast at least 4.5:1. Meaningful large text and UI outlines at least 3:1. Check each actual foreground/background pair.
- Keyboard access and visible focus on every interactive element.
- Label inputs. Use buttons for actions and links for navigation.
- Aim for 44px touch targets. No clipped controls or page-level horizontal scrolling on a 320px viewport.
- Never rely on color alone for state. Use text, icons, and
aria-pressedor native checked semantics as appropriate. - Keep decorative glyphs hidden from assistive technology; caption figures.
- Honor
prefers-reduced-motion. No press scale or gratuitous motion.
Agent entry points
- design.md: the contract, always markdown.
- llms.txt: complete manifest-driven install index.
- tokens.json: full light, Night, and Tailwind tokens.
- theme.css: tokens and component rules; use with Tailwind v4.
/r/<name>.json: installable shadcn item./r/<name>.md: plain-markdown setup, dependencies, files, and usage notes./withAccept: text/markdown: this same design contract (Vary: Accept).
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